Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a83f04be5c |
@@ -1,54 +0,0 @@
|
||||
---
|
||||
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,55 +0,0 @@
|
||||
---
|
||||
name: hand-pack-builder
|
||||
description: Builds one hand pack of the Novox mesh - a folder holding one module's bundle (or a few), built from a repository commit the way the Go build module builds it, with SHA256SUMS, the build script and NOTES.md naming the exact placement steps - for a hand placement the lead says to the operator first. Places it on a node only when the caller asks for that in a later message. Never builds in a developer's worktree, never commits or pushes in a code repository.
|
||||
tools: Read, Grep, Glob, Bash, Write, Edit, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
|
||||
model: opus
|
||||
---
|
||||
|
||||
You build one hand pack for the lead who started you. A hand pack is a folder of built artifacts that a person puts on
|
||||
a node by hand, a hand act, when the delivery cannot bring them: most often a circle, where the fix is the very bundle
|
||||
the node-engine cannot fetch or the pipeline cannot pass without it. The handover names the module and its artifacts
|
||||
(`<module>:<artifact>`), the repository and the commit, the node, the pack's folder, the pack it is built like, and the
|
||||
read that confirms the cause.
|
||||
|
||||
**Confirm the cause first, read only.** Before you build, do the read the handover names: the seat's verb through the
|
||||
mesh MCP server (`mesh_search` finds it), the store or the journal it names. Say what it answered, what that means, and
|
||||
whether the pack answers that cause. When it does not, stop and report before building.
|
||||
|
||||
**Build like the earlier pack.** Read the earlier pack's NOTES.md and its build script or go.work files, and the pack it
|
||||
points to. Then:
|
||||
|
||||
- Make your own worktree of the repository, detached at the named commit, under hq's `.work/` with the name the
|
||||
handover gives; never build in a developer's worktree or a working copy's checkout. Siblings the build needs (the
|
||||
mesh packages of other repositories) come from their `origin/main`, in worktrees of your own or in checkouts the
|
||||
earlier pack used when they sit at `origin/main` and are clean; say each sibling's commit.
|
||||
- Build as the Go build module builds: `CGO_ENABLED=0`, `GOFLAGS="-trimpath -buildvcs=false"`,
|
||||
`-ldflags "-s -w -X main.builtFor=<system>"`, `GOTOOLCHAIN=local`, no version stamped, the mesh packages placed by a
|
||||
go.work file kept in the pack. Run the unit tests of the packages the commit changed.
|
||||
- Write the build as a script in the pack that refuses a worktree not at the commit and is loud on failure; run it
|
||||
twice and say whether the sha256 is the same.
|
||||
- Prove the artifact: a tools bundle answers `initialize` and `tools/list` over stdio (say the count and the tools the
|
||||
fix concerns); a program carries what the fix adds (a string, a flag). When the delivery released the same commit
|
||||
already, fetch the released artifact from the registry and compare: same source, and why the bytes differ if they do.
|
||||
- Write `SHA256SUMS` over every file of the pack.
|
||||
|
||||
**NOTES.md says the placement whole**, so the lead can say it to the operator and a person can run it without asking:
|
||||
|
||||
- What each file is, from which repository, commit and directory, its size; the siblings and the toolchain.
|
||||
- Why: the cause as read, with the digests or the lines read and the time read, and the circle the pack breaks.
|
||||
- Where each file goes on the node, read from the unit or the tool runner's module list there (never assumed), with the
|
||||
file's present sha256, owner and mode; the old file kept once beside it as `<file>.pre-h1`, the new one put with the
|
||||
same owner and mode through a temporary name and a rename.
|
||||
- Which units restart, in which order, and the check after each that must pass before the next step (a verb's answer,
|
||||
a unit's state).
|
||||
- How the node-engine's have of the module comes to the released fingerprint: read in the node-engine's code on main
|
||||
whether it asks again on its own, on its verb `compose`, or only after a restart, and name the function that decides.
|
||||
- The undo, and the notifications the steps may raise.
|
||||
|
||||
**Placing**, only when the caller asks for it in a later message, after the lead has said it to the operator: copy the
|
||||
pack to the node, check `SHA256SUMS` there, run the steps of NOTES.md one by one and read each check; stop at the first
|
||||
that fails and report it. Reading a node by a shell is allowed only on the days the operator allows it; otherwise
|
||||
through the mesh MCP server alone.
|
||||
|
||||
Report in under 500 words: the cause's read and what it means, the pack's folder, its sha256 lines, the placement steps
|
||||
in order, what you could not read or prove, and any finding (a fault the pack works around) for the lead to note on
|
||||
the issue that covers it. Separate fact from guess, in the glossary's words.
|
||||
@@ -26,10 +26,6 @@ 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
|
||||
|
||||
@@ -23,12 +23,6 @@ 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,9 +25,7 @@ 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).
|
||||
- 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).
|
||||
- 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.)
|
||||
- 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,
|
||||
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
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.
|
||||
+4
-57
@@ -306,9 +306,7 @@ controller and the store; for module assignment, by the seat `mesh-module-assign
|
||||
- **transport fault** — a failure of a call or a step because the part it asks did not answer for a moment, not
|
||||
because of what it asked: a name lookup that timed out; a connection refused, reset or unreachable; a seat verb
|
||||
answered with no responders while a holder of that seat is named in the assignments (ADR 0664 §1); and, for a call,
|
||||
its own deadline passing (ADR 0668 §1); a holder's `away` to a seat ask, its word that a part it depends on did
|
||||
not answer, naming that part (ADR 0668 §1, ADR 0664 §1, insights of 2026-11-21); and a 401 or 5xx answer of the forge to
|
||||
a step's fetch of its source (ADR 0664 §1, insight of 2026-11-21). A build or check step that meets one is given again by the bus, at most
|
||||
its own deadline passing (ADR 0668 §1). A build or check step that meets one is given again by the bus, at most
|
||||
three runs (ADR 0664 §1, §2); a kept call is called again. A fault in what was asked (a compile error, an unknown
|
||||
revision, a seat no holder is named for) is not one, and ends the step or the call at once.
|
||||
*Not:* ~~transient error~~ (hq), ~~network blip~~ (hq)
|
||||
@@ -602,46 +600,7 @@ 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; 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)
|
||||
placement may choose for a node; registering one the forge does not protect is refused (ADR 0666 §3, §6).
|
||||
- **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
|
||||
@@ -661,15 +620,6 @@ 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
|
||||
@@ -857,8 +807,7 @@ 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). 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).
|
||||
(ADR 0666 §13).
|
||||
- **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
|
||||
@@ -932,9 +881,7 @@ 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). 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).
|
||||
there too until the group's end, as members still gathered (§4).
|
||||
- **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
|
||||
|
||||
+3
-12
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: canonical
|
||||
updated: 2026-11-16
|
||||
updated: 2026-11-11
|
||||
---
|
||||
|
||||
# The principles
|
||||
@@ -22,18 +22,9 @@ 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. **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.
|
||||
7. **The simplest thing that works.** Prefer what already exists. No new mechanism unless it is needed, and fewer
|
||||
parts over more.
|
||||
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,7 +112,10 @@ 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);
|
||||
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);
|
||||
- **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
|
||||
|
||||
@@ -8,9 +8,8 @@ code:
|
||||
- mesh-sdk go/catalogue (the manifest's shapes)
|
||||
- mesh-sdk go/declaration (the node-engine's resource vocabulary)
|
||||
- mesh-contracts
|
||||
updated: 2026-11-18
|
||||
updated: 2026-11-12
|
||||
decisions:
|
||||
- "ADR 0680"
|
||||
- "ADR 0578"
|
||||
- "ADR 0595"
|
||||
- "ADR 0619"
|
||||
@@ -170,7 +169,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 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 |
|
||||
| **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 |
|
||||
| **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 |
|
||||
@@ -179,39 +178,6 @@ 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,10 +3,9 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 42
|
||||
milestone: zfs-owns-zfs
|
||||
updated: 2026-11-18
|
||||
updated: 2026-11-13
|
||||
decisions:
|
||||
- "ADR 0679"
|
||||
- "ADR 0680"
|
||||
---
|
||||
# 42, milestone zfs-owns-zfs — the lead's answers to the prepare's questions
|
||||
|
||||
@@ -137,8 +136,6 @@ 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,10 +2,8 @@
|
||||
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-20
|
||||
updated: 2026-11-11
|
||||
decisions:
|
||||
- "ADR 0682"
|
||||
- "ADR 0681"
|
||||
- "ADR 0673"
|
||||
- "ADR 0672"
|
||||
- "ADR 0668"
|
||||
@@ -197,16 +195,6 @@ 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
|
||||
@@ -1520,23 +1508,6 @@ 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):
|
||||
@@ -1693,7 +1664,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.** *(Retires at milestone H, design 47 H §764.)* A merged revision naming a newer indexer gives, from the running indexer, a catalog
|
||||
38. **A newer indexer is reached.** 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
|
||||
@@ -1735,7 +1706,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** *(Retires at milestone H, design 47 H §764.)* (ADR 0633 §4, §5). The forge bridge sets the group on each
|
||||
49. **The forge bridge reads a group from the gate's verb** (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).
|
||||
|
||||
@@ -1757,9 +1728,11 @@ 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` (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).
|
||||
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).
|
||||
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
|
||||
@@ -1892,9 +1865,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** *(Retires at milestone H, design 47 H §764.)* raises `take-in-waits` at 30 minutes, and none of its members is delivered (whole,
|
||||
81. **A group that never completes** 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** *(Retires at milestone H, design 47 H §764.)* leaves its revision pending, holds only its own watched branch,
|
||||
82. **An indexer whose manifest its validator refuses** 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
|
||||
@@ -1980,13 +1953,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** *(Retires at milestone H, design 47 H §764.)* (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is
|
||||
105. **One query finds what is behind** (design 47 G §375). With the runner stopped while mesh-sdk `0.1.16` is
|
||||
released, `outdated` names the module's kind-1 edge at `0.1.15` against `0.1.16`, and at its restart the runner
|
||||
starts that module's pipeline once, keyed by mesh-sdk's source revision; `runner_catch_up` does it by hand and
|
||||
writes the hand-act log
|
||||
(whole, indexer and runner, mesh-delivery). After the first fill (§377), a mesh running its newest builds is
|
||||
answered with nothing behind.
|
||||
106. **A delivery is waited for mesh-wide** *(Retires at milestone H, design 47 H §764.)* (design 47 G §376, §379, §380). A module ordered after a provider's
|
||||
106. **A delivery is waited for mesh-wide** (design 47 G §376, §379, §380). A module ordered after a provider's
|
||||
new version is wanted only once `version-delivered` says every present machine placing the provider runs it; with
|
||||
one machine away the module's status reads "waiting for delivery of" the provider, naming the machine, and it
|
||||
catches up when that machine is back; with every placing machine away the provider reads "waiting for <machine>
|
||||
@@ -1999,85 +1972,9 @@ 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
|
||||
@@ -2171,7 +2068,6 @@ 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,10 +84,9 @@ 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 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).
|
||||
- §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).
|
||||
- §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
|
||||
@@ -318,10 +317,8 @@ 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 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).
|
||||
- §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).
|
||||
- §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,9 +242,8 @@ 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, 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
|
||||
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
|
||||
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,15 +384,12 @@ 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. *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.
|
||||
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.
|
||||
- §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,21 +378,12 @@ 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; 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).
|
||||
- §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).
|
||||
- §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`.
|
||||
@@ -409,8 +400,9 @@ 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 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`.
|
||||
- **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`.
|
||||
- **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-17
|
||||
updated: 2026-11-11
|
||||
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, for a step that read a test run or a composition run another step asked its `shared` (G-24 §729); 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; 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), `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 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 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_compositions` (each composition run, G-24 §728) | — | `assigner_release`, `assigner_compositions_drop` |
|
||||
| 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 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,8 +230,6 @@ 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
@@ -1,209 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,290 +0,0 @@
|
||||
---
|
||||
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,9 +103,7 @@ 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 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
|
||||
for the consumer, named `<machine>_<module>` as ADR 0363 §5 names one, with its grants to read and acknowledge it and
|
||||
its membership's word to bind it; it drops that consumer when the module no longer declares the event, and makes one
|
||||
for a module that declares it later, with no change to the consumer's manifest. A `*` entry never reaches a
|
||||
restricted stream (one with a `grant`, ADR 0363 §4). Why: the keeper hears modules it finds in the catalog and its
|
||||
|
||||
@@ -3,7 +3,7 @@ layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: G
|
||||
updated: 2026-11-17
|
||||
updated: 2026-11-12
|
||||
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-four files, each read whole, its design lines numbered across them:
|
||||
The part is twenty-two 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,7 +112,5 @@ The part is twenty-four 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).
|
||||
|
||||
@@ -1,297 +0,0 @@
|
||||
---
|
||||
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).
|
||||
|
||||
@@ -1,197 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,718 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-21
|
||||
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 the operator's desktop | 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 the home server and the laptop) | 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 shadow fault on the operator's desktop**: the entries client leaves an entry `asked` after a transport failure and never asks
|
||||
again; about 110 entries on the operator's desktop 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 the operator's desktop: 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 the control-node 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 the operator's desktop and the control-node 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. Done at 19:31 on 2026-11-21 (section 10, row 173).
|
||||
|
||||
## 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 work H1's live run owes, as the lines of its own part, [H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md) and [H2-stores-and-tools](H2-stores-and-tools.md) (design 47 H2 §775 to §821): every ask a kept call through a part away, the work queues and journal lines of the asks, the fingerprint over a module's own build source, the stores capped and read in parts, the gate's ledger per module and its delivery times, hq a watched source | mesh-delivery, mesh-catalog, `mesh-host`, `mesh-tools`, `mesh-sdk` | H2 §816 and §817: a change to a delivery part, and a package with its importer in two repositories, each running everywhere within ten minutes of its merge call with no hand act |
|
||||
| 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 (the control-node'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.
|
||||
|
||||
## 10. Findings of H1's live run, for H2 and H4 (the lead, 2026-11-20 14:22 CET)
|
||||
|
||||
Met while the clean state was placed and the first pipelines ran; none changes H1's scope. Each is a line for the
|
||||
milestone named, written into its part before that milestone's prepare.
|
||||
|
||||
| finding | milestone |
|
||||
|---|---|
|
||||
| The indexer starts its take-in on a two-minute timer; the first branch take-in after a start waits that long. An event, not a timer (P1). | H2 |
|
||||
| The readers' first views loop on "asked once more" when the verb's holder is slow; the loop is silent. | H2 |
|
||||
| The composition step's validate reads "the branch's previous catalog revision" and could not run for the first revision after the seed (main.2 does not exist): a first revision validates against nothing, said so. | H2 |
|
||||
| The node build module asks a `package-lock.json` of the artifact's path; mesh-contracts's TypeScript artifacts name `.`, where none is: either the artifact path or the module's check is wrong, read against ADR 0499. | H2 |
|
||||
| The indexer's whole integration test took 32 s to set up on the build node, over the level's 30 s setup bound, so the step failed on time, not on behaviour. | H2 |
|
||||
| The grants part composes no per-branch consumers. | H4b |
|
||||
| The runner's publish is malformed on the earlier model's records (one journal line each). | H2 |
|
||||
| `TakeInSource` has no check for a revision below the newest kept. | H2 |
|
||||
| `mesh_wait` refuses the operator channel's events. | H2 |
|
||||
| No bus snapshot on request (a tool of the bus module). | H2 |
|
||||
| The keeper's orphan rule ignores state buckets. | H2 |
|
||||
| An artifact's key against the workspace directories H-A-136 adds (ADR 0499 clause 4). | H2 |
|
||||
| hq has no registration, so its pull requests are refused by the gate (H-A-131). | H2 |
|
||||
| mesh-delivery-sdk and mesh-delivery-contracts publish as packages of their own. | H2 |
|
||||
| The hand pack's `build-seats` phase carries the label of the build node only; every machine with a build runtime needs it. | H1, the runbook |
|
||||
| The claude-code node side wrote a lease over a login the manager had not adopted (H-A-138); its fix is a small fix beside H1. | fixed in H1 |
|
||||
|
||||
Added by the lead at 18:40 CET, from the run of 16:40 to 18:40: the first delivery by pipeline landed (a module on the
|
||||
desktop, with hand restarts), and these were met on the way. A row a lead answer settled says so; the rest are open.
|
||||
|
||||
| finding | milestone |
|
||||
|---|---|
|
||||
| Validate's base was read as the source number minus one, which names nothing where a take-in moved nothing (the seed, a merge with no mover); the indexer (`mesh-delivery-indexer`) and the assigner's validate. Settled by H-A-151 and H-A-154 (the catalog revision's field `base`), which settle the first-revision row above too. | settled in H1 |
|
||||
| Compositions on the control-node failed on stale assignments (modules assigned that no watched branch lists); the assigner (`mesh-delivery-assigner`). Settled by H-A-152 and H-A-153 (the run value's field `unlisted`, in the seat mesh-wants), proven at main.24. | settled in H1 |
|
||||
| A build ask reached the builder before its picture held the pipeline's revision, so it built with no version reserved (main.8, main.21, the first proof); the builder. Settled by H-A-155, H-A-156 (`revision-wait-minutes`) and H-A-162 (a run's ask names no source). | settled in H1 |
|
||||
| 64 of 82 Go modules carried no package edge, because the indexer read mesh packages from go.sum, which names none at the zero version; the indexer. Settled by H-A-157 (edges from go.mod). | settled in H1 |
|
||||
| The tool runner (`node-tools`) stopped every subscription on each membership and repair and dropped calls in the gap; the tool runner. Settled by H-A-158 and H-A-160 (make before break). | settled in H1 |
|
||||
| The builder still numbered every trunk build in a `versions` state of its own and folded a reserved version into an older entry, so builds pinned an old package; the builder. Settled by H-A-159 (the reservation is the one numbering), which also makes a tool to drop or rewrite a versions entry moot. | settled in H1 |
|
||||
| Packages were pinned by a commit (a pseudo-version of an old tree), so builds ran against pre-H1 packages (main.15, main.20, main.22, main.24); the indexer and the builder. Settled by H-A-161, H-A-165 (`package-wait-minutes`, a re-pin on version-released), H-A-167 and H-A-172 (pins in every form's fingerprint). | settled in H1 |
|
||||
| A pipeline whose mover had no registration never ended (main.20, main.22), and no tool ended a pipeline by hand; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-163, H-A-171 and H-A-164 (the seat verb `end-again` on mesh-pipeline-runner, the tool `runner_end_again`). | settled in H1 |
|
||||
| The SDK's view reader heard an event only on `<subject>.>`, so the seat mesh-catalog's registration-changed on its bare subject reached no handler; mesh-sdk. Settled by H-A-166 and H-A-169 (the finding `event-unhandled`). | settled in H1 |
|
||||
| The SDK's finding write for an unhandled event waits up to 3 s on the bus inside the event loop, per event, so a missing stream or a slow bus stalls the module: write it outside the loop, or once per change of the count; mesh-sdk. | H2 |
|
||||
| The indexer dropped a passed pipeline's revision once the pipeline ended, so the want named an entry no longer kept and was held "entry-missing" (main.23, main.25); the indexer. Settled by H-A-168, H-A-170, H-A-173 and H-A-174 (release pins). | settled in H1 |
|
||||
| A tier-late pipeline's release records are freed only by that module's next pipeline that ends running, so a module with no later pipeline keeps its revisions pinned; the indexer. | H2 |
|
||||
| The indexer's `publishedAsBuilt` may read a package's imports at the wrong commit when the pin is not the newest of its series; the indexer. | H2 |
|
||||
| A failed re-pin leaves a pending key behind; the indexer. | H2 |
|
||||
| A build module's toolchain edge into the movers it is built from made a cycle the runner never broke, so pipelines held their turn with no step for an hour (main.26, main.28, main.30); the pipeline runner. Settled by H-A-175 and H-A-176 (the pipeline ends failed with why `cycle`). | settled in H1 |
|
||||
| Integration tests pass alone and fail on the build node under load (the bridge, the grants part, the indexer, the assigner's setup at 38 s against 30 s, the tool runner's level at 72 s against 60 s), because a build node runs levels side by side; fixed per test for the indexer and the tool runner only; the Go build module (`mesh-build-go`) and each module's tests. | H2 |
|
||||
| The Go build module runs builds at idle CPU priority, so a fixed bound in a test or a step can be outlasted by load alone; the Go build module. | H2 |
|
||||
| The build node counts untagged tests into a module's integration count (156 against the budget of 50 for the pipeline runner); the Go build module. | H2 |
|
||||
| Modules over the test budget: the node-engine (`mesh-host`) with 1716 unit tests against 500, the indexer with 538 integration tests and the assigner with 64, against 50; each shrinks with every change to its tests. | H2 |
|
||||
| The Go build module reads failed on the control-node and on the laptop, and a third build node is paused, so one build node (the desktop) builds for the whole mesh. | H2 |
|
||||
| The builder still starts delivery builds from the take-in path, flooding the one build node, where H §756 says a build is entered only by the runner's build step; the builder. | H2 |
|
||||
| A newer pipeline withdraws an older pipeline's build of the same module, and the older pipeline then fails instead of that mover leaving it (main.27, withdrawn by main.30); the pipeline runner and the builder. | H2 |
|
||||
| The step outputs store keeps 0 bytes, so the words of a failed test are lost and only the verdict remains; the pipeline runner. | H2 |
|
||||
| The pipeline runner's `show` answers 150 KB with no filter, too large for a session to read; it needs a filter (a mover, a step, a state); the pipeline runner. | H2 |
|
||||
| A run on request cannot place steps for a module that is not a mover; the pipeline runner. | H2 |
|
||||
| `runner_start` refuses a head whose pipeline exists (H-A-52), so a package module is built again only by a new merge; the pipeline runner. | H2 |
|
||||
| A required step that could not run has no hand twin: accepting it and running it again are both refused; the pipeline runner. | H2 |
|
||||
| No tool places a pipeline's waiting movers again; only the runner's start does; the pipeline runner. | H2 |
|
||||
| No tool shows the pins a build ask carried; the builder. | H2 |
|
||||
| `builder_build_again` refuses a key that is done; the builder. | H2 |
|
||||
| The seed registered not every package module (mesh-delivery-contracts, mesh-delivery-sdk) and made no mover of them, so they were registered by hand and nothing was published at H1's heads (H §758); the seed of the seat mesh-catalog. | H2 |
|
||||
| A want is written only from a pipeline that passed whole (H §750, §751), so a dependent folded in (H §745) that fails blocks a fix of the module it depends on; the assigner. A design question: all or nothing, or per mover. | H2 |
|
||||
| Packages in one repository carry no kind-1 edge between them (the sibling rule, H-A-136); a design question whether they should; the indexer. | H2 |
|
||||
| A module (`feh:tools`) carries a required integration step with no integration test to run ("a step with nothing to run"); the seed's steps in the seat mesh-catalog. | H2 |
|
||||
| The gate (`mesh-delivery-gate`) says old sources again on a restart. | H2 |
|
||||
| A held take-in does not try again after a passing failure of the forge; the indexer. | H2 |
|
||||
| The node-engine's early-pass words "reaches no artifact store" read as a fault while placements are not read yet; the node-engine. | H2 |
|
||||
| The node-engine's resolve-again period is fixed in code, not a setting (P11); the node-engine. | H2 |
|
||||
| A fetch made inside the node-engine's turn tells the composer nothing; the node-engine. | H2 |
|
||||
| The node-engine's node-agent wiring has no test; the node-engine. | H2 |
|
||||
| A bundle reload of the tool runner still unloads before it serves, so calls in the gap meet no responders (said, not silent), and the mesh MCP server's package takes 28 s to load; the tool runner. | H2 |
|
||||
| The seat node-files has no verb that reads a file's sha256, and its `copy` refuses another node (issue 903), so hand packs were copied by the lead's shell; node-files. | H2 |
|
||||
| The builder's unit written by hand on the desktop carries none of the manifest's setting variables, so its settings are the defaults; the builder's hand pack. | H1, the runbook |
|
||||
| The clean proofs of the runbook's step 7 are still owed: the first proof failed on the version race (settled by H-A-155), the second ran for the publish of the SDK packages; the freeze is not lifted (step 8) (lifted at 19:31 on 2026-11-21, row 173). | H1 |
|
||||
|
||||
Added by the lead at 19:50 CET, from the run of 18:40 to 19:50; a row met again names the row of 18:40 it adds to.
|
||||
|
||||
| finding | milestone |
|
||||
|---|---|
|
||||
| The node-engine (`mesh-host`) asks the seat mesh-recovery for a restore point before it moves a data-holding module, and the recovery module is placed nowhere (H §456), so every such take-in was held for good; the node-engine. Settled by H-A-177 and H-A-178 (it moves without a point where no holder is placed and raises the finding `restore-point-missing`). | settled in H1 |
|
||||
| A package module no machine holds (mesh-delivery-sdk) had a required composition step that could not run, so its pipeline could never pass (main.35, the second proof); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-179 (the step ends `nothing to run`, ADR 0682 §8). | settled in H1 |
|
||||
| A module held for a failed restore point kept the hold across the node-engine's start, and no operator's ask was raised for it, so the hold was for good; the node-engine. Settled by H-A-180 (the hold's cause is judged again at the start and on every change of placements). | settled in H1 |
|
||||
| The forge bridge kept each owed event whole in its state `performed`, filling its kept data to 51 MB of the template's 64 MiB (19,530 keys, the condition "kept data is filling up"); the forge bridge. Settled by H-A-181 and H-A-182 (the outcome, when, and the act's pull request; the act stays in the gate's stream `owed`). | settled in H1 |
|
||||
| The finding `restore-point-missing` did not reach the conditions after the first move without a point: the finding's wiring to the condition keeper; the node-engine. | H2 |
|
||||
| The recovery module is placed nowhere, and the assigner derives no placement from the holder of the seat mesh-broker (G §554); the assigner (`mesh-delivery-assigner`). | H2 |
|
||||
| A pipeline record with 112 or 129 movers exceeds the bus's 1 MiB message limit once its steps are placed, so two pipelines were cancelled; the record's shape (steps per mover key) and the limit as a setting; the pipeline runner. | H2 |
|
||||
| A change to the SDK package folds in about 112 importers and a change in the catalog repository about 60, so the first re-pin of those repositories cannot run until the pipeline record is reshaped (the row above); the pipeline runner. | H2 |
|
||||
| Met again on the tool runner's pipeline: a superseded build makes the older pipeline fail instead of its mover leaving it (the row of 18:40 on a withdrawn build); the pipeline runner and the builder. | H2 |
|
||||
| The gate's owed acts run at about ten times the design's estimate (about 80 note acts per delivery record per pull request), and the gate's own stream `owed` takes the same rate; the gate (`mesh-delivery-gate`). | H2 |
|
||||
| The forge bridge's `bridge_owed` by pull request still reads every key of its state in the tool runner's process; the forge bridge. | H2 |
|
||||
| A refused consumer creation is tried again for longer than the tools' wait for an answer, so a person sees a timeout instead of the refusal; the bus module's tools. | H2 |
|
||||
| Met again: the SDK's finding write for an unhandled event waits up to 3 s on the bus inside the event loop, seen as a 90 s test (the row of 18:40); mesh-sdk. | H2 |
|
||||
| Met again: the build node counts untagged tests into a module's integration count (the row of 18:40); the Go build module (`mesh-build-go`). | H2 |
|
||||
| Met again: the step outputs store keeps 0 bytes, so a failed test's words are lost (the row of 18:40); the pipeline runner. | H2 |
|
||||
| The proof of the runbook's step 7 is still owed: proof 1 failed on the version race, proof 2 twice, on stale pins and on the composition step of a module no machine holds (settled by H-A-179), both settled; the freeze is not lifted (step 8) (lifted at 19:31 on 2026-11-21, row 173). | H1 |
|
||||
| Four hand placements more (the distribution tools bundle, the assigner, the builder's program, the node-engine twice) and five hand restarts were needed to break circles, each said to the operator; the runbook. | H1, the runbook |
|
||||
|
||||
Added by the lead at 21:30 CET, from the run of 19:50 to 21:30; a row met again names the row it adds to.
|
||||
|
||||
| finding | milestone |
|
||||
|---|---|
|
||||
| A pin named the newest release of the module holding a package (its release number), while a Go package's version is its tag, so every importer of a nested package failed on "unknown revision" (main.39), and pipelines kept failing on old pins; the indexer (`mesh-delivery-indexer`). Settled by H-A-183, H-A-184 and H-A-185 (the pin is the newest version the registry published for the package path, within the series the module's manifest accepts), built in the indexer and placed by hand, because its own pipeline could not deliver it. | settled in H1 |
|
||||
| Nine Go packages other modules import were never declared artifacts of their modules (among them the builder's `builds`, the bus module's `busgrants`, disk-load's `diskreadings`), so no release published them and their importers' builds wait past the bound; the owning modules' manifests in the catalog. Settled by H-A-186 (an imported mesh package is a declared artifact of its module); still owed: the catalog's check that refuses a manifest whose Go module imports a mesh package path no module of the catalog declares. | H2 |
|
||||
| A package artifact's declared series (0.1) differed from its module's version series (0.3 for the assigner), so its publishes would pin nothing; the manifests in the catalog. Settled by H-A-188 (a package artifact's series is its module's version series, or left out); still owed: the catalog's check that refuses a mismatch, and the gate's manifest (`mesh-delivery-gate`) naming the series 0.3 in its `packages` so it accepts the assigner's asks, in the catalog's next change. | H2 |
|
||||
| A pipeline record of 112 or 129 movers exceeded the bus's 1 MiB message limit (the row of 19:50 on the record's shape); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-187 (steps one key per mover), H-A-189 (a mover's unlogged step-log entries under its mover key), H-A-190 (a step-log entry names its mover) and H-A-191 (`list` answers counts, `mover-count` and `step-count`). Still owed: a tool that reconciles a record whose mover-key writes failed; and a bound on every kept value (64 KiB) and on every tool answer, in mesh-sdk, the lead's proposal, whose scope waits on the operator. | H2 |
|
||||
| The builder's step path pinned a package of the same pipeline at the module's release number, and the Go build module (`mesh-build-go`), given no pin, took another package's version of the same repository (its "askedFor" fallback), so both built against versions never published; the builder and the Go build module. Settled by H-A-192 (the builder takes a pin from the catalog entry or the registry's package-published event alone; a build module given no pin refuses the build, loud); still owed: the Go build module's half, in the catalog. | H2 |
|
||||
| The builder's lane narrowed a module's single fetch to the paths of its package artifacts, so a program build found no main module; the builder. Fixed in the builder, by ADR 0499 clause 1. | settled in H1 |
|
||||
| The indexer's tools bundle missed a catalog-revision event in silence, so the pipeline runner waited 12 minutes for the next revision; the tool runner (`node-tools`). The cause, not the SDK's reader: the tool runner on the control-node was built before the one consumer loop (H-A-132, H-A-133), so two pull loops read the bundle's one durable consumer and each event reached one loop only; the events alternated (the bundle read 42 and 44, the runner's own view heard 41 and 43), and the seat mesh-catalog's revision verb answered a stale revision while the same process had heard the newer one. The fix of the cause is the tool runner's own release reaching that node (pipeline main.43); the kind is closed by H-A-196 (the SDK refuses, loud at bind time, a second pull loop on a durable the same process already pulls), in build. A note: a log line per event handed to a bundle. | settled in H1 |
|
||||
| The seat mesh-grants's verb `grants-for` was cut after 5 s in two pipelines' composition steps (a widening entry on the vault); the grants part. The cause: the verb answers in 3.4 to 5.0 s, because on every call it reads two whole catalog revisions (about 1.4 MB each) page by page through the seat mesh-catalog's revision verb and composes every account twice, with no cache, while the pipeline runner's read bound is 5 s. A revision read whole over the bus is the same habit as the row of 21:30 on the pipeline record over 1 MiB. The fix chosen (thorough): the grants holder keeps each revision it read, a revision never changing; in build now. Not chosen: raising the runner's bound. | H2 |
|
||||
| The node-engine (`mesh-host`) on one machine said it cannot create a new version's folder ("operation not permitted"), met twice, two days apart; the node-engine. The cause: an immutable attribute a person set by hand on the engine's versions folder during the recovery of the mixed state of 2026-11-13, since removed; the engine keeps repeating the stale words of its last applied record. No fix in code or unit: the words clear at the next applied composition. Owed: a tool of the seat node-files that shows a file's attributes (none exists), and the engine's record says when its words date from. | H2 |
|
||||
| Two hand placements more (the assigner's compositions fix and the indexer with pins by package path), each on its machine, because their own pipelines could not deliver them; the runbook. | H1, the runbook |
|
||||
| The "unknown revision" kind, its cause read at 22:12: the Go build module (`mesh-build-go`), given no pin for a requirement at the zero version (a transitive one, or one a sibling names), borrowed the version of the first package of the same repository in the ask, wrong since pins became per-package versions; the registry, the indexer's pins and the publishes were right for the paths they name; the Go build module and the indexer (`mesh-delivery-indexer`). Settled by H-A-192 (a build module given no pin refuses the build; the catalog's change, in build) and H-A-201 (the entry pins every requirement of the module graph, transitively; in build in the indexer). | settled in H1 once delivered |
|
||||
| The builder writes a git tag `go/v<version>` for every Go package, while the Go toolchain's direct fallback for a nested module looks for `<directory>/v<version>`, so the tags serve nothing; secondary, as the registry seat holds every real version; the builder. Owed: the tag takes the package's directory, or no tag is written at all. | H2 |
|
||||
| A build that fails this way is asked again every 30 to 40 s, and the builder reserves a new version number each time (`mesh-build-go` 0.1.65 to 0.1.70 in five minutes): the builder never gives up a failing build of an unchanged fingerprint; the builder. Owed: a failed build of a fingerprint is not asked again until its inputs change, and no version is reserved for a build that failed before. | H2 |
|
||||
| With H-A-196 and H-A-197 built (the SDK's one guard against a second pull loop on a durable; the tool runner claims through it), two durable pull loops in the delivery repository still call the bus client directly: the watchman's dead-letter loop and the grants holder's main loop; each binds one durable once today, so there is no fault, but the kind is open there; the watchman and the grants part. Owed: both route through the SDK's consume function, in a change after this group's SDK is published (a module builds against the latest published SDK); the review that finds a direct durable pull is the check. | H2, or the next change of the delivery repository |
|
||||
| The seat mesh-grants's verb `grants-for` (row 69): the grants holder keeps the catalog revisions it read, at most `grants-for-revisions-per-branch` per branch and only for the branches it follows, and learns the branch's newest revision from the catalog-revision event; the grants part. Settled by H-A-193 and H-A-195; merged as pull request #294, whose pipeline failed on other faults, so it is delivered with the next passing pipeline. | settled in H1 once delivered |
|
||||
| The publishes the builder heard lived only in its memory and were lost at a restart, so a build waiting for a package published before it waited the whole bound; the builder. Settled by H-A-194 (before it waits, the builder asks the package registry seat's `versions` verb once), in pull request #291. | settled in H1 once delivered |
|
||||
| A package artifact's steps lacked its same-repository requirements (H-A-198), and writing the derived "../" paths into the entry (H-A-199) would have changed the form of the seat mesh-catalog's `modules` value, which every module decodes, so every reader would have had to run the new client before the writer: the mesh cannot derive that ordering edge yet; the Go build module (`mesh-build-go`) and the indexer (`mesh-delivery-indexer`). Settled for H1 by H-A-202 (the Go build module derives the same-repository tree transitively; the indexer takes those directories into the fingerprint for every form without writing them into the entry). Owed: a change of a kept value's form is an ordering edge the delivery plan derives (a contract version on the value, or the readers' release before the writer's). | H2 |
|
||||
| The indexer pins every other-repository requirement across the module graph, never one of its own repository (H-A-201, pull request #296), and the Go build module refuses a build with no pin (H-A-192, the catalog's change); together they end the "unknown revision" kind (row 72); the indexer and the Go build module. | settled in H1 once delivered |
|
||||
| The seat mesh-catalog's hand-written digest helpers lived under the contract's generated root, so the generator's check failed every unit step; the contracts module. Settled by H-A-200 (they live in the seat's hand-written client), in pull request #295. Owed: the generator's check runs in the contracts module's own unit step on the mesh (it does today), and the hand-written clients' import of the delivery SDK (ADR 0625 §3) is still on trunk. | H2 |
|
||||
| The pipeline runner's lint, unit and integration asks carried no pins (only the build ask does, and the builder adds them), so once the Go build module refused a requirement with no pin (H-A-192) twelve test steps of the contracts mover could not run; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-203 (every step ask carries the entry's pins), in build in the runner. | settled in H1 once delivered |
|
||||
| The entries of modules not changed since kept their old `packages`: a direct requirement with no pin although the registry held its version, a declared package never published left out, a same-repository chain missed; six build asks were refused; the indexer (`mesh-delivery-indexer`). Settled by H-A-204 (an entry names every requirement, with an empty version where none is published so the builder waits; a publish re-pins every kept entry of any repository; a tool answers one entry's pins), in build in the indexer. Owed: the kept-entry rule "unchanged unless it imports a package the commit moved" is replaced by the publish re-pin everywhere. | H2 |
|
||||
| A second build node still ran the Go build module (`mesh-build-go`) from before the pin refusal, so one pipeline's build borrowed a pin there and failed "unknown revision" while the first build node refused loud; the fixed build module could not be placed on that node tonight, so its Go steps were paused by its tool; the Go build module and the runbook. Owed: a hand placement reaches every node that runs the module, or the module is delivered by its pipeline (H1's purpose). | H1, the runbook |
|
||||
| Two pipelines of consecutive revisions ran at once, and the older one's builds failed "revision 45 of main not in the builder's picture within 2m0s" while the seat mesh-catalog's revision verb answered 46; the builder. Settled by H-A-205 (for a revision below the newest it heard, the builder asks the revision verb by number), in build. | settled in H1 once delivered |
|
||||
| A test step of an entry whose package has no version yet went out without that pin and was refused; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-206 (a Go artifact's test steps wait for their pins as the build does, "waits on the publish of <path>"), in build in the runner. | settled in H1 once delivered |
|
||||
| The Node and the Go build modules' tools that list their running steps do not list delivery asks (the builder's own asks), so the check "no running step" before a hand restart cannot see them; the Go build module's was seen at 01:17 to 01:19, its step list showing none while the seat's `current` verb showed asks running; the Node build module and the Go build module (`mesh-build-go`). Owed: each list names every ask the module runs, whoever asked. | H2 |
|
||||
| A test step held for a pin not yet published had nothing to end it once its build passed (the builder had read the registry and pinned it), so with one pipeline at a time the queue would stop; the pipeline runner (`mesh-delivery-pipeline`) and the builder. Settled by H-A-207 (the build's end reports the pins it built with, the seat mesh-builds' end carrying `packages`, and the runner asks the held steps with them), in build. | settled in H1 once delivered |
|
||||
| The reading of the module graph (H-A-201) runs at a take-in, which applies a repository whole, so repositories with no merge since the rule changed kept their modules' direct requirements only, and no tool took a repository in again; the indexer (`mesh-delivery-indexer`). Settled by H-A-208 (the tool `indexer_take_in_again`), H-A-209 and H-A-210: the take-in again keeps no catalog revision and asks no gate; it re-reads the repository's kept requirements at its merge commit and recomputes the modules state as a publish re-pin does; in build. Owed: a change of the indexer's rules recomputes every repository by itself at the indexer's start; the tool is the hand form of that. | H2 |
|
||||
| The pin kind (rows 62, 66, 72, 79, 81 to 85, 87, 88) was fixed one instance per round for five hours, against the rule "at the second failure of a kind, fix the kind"; the rule was then written whole as a specification with a gap table against the code ([H-pins-spec-and-gaps.md](H-pins-spec-and-gaps.md)): 35 lines, 24 built, 6 built otherwise, 1 contradicted, 2 missing, and 7 changes still missing (its section 8), the largest that a re-pin on a publish never became a revision or a mover (the "entry-missing" holds on wants), settled by H-A-211 (a re-pin is taken in as the next catalog revision of the same source); the indexer (`mesh-delivery-indexer`), the pipeline runner, the builder and the Go build module. The lesson for playbook 07: a kind met twice gets its specification before its third fix, and one owner across every part it touches. | H1 (the way of working); H2 for the owed items of the specification's section 8 |
|
||||
| A catalog revision's number equalled the gate's source revision by habit, so a re-pin had no number to keep its entries under, and the pipeline runner started a pipeline per published artifact (several per release) from its own hearing; the indexer (`mesh-delivery-indexer`), the seat mesh-catalog's definition and the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-212 and H-A-213: a revision's number is the indexer's own counter, with the gate's source as a field; a revision carries its call (`call`: take-in, release of a module version, or take-in again of a repository); one pipeline per release revision; the runner keys pipelines and reads revisions by number. The call's kind is a field of its own, `call-kind`, an enumeration the seat's schema validates (take-in, release, take-in-again), with `module` and `version` or `repository` beside `call`, the words for a person, so no reader parses words (H-A-215). The seat mesh-builds' package-published names the revision it was built from (`revision`, set by the builder), so the runner finds the publishing pipeline among several revisions of one source (H-A-218). Every ask of the runner (build, step, wants) names the catalog revision number in its `revision` field, with the gate's source beside it in `source`, so a build module and the builder read one meaning of the word (H-A-219). A build the builder starts from its own picture takes its revision number from the picture's half into its reservation, so its publish names the same revision its source comes from (H-A-220). The runner's pipeline subjects (pipeline-started, pipeline-ended, wait-held, wait-ended) name their last token `<revision>` and carry the pipeline's revision number, the same number as its key, so name and value agree (H-A-221). In build by the one owner of the pin kind (row 89). | settled in H1 once delivered |
|
||||
| With revision numbers no longer the gate's source (row 90), two readers still looked a revision up by its source: the seat mesh-catalog's revision verb's source input, and the indexer's freeing of a pipeline's pins on the seat mesh-wants' pipeline-wanted, which named only the source; and the take-in again could re-read only the trunk, since only its merge commit is kept; the indexer (`mesh-delivery-indexer`). Settled by H-A-214 (pipeline-wanted names the revision number; the verb's source input answers the take-in's revision; the take-in again covers the trunk, and another watched branch is re-read at its next merge). In build by the pin kind's second owner: the first ran out of context after the indexer's part, and the hand-over cost one review round. Owed: a take-in again of another watched branch, once branches live longer. | settled in H1 once delivered; H2 for the owed item |
|
||||
| Beyond the publish re-pin, three more whole recomputes of the indexer (on a build module's assignments change, on a toolchain report, and by the recompute tool) moved fingerprints with no kept revision, and the assigner (`mesh-delivery-assigner`) derived a pipeline's source from its key, which now carries the revision number; the indexer (`mesh-delivery-indexer`), the pipeline runner and the assigner. Settled by H-A-217 (any recompute that moves a fingerprint keeps a revision of `call-kind` recompute naming its reason; the runner treats every revision whose kind is not take-in alike, one pipeline for its movers) and H-A-216 (the assigner keeps the source the pipeline's end names and sends it in pipeline-wanted beside the revision). In build by the pin kind's second owner (row 91). | settled in H1 once delivered |
|
||||
| The joined pipeline runner (`mesh-delivery-pipeline`) crashed at every start on the control-node ("concurrent map writes" in its per-mover step store: the store's shared maps were written under each pipeline's lock only, while the start placed several branches' waiting pipelines at once) and was rolled back within a minute. Before dying it had split two kept pipelines into per-mover keys, and the old runner then placed one running pipeline's steps again from the emptied record, losing that record's history; no hand repair, as the new runner composes from the keys; the pipeline runner. Settled in H1 by a mutex over the store's maps and a run of the race detector over the runner's start path with kept pipelines. Owed: every module's unit and integration suites run under the race detector in the check, and a tool that lists the runner's state keys (a whole list exceeds the bus; no key listing exists). | H1 (the fix); H2 (the check and the tool) |
|
||||
| The indexer (`mesh-delivery-indexer`) refused its own take-in-again tool's ask ("a takeins value naming no hand act the indexer serves"): the decoder of a take-in ask kept a hand-written list of hand-act fields that the new field was not added to, and no test sent a tool's value through the decoder; the indexer. Settled in H1 by deriving the check from the ask's fields, and by a table test that decodes every tool's value. Owed: the same table test for every module whose tools write asks its daemon decodes. | H1 (the fix); H2 (the kind across modules) |
|
||||
| The seat mesh-catalog's revision verb answered from the tools bundle's view of the trunk in memory, which ran one or more revisions behind the kept revisions once releases kept several in a row, so the pipeline runner waited minutes for a revision the indexer had kept (four minutes for revision 52) and the builder's picture failed a pipeline's first builds past its bound (rows 68 and 84); the indexer (`mesh-delivery-indexer`) and the builder. Settled by H-A-222 (the verb answers the newest kept revision read from the store at the ask; the builder's picture holds an ask that names a kept revision number, read by number), in build. | settled in H1 once delivered |
|
||||
| A release re-pinned a mover of a running pipeline of 120 movers (the tool runner, pinned to the SDK's new version) while that pipeline still built it at the old fingerprint; the build failed and, as a pipeline passes or fails whole, took every other mover with it, because the runner moved only movers of waiting pipelines; the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-223 (a moved mover leaves a running pipeline too: its steps end superseded, its asks are cancelled, the end judgement counts it as left; a pipeline whose every mover left ends superseded), in build in the runner. Also seen in the same pipeline: two builds done "but no version is reserved", because the builder's picture lagged the revision that named their fingerprints (row 95's cause). | settled in H1 once delivered |
|
||||
| On the build node the SDK's own integration test of the views reader ("the views reader and two handlers share the module's one durable") failed under the new guard against a second pull loop on one durable (H-A-196), while the same test passed locally at review. The cause, not the guard: the test read the durable's pending-ack count the moment the handlers had spoken, while the reader acknowledges afterwards and the bus takes acknowledgements on its own, so one was still pending on the loaded build node; the test now publishes a mark event and waits for the consumer's acknowledged floor to reach it, fixed in mesh-sdk, in review. The kind: a test reading the bus's acknowledgement count right after a handler speaks; mesh-sdk. Also seen: four release-revision pipelines waited with no steps for over ten minutes behind one running pipeline that could no longer pass, because the pipeline runner (`mesh-delivery-pipeline`) runs one pipeline at a time and ends a pipeline only when its last step ends. Owed: a pipeline that cannot pass ends at once (H-A-163 as written), and the queue's setting is raised once the build nodes allow. | H1 (the SDK's fix); H2 (the queue) |
|
||||
| With the SDK's new guard against a second pull loop (H-A-196), which reads a consumer's cached information at bind, a test fake of a consumer in the indexer (`mesh-delivery-indexer`) that answered no such information panicked, so the indexer's unit step would fail against the new SDK although no indexer code changed; mesh-sdk and the delivery repository's modules. Fixed in H1 by completing the fakes across the delivery repository's modules. Owed: a change of the SDK that adds a call on an interface every module fakes is tried against the modules' suites before its merge (the group's check builds every importer, but runs no importer's suite). | H1 (the fakes); H2 (the check) |
|
||||
| The builder was restarted by hand while Go asks ran in the Go build module's runtime (`mesh-build-go`), whose step list showed none because it does not list the builder's own delivery asks (row 86); the asks survived the restart because the build module runs them, but the "no running step" check before a hand restart is blind to them; the build modules and the runbook. Owed: one tool across the build seats that lists every running ask, whoever asked it. | H2 |
|
||||
| The watchman's entry still pinned no client that its same-repository `buildrun` module requires, because the watchman's go.mod names `buildrun` in a replace directive without a require line, and the reading of the module graph (H-A-201) followed require lines only; six test steps were refused "no pin" (rows 79 and 82); the indexer (`mesh-delivery-indexer`). Settled by H-A-224 (a same-repository module named only by a replace counts as required; its requirements are pinned transitively), in build in the indexer. | settled in H1 once delivered |
|
||||
| The builder keeps one reservation per module and series and bumped its number on any new run of a build (a restart's re-run included), while the run already building carried the old number, so its publish was refused "has no version reserved or released"; and a take-over of the series by another fingerprint dropped the older reservation without stopping the older build, which then published a dropped number; the builder. Settled by H-A-225 (a reservation is kept for the same fingerprint until it is released; a taken-over build is withdrawn; a number never published is freed), in build in the builder. Its last clause is withdrawn by H-A-226: the builder's Built and the reserved answer match by version alone, and the registry refuses a republish with other bytes, so a reused dropped number would let a withdrawn build's late publish land in the new reservation; a dropped number stays a gap, which harms nothing, and the series key keeps only the withdrawn numbers above the catalog's highest released patch. Also seen: after the builder's start it logged "no seat builds an artifact of language go and kind package" dozens of times a second (the journal suppressed over a thousand lines); not a spin but a burst at the start: every catalog entry taken in and every seat definition heard plans every known module again, and a failed plan is not kept, so the same line is logged once per definition and module. Owed: a failed plan is kept and said once until the seat list changes. | settled in H1 once delivered; H2 for the owed items |
|
||||
| A restart of a node's tool runner (`node-tools`), to load one module's new tools bundle, silences the seat verbs of every module whose tools run inside it: the artifact registry seat answered "no responders" for about two minutes while the control-node's tool runner restarted, and the builder's publishes failed meanwhile; the tool runner and the builder. Owed: a tool runner serves one module's bundle again without restarting (H-A-158's make before break, for a bundle), and a publisher retries a seat that answers no responders, within a bound. Also seen there: the registry seat's list answer exceeds the bus (1.5 MB; pages are owed, the same habit as row 65), and a finding of kind read-side-down raised by one writer cannot be cleared by the tools' writer (owed: one owner per finding kind). | H2 |
|
||||
| The thirteen issues the lead held were judged against what the milestone delivered: five closed as superseded by H's merge call and the checker's retirement (the forge's status writes, the merge Approve path, a second check overwriting the first, a gate merge without a manifest, a refused merge asked again); three resolved with their fixes named (the controller's check bound, the checker's tests on the desktop, the build node's resolver); one released back to open (the verbs of the seat node-package-manager, which H does not touch); two kept with a note (the bus flood, whose kind now sits on the connection of the control-node's tool runner; the session not told of an answer); and two wait for the proofs (a held module's chain; one release for a change across repositories, proof 2); the issue tracker. A missing tool was met: no forge tool lists merged pull requests by number. | H1 (done); H2 for the two waiting and the tool |
|
||||
| The artifact registry's receiver read its incoming object store's fill on every chunk it took, and the tool runner (`node-tools`) answered the fill by listing every kept description of the store, the leftovers of about twenty thousand deleted chunks included, so the control-node's tool runner read fourteen megabytes a second and the bus ran at full CPU; every take-in and publish slowed (proof 1's take-in took six minutes), and discovery answered incompletely (rows 65 and 102); the artifact registry, the tool runner and the delivery SDK. The recovery (drop one dead upload, purge the store's leftovers) removes data and was put to the operator. Settled by H-A-227 (a fill is read from the stream's own figures, never by listing; a receiver reads it once per transfer; the owner compacts a store of leftovers), in build in the tool runner and the delivery SDK. Also seen: three findings streams stood full (the pipeline runner's, the builder's and the node-engine's); owed: a findings stream bounded by age, and a reader of its fill. | H1 (the fix); H2 (the compaction and the bounded streams) |
|
||||
| The validate step's run ask (the manifest validator's program, built and run from the delivery repository's tree) still carried no pins after H-A-203 was built for the test asks, so with the build module refusing a requirement without a pin every validate step ended "could not run" (proof 1's feh at 01:56, the SDK's at 01:30) and no composition followed (rows 81 and 85); the pipeline runner (`mesh-delivery-pipeline`). Settled in H1 by giving the validate ask the pins of the manifest validator's own entry at the pipeline's revision, in build in the runner. The kind: every ask the runner makes carries pins, and a review that reads "every step ask" lists the asks. | settled in H1 once delivered |
|
||||
| The bus module's keeper reads only a manifest's new-form asks, so the eleven entries the two foundation parts (the artifact registry and the forge) declare in their old sections, all with live data, stand as orphans to it: the registry's incoming store could not be rebuilt empty ("an orphan: drop it, or ask for it in a manifest again"), and the only way to empty it was a drop on the operator's warrant followed by the grants part's assert that makes it again; a careless drop of any of the other ten would lose live data (rows 65 and 104); the bus module. Settled by H-A-229, H-A-230 and H-A-231: every manifest's old-section entries are asked for, never orphans; the keeper keeps, grows and rebuilds only those it made, and creates none (the grants part makes the rest); in build in the bus module. Ten of the eleven clear; the lower-case events stream, which the keeper made under a name the grants part does not derive, stays an orphan, to be dropped on the operator's warrant. | H1 |
|
||||
| Three fixes were merged between 02:09 and 02:13 and each taken in within a minute (the flood halved after the dead upload was dropped): the validate and composition run asks' pins (the holder of the seat mesh-wants), the tool runner's fill from the stream's figures, and the receiver's one read per transfer. The first lands in the holder that runs on a node of its own and through which every validate step runs, so no pipeline can deliver it to itself: a hand pack for that node, copied by the operator at their terminal (the session's permission check refused the lead's copy) and restarted there before the running pipelines' validate steps can pass. The last of the three re-pins twenty-nine modules into one pipeline; the runbook. | H1 |
|
||||
| The bus module's drop of an orphan asks the operator's warrant with a window of ten minutes, and then ends with nothing removed ("ask again with a new request") while the operator is away, whereas the session's own asks carry an expiry the asker sets (up to a day); the drop's warrant should carry the asker's expiry too, or at least the operator's answer to the session's ask should count (row 106); the bus module. Owed: the bus module's warranted acts take an expiry from their caller. | H2 |
|
||||
| The bus module's orphan judgement (row 106) was fixed, reviewed in two rounds (the first found the keeper taking into its care a state's object store the grants part made, and its cap sum dropping kept state buckets) and merged at 02:33; its take-in took close to three minutes while the indexer waited on a package's versions, where the night's others took under a minute; its pipeline waits with five others on the validate fix reaching the node that runs the holder of the seat mesh-wants (row 107); the bus module and the runbook. | H1 |
|
||||
| Every take-in of the catalog repository since a Go module was removed from it on 2026-11-17 said "its packages are not published": the indexer (`mesh-delivery-indexer`) lists a repository's packages from its kept packages state too, which still holds the removed module, so the forge's listing of the whole set fails, and the indexer's one-directory fallback runs only on its own error, not on the forge's. Nothing of that repository was published since, so the digests of its three same-repository packages froze on their last commit, and a change to one would not move its seven importers, unsaid; met twice tonight before it was read (row 81 on the pins kind; issue 1585, one release for a change across repositories); the indexer and the forge module. Settled by H-A-232 (a repository's packages are those in the merge's tree, and a gone key is dropped and said; the forge answers not-found and the fallback runs on it; any other failure stays loud), in build in the indexer and the forge module. | H1 |
|
||||
| The operator restated at about 03:33 the bound ADR 0282 decides: a fix to a leaf module runs healthy on every node within five minutes of its merge, a core module within ten. Tonight's measured parts: merge to take-in 25 to 45 s for the delivery repository and 2 min 40 s to 5 minutes for the catalog repository (cause not yet known; the indexer waited on a package's versions); take-in to placement about two minutes under the queue of pipelines at once; a leaf's build step running past six minutes; and no pipeline reaching its composition since 01:56 (the validate asks). No pipeline completed merge to running tonight, so the whole is unmeasured (rows 105 and 107); the pipeline runner (`mesh-delivery-pipeline`) and the condition keeper. Owed: the pipeline's phases timed and said per pipeline (the pipeline-ended event carries each step's start and end), and the delivery time held against ADR 0282 by a condition. | H2 (the measure); H1 records it |
|
||||
| A release pipeline held the pipeline runner's one slot for nine hours (02:06 to 11:08): its validate ask was lost when the holder of the seat mesh-wants was restarted for a hand pack, and the runner waits on an ask without a bound, so eight pipelines queued behind a step nobody would answer, until the lead cancelled it on the operator's word (rows 107 and 111); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-235 (every ask the runner makes is bounded, asked again once, then ends could-not-run with a finding, and the slot frees), in build in the runner. | H1 |
|
||||
| The runner's rerun of a validate step was always refused ("placed no ask now"): the verb looks for the ask by the mover's id, while the validate ask is one per pipeline and names no mover (H-A-51), so a failed pipeline's validate could not be asked again after the pins fix, and proof 1 had to be run a second time from a new merge (row 105); the pipeline runner. Settled by H-A-236 (the rerun of validate asks the pipeline's one validate ask again; the rerun of composition builds the composition ask for the named mover), in build in the runner with the row above. | H1 |
|
||||
| The bus module's drop and rebuild warrants ask at the destroy level, which needs a code no channel carries yet, so the router held all four of the night's asks unshown ("no channel can carry it now") while the tool answered "the operator is asked", and each expired after ten minutes; the operator saw nothing on Telegram (rows 106 and 108); the bus module and the operator channel's router. Settled by H-A-237 as a weighed bend the operator asked for: the keeper asks at the approve level until a channel carries destroy, with the caller's expiry; the tool reads the router's record and says offered, held or refused; the router's hold reason names the level. Owed: the destroy proof stays designed (ADR 0259), and a channel that carries a destroy answer. | H1 (the bend); H2 (the destroy channel) |
|
||||
| Once the slot was freed, the first pipeline through the fixed holder of the seat mesh-wants passed at 11:07 (a release of a contracts package, six movers): validate three minutes after placement, compositions on the build node, the pipeline ended passed, and the next took the slot within a minute; the pipeline runner (`mesh-delivery-pipeline`). Still seen: the seat mesh-grants's verb `grants-for`, cut after 5 s, marks every mover's widens could-not-run (rows 69 and 76, the grants cache); and two movers are over the test budget (an NFS server module at 51 integration tests, a package manager module at 121, against 50). | H1 (the pass); H2 (the cut, the budget) |
|
||||
| Proof 1 runs a second time: one line in the wallpaper module, merged at 11:07:56, taken in 2 min 51 s later as its own pipeline with the one mover, and placed last in a queue of six; the catalog repository's take-in still says "its packages are not published", because the forge's not-found fix is merged but not running yet (rows 110 and 113): the hand packs of the forge module and the indexer go onto the control-node now, on the operator's word, with the tool runner's; the runbook. | H1 |
|
||||
| On the operator's word ("if you would run all the changes on our local machine, it wouldn't take that long"), the night's merged fixes to the delivery system itself went onto the control-node as hand packs between 11:10 and 11:19 (the indexer, the forge module's code, the tool runner for seventeen units), each by its notes, with the kept copies beside; all units are active and the forge's listing verb is served; the two proofs alone go by their pipeline (rows 107 and 110); the runbook. Seen in the indexer's journal: its findings writer owns four kinds while its code raises others (a missing pin, generated types out of step, a merge not taken in), so the writer refused them once a minute for hours and no finding of the indexer was written; the kind of H-A-233 would have met the same; the indexer (`mesh-delivery-indexer`). Settled by H-A-240 as H-A-242 corrects it (row 119). | H1 |
|
||||
| The root of row 112: the holders of the seats mesh-builds and mesh-wants take their asks on a plain subscription, not from a work queue, so an ask put while the holder is down (a hand pack's restart) is lost, and neither seat says a word about an ask before the step's end (rows 107 and 112); the pipeline runner (`mesh-delivery-pipeline`), the builder and the holder of the seat mesh-wants. Settled by H-A-241 and H-A-243: the runner puts every open ask of a seat again when the seat's holder starts, on the node-engine's running event; for a seat that says no first word, one silent bound (`ask-silent-bound`, default forty-five minutes) ends the step could-not-run instead of two short ones, so no build of ordinary length is cut; the second ask's id is derived in the accepted form; in build in the runner with rows 112 and 113. Owed: the seats' asks as a work queue, and an ask-taken from both holders. | H1 (the runner); H2 (the queue) |
|
||||
| Row 117's cause corrected: the refusals come from the SDK's held writer, which at its start seeds every key of the module's shared findings state, the daemon writer's kinds included, and refuses them once a minute, against the design's rule that no bundle reads the whole state to state another's findings (G §580); mesh-sdk and the indexer (`mesh-delivery-indexer`). Settled by H-A-242, which corrects H-A-240: the held writer seeds only the kinds it owns; each writer's kinds stay in code, with a unit test holding the code to them; an unowned kind is said once; no manifest field; in build in the SDK and the indexer (row 117). | H1 |
|
||||
| A pipeline placed from the queue nine hours after its take-in still carried a mover whose fingerprint a newer revision had moved at 03:33 (the series taken over by the newer build), so its build step found the old build done but holding no number, and the pipeline failed: the rule that a moved mover leaves a pipeline (H-A-223) was applied to running pipelines only (rows 90 and 112); the pipeline runner (`mesh-delivery-pipeline`) and the builder. Settled by H-A-244 (the rule holds for every pipeline not ended; the builder's answer for such a build says "stale: its series moved", never "no version is reserved"), in build in the runner and the builder. | H1 |
|
||||
| A package's version tag (`go/v0.1.59`) stood at another commit on the forge, so the version-released event could not write it and was given up after five deliveries while the publish went on (row 101); the builder. Settled by H-A-245 (the builder reads the tag through the seat git before reserving a number, and takes the next free one, with the finding version-tagged-elsewhere; a tag is never moved). Owed: its build in the builder. | H2 |
|
||||
| The bus module's warrant fix (row 114) was reviewed in two rounds and merged at 11:28, and taken in three minutes later as a pipeline of two movers (the bus module and the router). The same take-in proved the hand-placed indexer and forge module (row 117): the forge's listing answered not-found for the gone directory, and the take-in went through where every one since 2026-11-17 had said "not published" (row 110). The bus module's hand pack is built from that merge and placed on the control-node next; then the registry's incoming store is dropped on the operator's warrant at the approve level and made again empty; the bus module and the runbook. | H1 |
|
||||
| With the bus module's hand pack placed (11:35), the drop of the registry's incoming store was refused by design (the store is asked for again, row 106), and the rebuild was asked at the approve level: the router offered it on Telegram at once, the operator chose Rebuild, and the keeper took a snapshot and rebuilt the store empty at 11:39:46, so row 104's recovery is done (rows 104, 114 and 122); the bus module. Seen beside it: the keeper does not withdraw the ask of a request it refused at once, so a dead "remove it?" stayed on the operator's channel until it expired. Owed: the keeper withdraws the ask of a request it refuses. | H1 (the recovery); H2 (the withdrawal) |
|
||||
| The rebuild did not end the flood: the bus still delivers about six thousand messages a second (five to seven megabytes) to the control-node's tool runner, so the listing of that store was one source and not the only one (rows 102 and 104). No tool of the bus module reads consumers by delivery rate or creation time, nor a connection's busiest subscriptions, so the source could not be named from the tools (a missing tool, by the instruction one-question-one-tool). Under reading now: the artifact store's bundle asking the registry's list verb in a loop, while the registry answers by listing a store whole and the answer exceeds the bus's 1 MiB; the bus module, the tool runner (`node-tools`) and the artifact registry. | H1 (the source); H2 (the tools) |
|
||||
| The flood's second source, read at 11:47: the artifact store's bundle starts a sweep on every finished build and an observation on every want change, each reading the builder's builds state key by key (ten thousand keys, two bus answers each, because the tool runner binds the bucket before every read), the starts queued behind one lock and draining back to back, and it asks the registry's list at every pass though its answer exceeds the bus's 1 MiB: about a third of the six thousand messages a second (rows 102, 104 and 124); the artifact store's bundle, the tool runner (`node-tools`) and the artifact registry. Beside it, the registry refuses that bundle's removals as not the sweep's, so the store never shrinks. Settled by H-A-250 (one pending pass, one paged read, a loud stop with the finding artifact-list-unread) in the artifact store's bundle and H-A-251 (the tool runner binds a state once) in the tool runner, both in build. H-A-257, H-A-258 and H-A-260 amend the followed view: its first view is the watch's handover, a build's end comes from the builder's log, and an unread end holds the pass and raises the finding artifact-builds-unread. Owed: the registry's list paged (with row 102), and the sweep's removals taken by the registry. | H1 (the two fixes); H2 (the list, the sweep's refusal) |
|
||||
| A pipeline's validate passed at 11:40 and the pipeline runner dropped its end: the one validate ask names no mover, the holder's end names the mover whose body it took, and the runner compared it with the first step carrying the ask ("a step's end the runner does not take"), so every mover's validate stayed running and the pipeline held the slot until the lead cancelled it, proof 1's behind it; seen at 01:11 too; the second of row 113's kind, a shared ask read as one mover's (rows 113 and 118); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-252 (a validate end matched by its ask alone ends every mover's validate step; the same for the composition's shared runs), in build in the runner with rows 112, 113, 118 and 120. | H1 |
|
||||
| Proof 1's second run passed its pipeline: merged at 11:07:56, taken in at 11:10:47, placed at 11:48:00 after thirty-seven minutes in the queue behind five older pipelines (one held nine hours by a lost ask, one by a dropped end), and built, tested, validated and composed by 11:49:06, sixty-six seconds from placement; the queue, not the pipeline, took the time (row 111); the pipeline runner (`mesh-delivery-pipeline`). | H1 |
|
||||
| The pipeline's wants were written only at 11:54:21: the holder of the seat mesh-wants runs its pass (the assignment graph, the tiers' judgement, the wants) only when a catalog revision arrives, so a passed pipeline waits for an unrelated merge's take-in (five minutes here, twelve for an earlier one) (rows 111 and 127); the holder of the seat mesh-wants (`mesh-delivery-assigner`). Settled by H-A-256 as H-A-259 corrects it (row 131). The node-engines on the desktop and the build node took the new want within a minute and updated the module's tools bundle, the files bundle following the composer. | H1 |
|
||||
| The SDK's paged read of a state takes a key as its cursor while the bus reads no key range, so a page read replays the bucket once per page, and a large state read in pages costs more than key by key (rows 102 and 125); mesh-sdk, the tool runner (`node-tools`) and the artifact store's bundle. Settled by H-A-255 in H1 (the artifact store's bundle reads the builder's builds from a followed view, no bus read per pass), amending H-A-250 and H-A-254. H-A-257, H-A-258 and H-A-260 amend the followed view: its first view is the watch's handover, a build's end comes from the builder's log, and an unread end holds the pass and raises the finding artifact-builds-unread. Owed: H-A-254 (pages in sequence order with an opaque cursor, a contract change). | H1 (the view); H2 (the cursor) |
|
||||
| The pipeline runner's change for rows 112, 113, 118, 120 and 126 was built as eight commits and approved in three rounds (the rounds found a validate rerun covering one mover only, bounds that expired while the runner was down never heard, and a restart asking an answered step again), and is merging now; the pipeline runner (`mesh-delivery-pipeline`). The reviewer's notes stay owed: a holder restarted at the same build with its health unchanged says no new running, so its lost asks are not put again until the seats' asks travel through a work queue; and the builder's build log does say a build started, a first word H-A-241 could use (rows 112, 118 and 126). | H1 (the change); H2 (the notes) |
|
||||
| Row 128's cause corrected: the holder of the seat mesh-wants does wake its pass on the pipeline-ended and running events, but each pass that keeps a fresh assignment graph revision sits six to eight minutes keeping and removing revisions (every unlisted entry object read one at a time, the kind of row 125), so a wake waits for the blocked pass: feh's wants at 11:54 were the end of a pass begun at 11:46 (rows 125 and 128); the holder of the seat mesh-wants (`mesh-delivery-assigner`). Settled by H-A-259, which corrects H-A-256 on the cause (the keeping runs off the pass loop, one at a time; its judgement reads the entries in one read; each pass and keeping logs its duration), in build in the holder. | H1 |
|
||||
| Between 11:50 and 12:03 four changes merged and were each taken in within a minute or two: the SDK's held findings writer (rows 117 and 119; its release re-pins 126 modules into one pipeline), the indexer's finding kinds (row 119; its merge was held seven minutes until the SDK's Go package was published, so it builds against the new version), the tool runner's bind once (row 125) and the pipeline runner's bounded asks (row 130). Their hand packs go onto the control-node now; the queue of pipelines behind them runs for hours, the one of 126 movers above all (row 111); the runbook. | H1 |
|
||||
| Proof 1's one line never reached the file: the wallpaper module is a moved module, so its template file is the provisioner's to fill (ADR 0349 §4); the node-engine deletes the file's content and hands a plan line to the provisioner, and the provisioner's client renders the files archive on the machine. The provisioner on the control-node runs a build from before the indexer's view rename, asks every minute for a first view the indexer no longer serves (503, no responders), and has made no plan since 2026-11-20 09:41; its own pipeline was the one cancelled in row 126, so no current build of it exists. The node-engines did take feh's new want and its tools bundle within a minute, and the builder did publish the new files archive (its digest moved twice since 2026-11-20) (rows 126, 127 and 128); the provisioner and the runbook. The provisioner goes onto the control-node as a hand pack from main on the operator's word (row 117), and its plan then names the new archive. Owed: a cancelled pipeline's movers get a pipeline again by themselves. | H1 (the pack); H2 (the cancel's movers) |
|
||||
| The four hand packs went onto the control-node between 12:14 and 12:23 (the pipeline runner with its bounded asks, the indexer with its finding kinds, the provisioner from main, the tool runner for seventeen units), every unit active: the provisioner composed every machine from 12:17 without the stale first view; the tool runner's "finding kind not declared" line stopped; the mesh MCP server dropped for a minute at 12:16 and came back by itself; and the big pipeline's validate (row 126's kind) was asked again with the fixed verb at 12:23 and runs under its bound (rows 117, 130 and 133); the runbook. | H1 |
|
||||
| Proof 1 (its second run) is shown: the wallpaper file on the desktop and the build node carries the merged line, read at 12:26. The chain: merged at 11:07:56, taken in at 11:10:47, placed at 11:48:00, passed at 11:49:06, the want written at 11:54:21, the node-engines applied it within a minute, the provisioner's plan named the new files archive at about 12:23 once a current provisioner ran, and the file was written by 12:26. No hand act touched the module's own path; the hand acts were on the delivery system's parts (the assigner on the build node, the cancel of the held pipeline, the provisioner). The time from merge to running was 78 minutes, 37 of them in the queue and 30 waiting on a stale provisioner, so ADR 0282's five minutes is not met (rows 111, 127, 128 and 133); the runbook. | H1 (the proof); H2 (the bound) |
|
||||
| Proof 2 began: the SDK's one-line change and the tool runner's were merged in one call at 12:26:59 (the seat git's merge verb with two members), the gate moved main's source to one revision for both repositories, and the indexer took both in together at 12:27:18 as one pipeline of 126 movers, the SDK and the tool runner among them (the SDK's release re-pins every importer); the pipeline waits fifth in the queue (rows 127 and 135). The acceptance: the tool runner runs on every machine at the new SDK version with no hand act; the gate, the indexer (`mesh-delivery-indexer`) and the pipeline runner (`mesh-delivery-pipeline`). Owed: a tool that reads one pipeline's movers, with the lighter read per step (row 124's kind). | H1 |
|
||||
| The change of the holder of the seat mesh-wants for row 131 was built, reviewed in two rounds and merged at 12:41 as its own pipeline; the first round found wants written at the start before any revision is kept, and the full-store verdict moved out of the pass, both settled by H-A-261 (no want before a revision is kept; the full-store verdict is the pass's own); the holder of the seat mesh-wants (`mesh-delivery-assigner`). The reviewer's notes stay owed: the bus wrappers' race on one handle, met twice (a handle per goroutine, or a guard in the SDK), and a failed first keeping holding the wants until the next event. Also seen: with the pipeline runner's change live, the waiting pipelines collapsed as designed at 12:38 (three left the queue, their movers moved by the newest), so proof 2's pipeline stands next after the one running (rows 130, 131 and 136). | H1 (the change); H2 (the notes) |
|
||||
| The pipeline ahead of proof 2 (774 steps) made no step the pipeline runner said from 12:42: four contracts modules added to their repository after the registrations' seed of 2026-11-14 were never registered (the seed writes only when no registration is held, and nothing registers a module that enters the module graph later), so their steps waited on a registration nobody had asked, with no bound and no finding (rows 112 and 136); the indexer (`mesh-delivery-indexer`) and the pipeline runner (`mesh-delivery-pipeline`). The build seats were in fact working the other movers while the usage view said none, because it judges a build module by the node-engine's held phase rather than its running asks. The recovery: the four were registered by the register verb, each an Approve on the operator's channel. Settled by H-A-262 (the indexer registers a module the moment it enters a watched trunk's module graph, with no ask, saying registration-changed; the runner raises the finding registration-missing while a mover waits on one), in build in the indexer and the runner. Owed: the usage view judges a build module by its running asks. | H1 (the fix); H2 (the view) |
|
||||
| The pipeline ahead of proof 2 ended at 13:13:18, its contracts movers still unregistered, and proof 2's pipeline took the slot the same second, placing 182 steps within fifteen seconds; its three contracts movers wait on the same registrations (four Approves open on the operator's channel since 12:59, asked by the indexer at the lead's register calls); a newer merge took 28 movers of the delivery repository out of it at 13:22, while the SDK and the tool runner stay in it (rows 136 and 138); the pipeline runner (`mesh-delivery-pipeline`). | H1 |
|
||||
| Row 138's fix was built in the indexer and the pipeline runner, reviewed in three rounds and merged at 13:22 as its own pipeline; the rounds found a finding that never cleared, three design points (a pending proposal is skipped; a module the seed left out is not registered by the graph; the branch is the one the siblings hold alike, else the repository's default) and an untested rule, settled by H-A-263, H-A-264, H-A-265 and H-A-266 (row 138); the indexer (`mesh-delivery-indexer`) and the pipeline runner. Its hand packs go onto the control-node next, so the indexer's start pass registers the four modules itself. Owed: a read of the registrations store in one call. | H1 |
|
||||
| The hand packs of row 140 went onto the control-node at 13:27 and 13:28: the indexer's start pass registered a fifth unregistered module at once (a networking contracts module nobody had noticed) and skipped the four whose proposals were pending, as H-A-265 asks; the lead had those four proposals dropped with the indexer's own tool (the operator's four asks cancelled with them), and the next start registered the four at 13:28:29, each at version 1 with the warrant "module graph". The pipeline runner (`mesh-delivery-pipeline`) at its start said 115 movers of proof 2's pipeline "have no registration yet" before its view of the registrations had loaded, then placed 1048 of their steps at 13:30:55: a fault of the start order of the runner's new check, loud and passing (rows 138, 139 and 140); the indexer (`mesh-delivery-indexer`) and the pipeline runner. Owed: the check waits for the view's first read. | H1 (the registrations); H2 (the start order) |
|
||||
| Proof 2's pipeline ran from 13:13 with over a thousand steps: the SDK's new version 0.1.29 was published, and the build node built modules against it from 13:58; the tool runner's six steps passed in it. Then the revision of the register-at-take-in merge (13:22) and the indexer's recomputes moved the tool runner and about a hundred other movers to the newer pipelines, as the rule says, so the proof's acceptance follows the tool runner's want on each machine rather than one pipeline's end; the superseded pipeline keeps running its remaining movers (rows 136, 139 and 141); the pipeline runner (`mesh-delivery-pipeline`). Owed: a read of a pipeline's record for one mover's steps (62 KB) still exceeds a reader without a shell, the lighter read of row 124's kind. | H1 |
|
||||
| The pipeline that carried the tool runner after the move of row 142 ended failed at 15:03:55 on the required steps of three modules of the catalog repository, none of them the tool runner's (its build, tests, validate and composition all passed, its release 0.1.37 reserved): the forge module's TypeScript build cannot find the contracts package it imports and uses fields its contracts type lacks, and its integration test of the whole seat fails; the bus module's integration test of the whole module fails on the subtest "the fill pass runs while the first view is asked", the one every developer tonight reported as failing at trunk and skipped (by the rule of the second failure, the kind is fixed now, not skipped again); and the registry's integration test of the whole module fails; so no pipeline wrote a passed end for the tool runner, and its want stays. Seen beside it: the earlier pipeline passed at 14:26, but the holder of the seat mesh-wants wrote no want for its eleven remaining movers (its record of the pipeline's end names none of them; the SDK's want still names the morning's pipeline); and the builder has asked the registry to publish the tool runner's release again every few minutes since 14:50, with no "published" answered. Under reading (rows 104, 137 and 142); the forge module, the bus module, the artifact registry, the holder of the seat mesh-wants and the builder. | H1 |
|
||||
| Row 143's causes, read by 15:30: (a) the Node build module places only the SDK into a trunk build and leaves out every other mesh package a package file names, so the forge module's TypeScript build has failed at every build since 2026-11-19 (H-A-267: every named mesh package at its latest published release, as the Go build module does through the pins); (b) the bus module's subtest waits for a first view's "answered", which the keeper never marks for an empty view, so it could never pass (H-A-268: the test waits for the first fill pass); (c) the builder reads every reservation per published event, fifteen seconds apiece, its consumer thousands behind, while its loop asks the same release to be published again every few minutes (H-A-269: one read by digest; no publish asked again while a published is unheard); (d) the holder of the seat mesh-wants skips in silence a passed pipeline's mover whose version the pipeline runner has not yet written, and the version waits on (c) (H-A-270: the skip is said; the runner says pipeline-ended again when a version is written after the end). All four fixes are in build, one owner each; the Node build module, the bus module, the builder, the holder of the seat mesh-wants (`mesh-delivery-assigner`) and the pipeline runner. The failure words of the registry's whole-module test and the forge's whole-seat test could not be read, because the runner's step outputs store holds no bytes for them (the rows of 18:40 and 19:50 on step outputs). The assigner's keeping fix (row 137) went onto the build node by hand at 15:25, and its passes now take 3 to 25 seconds (rows 124, 137 and 143). Owed: step outputs kept and readable. | H1 (the four); H2 (the outputs) |
|
||||
| The builder's loop asking the publish of the tool runner's release 0.1.37 again (row 143) had a second cause under the first: the artifact registry holds that version at another digest than the build's, so even a heard "published" would not have marked it, and the asks would have gone on until the version ended unreleased; the kind of row 121, met on a registry instead of a tag (rows 121, 143 and 144); the builder. Settled by H-A-275 (a number a registry holds is never reserved; a done build so caught moves to the next free number, with the finding version-held-elsewhere) and H-A-274 (a registry record holding the built digest ends the publish as published), in build in the builder. The builder's fixes of the reading of events and the publish asked again (row 144 (c)) were approved at 15:45. | H1 |
|
||||
| Row 144's four fixes were built and reviewed by 16:00: the Node build module's and the bus module's test (merged at 15:49 as a pipeline of 36 movers; the Node build module's pack goes onto the build node by hand, so the forge module's build can pass in it); the builder's (approved in two rounds; the second found that every artifact carries its version at build time, so a build whose number a registry holds at another digest is built again at the next free number rather than moved: H-A-279); and the pipeline runner's and the assigner's (approved in two rounds; the first found that a passed mover with no version yet must hold its tier, else a later tier is wanted before it: H-A-277). The merge of the runner's and the assigner's waits on the operator's word, because the session's permission check refused the lead's dispatch of it (row 144); the Node build module, the bus module, the builder, the pipeline runner (`mesh-delivery-pipeline`) and the assigner (`mesh-delivery-assigner`). | H1 |
|
||||
| The tool runner (`node-tools`) sits in no live pipeline: its last one failed on other movers (row 143) and its fingerprint has not moved since, so nothing builds it again until a merge re-pins it; a module stranded by a failed pipeline gets no pipeline by itself, the kind of row 133's cancelled movers (rows 133, 142 and 143); the pipeline runner. Proof 2 therefore runs a second time, with a new one-line merge of the SDK and the tool runner once the fixes are live. Owed, as one rule: the movers of an ended pipeline that have no passed end are put in a pipeline again at the next kept revision. | H1 (the second run); H2 (the rule) |
|
||||
| The builder's fix (rows 144 (c) and 145) merged at 15:59 and went onto the build node as a hand pack at 16:09 (its program only, the tools bundle left, so the mesh MCP server stays up; a publish in flight was cut by the restart and is asked again). Within three minutes the builder dropped the tool runner's held release 0.1.37 for a new fingerprint of the tool runner that a fresh pipeline carries, and reserved 0.1.38 for it; its loop that asks a publish again now waits, saying so every thirty seconds, while its events consumer's backlog of about 3,800 messages drains under the bound of a hundred at about one and a half a second (some forty minutes). The Node build module's pack went onto the build node at 15:59 too, and the forge module's build moved into the newest pipeline behind the Node build module's files (rows 144, 145 and 146); the builder, the Node build module and the runbook. | H1 |
|
||||
| The builder's events backlog (row 148) drained at only fifty a minute under the new builder, holding up every publish and so every pipeline waiting on one: a published at a version many reservations share still cost three seconds (the fallback by version read every reservation at the version, and the journal line read them all again), and the SDK's event hub pulls five hundred messages per pull and handles them one by one, so buffered messages outlive the thirty-second ack wait and are given again (almost every outstanding message redelivered) and handled twice. Every recovery loses something (a purge of the consumer would drop take-ins, source moves and conditions among the publisheds), so the backlog drains while the fixes build (rows 144 and 148); the builder and mesh-sdk. Settled by H-A-280 (each reservation read once, the fallback only over the unbuilt ones, in-progress sent before long work) in the builder and H-A-281 (the hub pulls at most twenty per pull and keeps a slow handler alive with in-progress) in the SDK for every module, both in build. | H1 |
|
||||
| Row 149's two fixes: the builder's (each reservation read once, the fallback over the unbuilt only, in-progress before the slow pass) was approved and merged at 16:47 as a pipeline of eight movers, its pack for the build node following; the SDK's (the event hub pulls at most twenty messages per pull and sends in-progress every third of the ack wait for a handler still running) is built and in review, and reaches every module at its next build against the new SDK release (row 149); the builder and mesh-sdk. | H1 |
|
||||
| The SDK's event hub fix (row 150) merged at 16:51, and its release re-pins 126 modules into one pipeline, the tool runner among them. Every merge of the afternoon moved the tool runner to a newer pipeline before the older one could pass (rows 142 and 147), so the lead holds further merges from 16:52 until the queue runs through to the tool runner's pass; the one approved change still unmerged (row 146) waits on the operator's word. The builder's read-once pack goes onto the build node meanwhile, so the events backlog drains faster (rows 142, 146 and 150); the pipeline runner (`mesh-delivery-pipeline`), the builder and the runbook. | H1 |
|
||||
| The builder was built again against the SDK's hub fix (row 151) and placed on the build node at 16:58 (its read-once pack at 16:52 before it, with no change in the drain rate): the redelivery stopped (two redelivered, against 175 before; nineteen unacknowledged, against the batch of twenty), and the drain rose to about 1.2 messages a second, so the backlog of 2,167 at 17:05 falls under the bound in about half an hour. What remains is about one second of work per event. Each restart of the builder cut one publish in flight, which the loop asking a publish again asked again; the tool runner's release 0.1.40 waits in main.117 on thirteen publishes (rows 149, 150 and 151); the builder. Owed: the cost per event of the builder's published handling, measured and cut. | H1 (the fixes live); H2 (the cost per event) |
|
||||
| Once the builder's backlog had drained (17:19), the tool runner's release could not publish for another reason: the tool runner imports about twenty packages its own pipeline releases, each package's publish re-pins it (H-A-204), each re-pin keeps a revision of the same source, each such revision's pipeline takes it out of the running one (H-A-223), and each newer build withdraws the older before it publishes; its release ran from 0.1.41 to 0.1.48 in nine minutes with none published: a livelock for any module that imports many packages of one pipeline (rows 142, 147 and 152); the pipeline runner (`mesh-delivery-pipeline`) and the indexer (`mesh-delivery-indexer`). Settled by H-A-283 (a re-pin revision of the same source keeps a mover in its pipeline and asks its build again there; only a new source moves movers), in build in the runner. Owed: pins taken from the reservation and confirmed at publish, so a release re-pins once. | H1 (the runner); H2 (the pins) |
|
||||
| The pipeline runner's fix for the re-pin livelock (row 153) took two review rounds: the first found the placed-again steps' ask ids equal to the ids the runner had just dropped (the build node refuses a dropped id; the work queue dedupes the composition's; a restart found none of them), and a kept mover placed later reading the branch's held view instead of its kept revision. H-A-286 settled both (every ask id of a kept mover carries its kept revision; its entry and pins are read at that revision wherever it is placed or pin-checked), and H-A-287 aligned the rule of one validate: a pipeline has one validate run, which a kept mover's own validate ask joins. Approved at the second round and merged at 18:01 into a pipeline of its own, with its hand pack for the control-node built beside it; merges are held again from then (rows 112 and 153); the pipeline runner (`mesh-delivery-pipeline`). Owed: the runner's unplaced line for a kept mover whose revision is not yet readable. | H1 (the fix); H2 (the line) |
|
||||
| While the re-pin fix (row 154) was built, the pipeline carrying the tool runner (row 151) ended at 17:45 could-not-run: its build ask on the build seat had no word from its holder within the silent bound of forty-five minutes (row 118), because the tool runner's build at that pipeline's fingerprint had been withdrawn by the re-pins' newer builds before it could answer; the tool runner then rode the newest re-pin revision's pipeline, nine of them waiting in the queue; the fixed runner, placed on the control-node by hand at about 18:05, keeps it there from now on. The builder meanwhile says the tool runner's release 0.1.55 is queued at the distribution already, while the registry holds nothing of it; the distribution's word is being read (rows 111, 151 and 153); the pipeline runner (`mesh-delivery-pipeline`), the builder and the artifact registry. | H1 |
|
||||
| The re-pin fix (row 154) was placed on the control-node by hand at 18:05, and the pipeline runner started clean; but the pipeline of row 155 still held the slot: every one of its movers had left to newer pipelines and its last open step had ended could-not-run at 17:45, yet it counted as running, with nine pipelines waiting behind it. The lead cancelled it at 18:08, the second pipeline of this kind to hold the slot with nothing left to do (row 112 was the first) (rows 112, 154 and 155); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-288 (a pipeline ends, and the next is placed, the moment nothing of it is open: at the last mover's leave, at the last open step's end in any outcome, and at the runner's start pass), in build in the runner. | H1 |
|
||||
| The cause of row 156's held slot, read from the pipeline runner's code and the control-node's journal: the pipeline did judge its end at 17:45, but never wrote it; the runner computed every mover's widens inside the end's compare-and-set loop (126 movers, each asking the seat mesh-grants and cut after five seconds, about eleven minutes per try) while the pipeline's key kept changing under it, so every write was refused and the reads were made again (212 cuts between 17:45 and 18:05) until the restart, and the start pass judged no ends (rows 112 and 156); the pipeline runner (`mesh-delivery-pipeline`). Settled by H-A-289 (the reads an end needs are made once before the compare-and-set and shared by every mover and every retry; a retry reads only the key again), beside H-A-288's end pass at the start; in build in the runner. Owed: the five-second cut of the seat mesh-grants's answer itself (rows 69 and 115). | H1 |
|
||||
| The tool runner's release 0.1.55 (queued at 17:47) waited more than forty minutes to publish, not lost but at the back of the builder's publish queue: a state bucket with one key per holder and version, worked one version at a time, oldest first, the whole bucket listed and read again before every send (about 1,900 subjects; the read tool timed out on it), and every start of the builder asks a publish again for every done build without a release, so old versions of many modules ride ahead of the ones a pipeline waits on; the second slow drain in the builder today (row 149 was the first) (rows 149, 152 and 155); the builder. Settled in H1 by H-A-290 (a publish a pipeline's step waits on goes before any asked again at a start; a withdrawn or taken-over build never publishes; one listing per pass and four sends at a time; a send that does not send says why; the read tool answers at any size), in build in the builder. Owed: the publish queue as a work-queue stream per holder, with tools to drop one item or put it first. | H1 (the five parts); H2 (the stream) |
|
||||
| The fix of rows 156 and 157 (a pipeline with nothing open ends at once; an end's reads are made once; a journal line at every end) was approved at its first review round without findings and merged at 18:22 into a pipeline of its own; its hand pack goes onto the control-node at about 18:30, the pipeline runner's second hand pack of the evening, after the re-pin fix at 18:05. After the cancel of 18:08 the queue runs again: the next pipeline took the slot at 18:08 with 853 steps; the tool runner rides the eighth pipeline behind it, and its release of 17:47 still waits in the builder's publish queue (rows 156, 157 and 158); the pipeline runner (`mesh-delivery-pipeline`) and the runbook. | H1 |
|
||||
| The fix that ends an empty pipeline (row 159) runs on the control-node since 18:26; its start pass found nothing to end, the cancelled pipeline having ended at 18:08; the evening's second pipeline runs since 18:08, with the tool runner's seven pipelines behind it. The builder's publish-queue change (row 158) was built with two gaps its developer named: at a start every old unreleased version still rode ahead of the live ones, and a live build waited for a whole start list. H-A-291 settles both (a start asks a publish again only for each module's newest reservation and retires the ones a newer reservation or release supersedes; a live enqueue makes the pass list again after its sends in flight), added before the review, together with a lock on two test fakes that failed the race detector on main (rows 158 and 159); the pipeline runner (`mesh-delivery-pipeline`) and the builder. | H1 |
|
||||
| With the two fixes of the pipeline runner live, the queue ran through: three re-pin pipelines passed between 18:39 and 18:45 (each with few movers), and the tool runner's pipeline was fourth in line at 18:47. Its release's publish had reached the front of the builder's publish queue at 18:27, in the very minute the control-node's tool runner restarted for a hand pack's bundle, and failed with no responders; the builder did not retry it in eighteen minutes, so the lead asked the publish again through the builder's own tool at 18:46, and it was published at 18:46:46 (the publish-queue fix of rows 158 and 160, in review, makes the retry the builder's own). The passed pipelines reached the control-node as the evening's first asks for a person's approval: the store and the identity provider, each recorded as a module a person moves, asked on the operator's channel at 18:45 and 18:46 before their containers are made again (rows 158, 159 and 160); the pipeline runner (`mesh-delivery-pipeline`), the builder and the node-engine. | H1 |
|
||||
| The large pipeline of the SDK's release (853 steps, row 159) ended failed at 18:37: the private network module's unit and integration tests failed, and every other mover passed; its movers get no pipeline by themselves (row 147's rule) and will ride the next merge that touches them. The review of the publish-queue change (rows 158 and 160) found one thing: its read tool reads the builder's own states in pages, which H-A-255 forbade for H1 because each page replays the bucket; H-A-292 allows it for a module's own tool when one page of about 768 KB holds the whole state (one replay instead of a request per key), and the review judges the same head again (rows 158, 159 and 160); the pipeline runner (`mesh-delivery-pipeline`) and the builder. Owed: a failed pipeline's movers put in a pipeline again. | H1 (the review); H2 (the re-pipelining) |
|
||||
| The builder's publish-queue change (rows 158, 160 and 162) was approved at its third and last review round: the second round had found the read tool paging on past one page, and the retire rule crossing version series (a standing 0.2 would have retired a done 0.1.x build); H-A-293 settled both (a one-page read past its page answers the first page and says it is capped, with the state's size; the newest reservation and release are found per module and series), and the fix was judged in one commit. Merged at 19:00 (19:00:35, rebased first onto the fix that ends an empty pipeline, the builder's code unchanged) into a pipeline of its own, with its hand pack for the build node (the program and the tools bundle) built beside it, the first of the evening's packs to restart the build node's tool runner (rows 158, 160 and 162); the builder and the runbook. | H1 |
|
||||
| A second re-pin pipeline ended failed at 18:58 on one module's tests, the teller's program and tools integration tests, every other mover passing, after row 162's private network module at 18:37. The movers of these pipelines carry only the re-pin to the SDK release with the event hub fix (row 150: pulls of twenty instead of five hundred, in-progress acks), so the kind is read before another pipeline fails on it: whether the tests depend on the old pull size or timing (a regression every module meets), or fail for their own reasons. The tool runner's pipeline is second in line from 18:58 (rows 150 and 162); mesh-sdk, the teller and the private network module. | H1 |
|
||||
| A third re-pin pipeline ended failed at 19:01 on the zfs module's tools unit test; the read of all three failures (rows 162 and 164) found none of them the SDK's: the teller's test (an ask refused for want of room is asked again) is sensitive to timing and failed five of seven pipeline runs today, four of them before the SDK's change, so its fix starts now under this milestone (the teller is a module of the delivery system); the private network module's three tests read files outside their own module and failed in every pipeline today (a fix for its repository, after the proof); and the zfs module's test has a data race on the peer's id (a fix for the catalog repository, after the proof). The read also met a missing tool: no tool shows a failed step's test output, only its counts and the names of the failing tests, which belongs with the owed keeping of step outputs (row 144). The tool runner's pipeline was placed at 19:03 with 105 steps; its build, lint, unit and integration steps passed, and validate runs (rows 150, 162 and 164); the teller, the private network module, the zfs module and the pipeline runner (`mesh-delivery-pipeline`). | H1 (the teller's test); later (the two others) |
|
||||
| The publish-queue change (row 163) runs on the build node since 19:03, the program and the tools bundle, the bundle's restart of the build node's tool runner silencing the tools of the mesh MCP server for about a minute (19:05 to 19:06); within three minutes the builder sent two live publishes and said both published, and its read tool answered the queue (empty) with its three standing publish items. Seen at its start: the start pass wrote one line per module no seat can build (about 6,500 lines the journal suppressed), which can hide other lines for a minute, the kind of row 101's burst (rows 158 and 163); the builder. Owed: one summary line for them. | H1 (live); H2 (the summary line) |
|
||||
| The tool runner's pipeline (row 165) ended failed at 19:09 on the forge module's six integration steps, while the tool runner's own build, tests, validate and composition had passed; a pipeline's wants are written only when it passes, so the tool runner got none, and a failed pipeline's movers get no pipeline by themselves (row 147). It is the fourth re-pin pipeline of the evening sunk by one module's tests (rows 162, 164 and 165), so the lead stops iterating pipelines and fixes the kind under this milestone: the teller's test that is sensitive to timing, the private network module's tests that read files outside their inputs, and the zfs module's test race, each in its repository, while the forge module's six failures are read. The tool runner gets a pipeline of its own at once, by a one-line probe commit in its repository merged as one call (the operator's word of 2026-11-16 on probe merges), built against the latest published SDK release; the one-call merge of the SDK and the tool runner itself was shown at 12:26 (row 136), and this pipeline shows the delivery part of proof 2 (rows 136, 147 and 165); the pipeline runner (`mesh-delivery-pipeline`), the teller, the private network module, the zfs module and the forge module. | H1 |
|
||||
| The forge module's six failures (row 167) are one test: its whole-seat test over a real bus, added on 2026-11-20, needs the module's npm packages installed, which the Go integration step never has (it fetches the tree without network), so it has never passed in a pipeline and sank every pipeline carrying the forge since, the one of 15:03 (row 143) included; the forge module and the Go build module (`mesh-build-go`). Settled by H-A-294 (a test that needs tooling its step lacks checks its needs first and ends NOT RUN with the reason and where it was proven, the build module's own precedent), in build in the catalog repository. The probe merge of row 167 landed at 19:13 and became a pipeline of one mover, the tool runner, being watched. The first of the four test fixes is built: the private network module's three tests read their facts from copies in the package's own test data, held equal to the originals wherever the repository is whole; the cause was the artifact's declared paths holding only the module's Go directory (rows 143, 165 and 167). Owed: the Go integration level receives a module's npm tree behind a declared need, and a read tool for a run's test output, which answers nothing through the mesh MCP server today. | H1 (the fixes); H2 (the need and the tool) |
|
||||
| The tool runner's own pipeline (row 167) waited its turn behind the running ones and was placed at 19:20 with eight steps; the fixed builder (row 166) had built and published the tool runner's release 0.1.56 at 19:15, before the pipeline's turn came, the publish sent by the publish-again path within a minute of the build's end. The first test fix (row 168) went to a second review round: it cited an issue instead of its design line (A-474, a module's tests read nothing outside their module), and its drift guard compared the copies against the sibling module's tree, which that line forbids; the guard now holds only the module's own manifest, and the contracts module's facts are proven against copies without a guard (rows 166, 167 and 168); the pipeline runner (`mesh-delivery-pipeline`), the builder and the private network module. Owed: the facts' home is a test in the contracts module. | H1 |
|
||||
| The tool runner's own pipeline (row 169) ended failed at 19:21 in its composition step: the compose ask met no responders on the node-engines of three nodes at once, while every node-engine answered discovery three minutes later; the lead ran the step again at 19:25 with the pipeline runner's rerun tool, and H-A-296 settles the kind (a seat ask that meets no responders is asked again with a back-off until its bound, never a verdict at once). The remaining three test fixes are built: the teller's test bed now answers the seat-holder ask the live mesh answers (the fault was the bed's, five of seven pipeline failures today), and on the way a live fault of the teller was fixed (two takers of one event since the SDK's views reader took its bare subject; H-A-295 keeps the ask-again for want of room until A-424 is built); the zfs module's test race is fixed, with a real fault of its client beside it (a peer not root whose write was cut was never told "only root"); and the forge's whole-seat test ends NOT RUN when its npm tooling is missing (H-A-294) (rows 165, 168 and 169); the holder of the seat mesh-wants (`mesh-delivery-assigner`), the pipeline runner (`mesh-delivery-pipeline`), the teller, the zfs module, the forge module and the Go build module. Owed: the no-responders wait in the assigner's composition run and in the runner's asks, and the step's own NOT RUN summary in the Go build module. | H1 (the fixes); H2 (the no-responders wait, the step summary) |
|
||||
| The tool runner's own pipeline (rows 169 and 170) passed after the composition's rerun, and at 19:28:13 the holder of the seat mesh-wants wrote the tool runner's want on every node (the operator's desktop, the laptop, the home server and the control-node) at the new fingerprint and release 0.1.56, step passed-pipeline (read by the lead at 19:30 through the assigner's reasons tool); the mesh MCP server dropped for a minute at 19:29, as the tool runner on the operator's desktop restarted with the new release; the node-engines' start of the new release on each node is being read, and is row 172's. From the probe merge at 19:13 to the wants: fifteen minutes, the rerun's three minutes inside them. This is the delivery part of proof 2 (row 167); the one-call merge of the SDK and the tool runner was row 136's (rows 136, 167 and 170); the holder of the seat mesh-wants (`mesh-delivery-assigner`) and the tool runner (`node-tools`). | H1 |
|
||||
| The node-engines applied the tool runner's new composition on every node within thirty-five seconds of the wants: the laptop at 19:28:36, the control-node at 19:28:42, the operator's desktop at 19:28:46 and the home server at 19:28:47, each restarting the tool runner because its bundle and its fingerprint changed, and reporting the new build healthy within twenty seconds (the build digest the node-engines report, 0a11dca2…, is the one the builder published as release 0.1.56 at 19:15); the control-node's node-engine had waited a minute for the composition ("the composer has made none yet", 19:27:43), the no-responders episode of row 170. Proof 2 is shown: the SDK and the tool runner merged in one call (row 136, 12:26), the tool runner running everywhere at the new SDK release by its pipeline (rows 167 to 172), no hand act on its path, and the day's hand packs all on the delivery system's own parts (rows 136, 167 and 171); the node-engine and the tool runner (`node-tools`). | H1 |
|
||||
| The lead's statement (lead-47, on the operator's desktop, 19:31): the freeze on hand placing of the delivery system's parts is lifted (step 8). Both proofs of the runbook's step 7 are shown; every part of the delivery system now runs a build its own pipeline delivered or, where a hand pack of today still runs (the pipeline runner, the builder, the indexer, the assigner, the tool runner, the private network module and the store module, named in rows 134, 148, 160 and 166), a build whose source is merged on main and whose pipeline has passed or runs. From now a change to any part is delivered by its pipeline only, and a fault met is fixed in its repository and delivered the same way; the operator's rule of 2026-11-16 on probe merges ends with this statement. The merge of the change of the assigner and the runner (row 146) waits on the operator's word only because the permission check of the lead's session refused the dispatch, not as a decision. What H1 leaves to H2 is the owed list across rows 150 to 170; the runbook. | H1 (done) |
|
||||
| Step 8's tail: the two issues the milestone ran under (one held module holds every reader's version back; a change across the SDK, the controller and the catalog repository needs three releases) were resolved at 19:33 with the proofs as the live case, and the second one's last open note (the indexer's dry run of a branch writes that branch's packages into the live packages state the trunk reads) was carried into H-A-297 as owed work. The recovery-mode rules of 2026-11-15 and 2026-11-16 on the lead's side ended with the freeze. The lead's dispatch of two reviewed merges, the change of the assigner and the runner (row 146) and the teller's test fix (row 170), was refused by the lead session's permission check, so both wait on the operator's word and are not routed through another agent; the catalog repository's two test fixes (rows 165 and 170) merge as one call; this branch's pull request is being opened for hq's check (rows 146, 170 and 173); the indexer (`mesh-delivery-indexer`) and the runbook. Owed: H-A-297 (a dry run reads and writes only its own scratch state, and leaves the trunk's packages state untouched). | H1 (done); H2 (the dry run) |
|
||||
| The catalog repository's two test fixes (rows 165 and 170) merged as one call at 19:29 and became one pipeline of 36 movers: a commit touching two test files moved every module of the repository, because a module's fingerprint takes the repository's commit rather than its artifacts' declared paths; the take-in took eleven minutes, seven of them without a journal line, while the indexer waited on the forge's listing under a busy control-node (the forge at over five cores). This branch's pull request (#797) was opened at 19:35 and had no delivery record or check seven minutes later; the chain from the forge's event to the gate and the checker is being read (rows 168, 170 and 174); the indexer (`mesh-delivery-indexer`), the forge module and the gate. Owed, by H-A-298: a module's fingerprint over its artifacts' declared paths and its manifest, so a commit outside them moves nothing; and a take-in that says what it waits on after a minute, naming the part. | H1 (recorded); H2 (the fingerprint, the take-in's word) |
|
||||
| The read of this branch's pull request (row 175) found the chain from the forge's event to the gate whole, and the cause elsewhere: hq is not a source repository of the gate, so an hq pull request gets no delivery and no check from the mesh, as none of the day's earlier hq pull requests did (the row of 14:22 on hq's registration); it merges on hq's own checks, run before every commit (ADR 0527); whether hq becomes a watched source with a mesh check is the operator's question (H-A-299). The same read met four live faults after the pipeline of 36 movers: the forge refuses the mesh's admin account since 19:41, which stops the forge watcher and the gate's acts on the forge (796 owed; being read: its cause, and the tool that provisions the account again); the gate's ledger records for two revisions exceed the bus's message size; the forge bridge's store of performed acts is full ("maximum bytes exceeded"); and the deliveries read tool cannot answer per repository (rows 150, 166 and 175); the forge module, the gate (`mesh-delivery-gate`) and the forge bridge. Owed, by H-A-299: one ledger key per module and revision; every store with a cap it prunes toward, a read of its fill and a limits tool; and a read tool that filters before it sizes. | H1 (recorded); H2 (the three); open (the forge account) |
|
||||
| The forge's refusal of the mesh's admin account (row 176) was the store's absence: the store's container was replaced between 19:41:04 and 19:41:32 (a move the operator approved on their channel), the forge answered 401 for that minute and said the account was refused, and it recovered by itself at 19:42:11 with a fresh token; the gate's views owed on the catalog repository's two merged pull requests failed in that minute and ended could-not-be-performed, with nothing performing them again; the forge module and the gate (`mesh-delivery-gate`). The record's own pull request (rows 175 and 176) was refused by the mesh's merge verb ("its base main is no watched branch"); the day's earlier hq merges went through the forge's own interface, and the lead's session refused to dispatch that, as it refused the two code merges of row 174, so the three wait on the operator. The private network module's pipeline (the fix of rows 168 and 169) passed at 19:46, the first pipeline of the day with that module's tests green (rows 169, 174 and 176). Owed, by H-A-300: an act failing while a part is away stays owed and is tried again with a back-off; the forge module names the cause it can read; one token mint at a time; a tool that performs every owed act of one record again. Owed too: hq registered as a watched source, so the mesh merges and checks it (H-A-299's question). | H1 (recorded); H2 (the owed acts, hq as a source) |
|
||||
| One more pipeline fell to the store's half-minute absence (row 177): the re-pin pipeline that followed the tool runner's ended failed at 19:43, with many build steps failed and lint steps could-not-run, because the builder's fetch of each source met the forge's 401 in that minute and the builder read the refusal as the build's verdict; the builder. Meanwhile the pipeline of 856 steps holds the slot since 19:46, and the catalog repository's pipeline of 36 movers waits behind it (rows 170, 175 and 177). Owed, by H-A-301, the same kind as H-A-296 and H-A-300: a step whose fetch meets the forge away is asked again with a back-off until its bound, and a fetch failure is said apart from a build failure. | H2 (owed) |
|
||||
| Forty minutes after proof 2 (row 172) the home server's tool runner dropped out of discovery: its node-engine restarts it every 20 to 50 seconds, because the composition key for the tool runner at its new fingerprint alternates between two digests written in turn by two composition runs, one resource (the runtime process) differing; the mesh MCP server on the operator's desktop dropped at 20:16 too, and the control-node's tool runner missed a round of discovery, so the other machines' keys are being read; the stale writer is being found and dropped with the assigner's own tool, as the recovery of the moment; the holder of the seat mesh-wants (`mesh-delivery-assigner`), the node-engine and the tool runner (`node-tools`). The same read found the pipeline of 856 steps (row 178) not stalled: its validate run took 25 minutes, and its last test steps passed at 20:15; and a tool fault: the build seats' steps read tool answered empty on every node while steps ran (rows 172, 176 and 178). Owed, by H-A-302: a composition key written by the newest run only; a run whose pipeline ended writes nothing more; the node-engine applies only a newer write and names it; and the steps read tool answers the steps state. | open (the flapping); H2 (the rule, the tool) |
|
||||
| Row 179's cause was not a stale run: no second composition run writes the key; on three of four machines the node-engine composes the tool runner's self-want itself, and while the grants part does not answer ("withheld unknown") every compose differs in the runtime process, so the node-engine writes a new revision and restarts the tool runner at each compose (every 20 to 50 seconds on the home server, slower on the operator's desktop and the control-node; the laptop, whose compose got the grants answer, is steady); the control-node's tool runner serves the grants answer, which closes the loop; the node-engine and the tool runner (`node-tools`). Settled by H-A-303, which amends H-A-302 (a withheld part keeps the running composition's part and writes no revision; the node-engine applies only a difference in a part it could read; the withheld part is said once), in build in the node-engine; the recovery of the moment, a held put of the tool runner on the home server through the assigner's tool, is being tried. Beside this, the operator decided at 20:24 (the relaying session wrote 20:35), through the session on their desktop, that the packet filter module gets standing control verbs on the seat node-packet-filter (allow, disallow and allowed, with an optional expiry) beside the ports derived from declarations, so design 08 §4 and the seat's verbs change (H-A-304; the decision record amending ADR 0170 is proposed; its first use is tcp 8000 on the LAN interfaces of the operator's desktop); its build runs beside H1's tail (rows 172, 176 and 179). | open (the flapping); other (the packet filter's verbs) |
|
||||
| The mechanism of row 180's loop, read in the node-engine's code and the home server's journal: the self-compose never asks the seat mesh-grants; what goes unanswered is a module's entry or its registry versions, and a module held for that is composed as a stand-in whose slice of the tool runner's runtime process is rebuilt from what runs without its fingerprint and files words, so the process's module list and words differ from pass to pass and the node-engine restarts the tool runner each time ("restarted because its unit's Environment MESH_TOOL_MODULES changed"); the node-engine and the tool runner (`node-tools`). Settled by H-A-306, which amends H-A-303 (a withheld part is every input a compose asks and does not get; a held module's slice is copied verbatim from the running process; a withheld part is said once), in build in the node-engine. The recovery of the moment works: a held put of the tool runner on the home server through the assigner's tool at 20:22 stopped the loop (one restart at 20:26, then steady); the same hold goes on the operator's desktop and the control-node, to be released when the node-engine's fix is delivered (rows 172, 179 and 180). Owed: a read of composed values by resource. | open (the fix in build); H2 (the read) |
|
||||
| The pipeline of 856 steps of the SDK's re-pin (rows 178 and 179) ended passed at 20:15, twenty-nine minutes after its placing, its validate run alone twenty-five of them; the catalog repository's pipeline of 36 movers (row 175) was placed in the same second with eleven steps, and runs. The packet filter's build (row 180) met two facts the lead's map had wrong and one design question: the seat's definition lives in the networking repository's contracts module, not in the contracts repository, so the group is three repositories (the networking repository, the catalog repository and the node-engine's); a definition that carries an event must be whole (every verb's answer form, the event's family, generated packages); and what the node-engine does when the holder's allowed verb does not answer as it composes the filter, settled by H-A-307 (it refuses to compose the filter and keeps the loaded one, said once; allowances only on a converged node's own table) (rows 175, 178 and 180); the pipeline runner (`mesh-delivery-pipeline`), the packet filter module and the node-engine. | other (the packet filter); H1 (recorded) |
|
||||
| The held puts (row 181) went onto the operator's desktop at 20:28 and the control-node at 20:30 too, but they only slow the loop: the node-engines still compose the tool runner themselves and restart it every four to five minutes instead of every half minute; the holds stay until the node-engine's fix (H-A-303 and H-A-306, in build) is delivered, and the mesh MCP server drops for a minute at each restart of the tool runner on the operator's desktop. Two more faults were met meanwhile: the pipeline runner's show verb refuses the record it reads ("unknown field kept-revisions"), because the tool runner's new release carries the runner's tools at a release older than the runner's record form (H-A-309); and the catalog repository's pipeline of 36 movers had eleven steps placed at 20:15, then "written meanwhile, so nothing is placed in it now", with no line since 20:17, being read. The packet filter's work stands: ADR 0683 reserved and in its third proposed version; the design amendments to 08 §4, 33 and the glossary (the word "allowance") committed and pushed on their own branch, in review by two architectural domains; the lead answers H-A-308 (an allowance's identity per interface, its expiry by the holder, the verbs' answers) and H-A-310 (the verbs required from the start in one group; ADR 0246 ended for the seats of contracts modules) (rows 180, 181 and 182); the node-engine, the tool runner (`node-tools`), the pipeline runner (`mesh-delivery-pipeline`) and the packet filter module. Owed: a tool decodes another part's record tolerantly (H-A-309). | open (the loop); other (the packet filter); H2 (the tolerant decoding) |
|
||||
| The catalog repository's pipeline of 36 movers (row 183) was stuck: its placing, cut at 20:15:59 by a concurrent write of the pipeline's record, was never done again; the last test's late progress was dropped without placing what its end unlocked; and the pipeline runner's health said healthy through seventeen minutes with nothing open; a restart of the runner at 20:35 placed 392 steps in twenty seconds from its start pass. It is the second recovery by restart of this kind (row 156 the first), so H-A-311 settles the kind in the runner, in build: a cut placing is done again at once from the record as read again; a late step end still places what it unlocks; a running pipeline with nothing open and nothing placed for five minutes is unhealthy, and said. The packet filter's build moved: the seat's definition, made whole (six verbs, the event, the state, generated Go and TypeScript packages), is committed in the networking repository, and the holder's build follows (rows 156, 182 and 183); the pipeline runner (`mesh-delivery-pipeline`) and the packet filter module. | H1's tail (the runner); other (the packet filter) |
|
||||
| The node-engine's fix of the restart loop (rows 180 and 181) is built and in review: a held module's slice of the tool runner's process is copied verbatim from what runs, so a holding pass has a digest equal to what runs and writes no revision; the withheld part is said once, naming the holder asked; the developer read the restart cause in the home server's journal ("its unit's Environment MESH_TOOL_MODULES changed") and found a failure of the race detector that predates the change. The packet filter's design amendments were read by two architectural domains (seams and tools: eight points; security and upgrade: seven) and settled in H-A-314 and H-A-315; among them: the allowances state takes the template's option of one bucket per machine (a shared bucket would have opened a port on every node); the verbs' classes and the node-engine's grants; a caller not proven is refused; an allowance with an expiry is rendered as a set element with a timeout, so the kernel closes it while the holder is away; a port that a derived rule admits only from the private network is refused unless a source is given; the loaded mark is compared on the allowance's time; and a running holder is not withdrawn when its seat's definition grows. H-A-316 adds a read verb `converged` to the node-engine's seat, so the holder knows its node is adopted; H-A-313 settles the stalled pipeline's journal line (row 184) as the tools program's. The packet filter's seat definition and holder are committed; the node-engine's part and the reviews' additions are in build by two developers (rows 180, 183 and 184); the node-engine, the packet filter module and the pipeline runner (`mesh-delivery-pipeline`). | open (the loop's fix in review); other (the packet filter); H1's tail (the runner) |
|
||||
| The packet filter's design amendments (row 185) now carry every point of the two reviews by architectural domain, and were pushed on their branch at 20:43 (hq's branch design/firewall-control-verbs, head 8fc4f09d): design 08 §4 with its part "control verbs" (eight lines: the node-engine as the one renderer, asking the holder's allowed verb within its compose-ask bound; a refusal keeping the loaded filter; converged nodes only; each expiring allowance its own one-element set with a timeout; the event heard; the acceptance test proving the drop before the allowance); design 33's part (fourteen lines: the six verbs with their classes and refusals, the event and its family, the state one bucket per machine, the verb `converged` on the node-engine's seat, the settings, the holder's start removing expired allowances); and the glossary word "allowance" (a port of the packet filter opened by the operator through the seat). The adoption text of design 08 moved whole into its own delivered part, to keep the main file under its size bound. The decision record ADR 0683 is in its fifth proposed version, with the same points (rows 180, 183 and 185); the packet filter module and the node-engine. | other (the packet filter) |
|
||||
| The node-engine's fix of the restart loop (row 185) was approved at its first review round at 20:45 (the reviewer took each part out in a copy and saw the tests fail; live, the home server's composition still alternated between two digests, which no tool can read word by word, H-A-306 (4) owed); the lead session's permission check refused dispatching its merge, as it refused the three of rows 174 and 177, so four reviewed merges now wait on the operator's word: the change of the assigner and the runner, the teller's test fix, this branch's pull request, and the node-engine's fix; until the last is delivered, the held puts of row 183 stay. The pipeline runner's fix of the cut placing (row 184) is built and in review: a placing refused because the record changed is done again from the record as read again; a late step end places what it unlocks; the health names a running pipeline five minutes without an open step, written once to the tools program's journal. The packet filter's build met two forms the lead's lines had wrong, settled in H-A-317: the state template's option per machine is one bucket whose keys carry the node, so the state's keys begin with the node while the allowance's own key stays as designed; and a holder does not list its seat's event in its manifest's emits, the claim says it (rows 174, 177 and 185); the node-engine, the pipeline runner (`mesh-delivery-pipeline`) and the packet filter module. | open (the loop); H1's tail (the runner); other (the packet filter) |
|
||||
| The packet filter's decision record (ADR 0683, "The packet filter's control verbs beside the ports derived from declarations") was approved by the knowledge base's own review at its eighth version at 20:46: fourteen clauses carrying H-A-304 to H-A-316 (the derived ports stay automatic; the six verbs; allow and its refusals; one allowance per protocol, port and interface; disallow; allowed and rules; the state per machine; one renderer, with the event; removed at its until; an unanswered read keeps the loaded filter; converged nodes only, with the read verb `converged`; the verbs required from the start; two settings; how it is checked), changing ADR 0170 and ending ADR 0246's optional-first for the seats of contracts modules. It is marked needs-operator and waits on the operator's Approve on their channel (the ask expires on 2026-11-22 at 19:36 UTC); nothing of it is in force until then. Two more forms met in the build after the record's last version are H-A-317 (the state's keys carry the node; the claim says the event) and H-A-318 (allowed asks converged again when it holds no answer); they are facts of the templates, and enter the record as a progressive insight if its review asks (rows 180, 186 and 187); the packet filter module and the knowledge base. | other (the packet filter) |
|
||||
| The catalog repository's pipeline of 36 movers (row 184) was not stalled after the pipeline runner's restart; it ran unseen: the builder answered its 36 build asks within seconds (every key already built), and the check asks ran on the Go build module of the operator's desktop at about six a minute, with no journal line from the runner for a step's end nor from the builder for an answered ask, so the lead read a stall where the bus showed the work; by 20:48 its builds, lints, units and validates had passed and three integration steps had failed (the Node build module's, its setup over its thirty-second bound, and the recovery module's whole test), so the pipeline will end failed on those, the kind of rows 162 to 165 again. The read also found the asks of the seat mesh-builds on a work-queue stream no consumer takes (1,524 kept), the home server's Go build module taking no check asks, and the unanswered bound not ending asks left untaken for thirteen minutes. H-A-319 settled the packet filter's refusal of a source-bound port as the chain shows it (a port accepted only with a source match) (rows 165, 184 and 188); the pipeline runner (`mesh-delivery-pipeline`), the builder, the Go build module (`mesh-build-go`) and the packet filter module. Owed, by H-A-320: a journal line per step end and per answered ask; the mesh-builds asks consumed, or the stream bounded; every build seat takes check asks; the unanswered bound ends an ask left untaken. Owed too, by H-A-319: the node-engine's render marks each derived rule with its scope. | H1's tail (recorded); H2 (the owed); other (the packet filter) |
|
||||
| The pipeline runner's fix of the cut placing (rows 184 and 187) was approved at its second review round at 20:54: the first round had found the stalled rule reading the pipelines through the seat's strict decode, which refuses the runner's own property `kept-revisions` (the live cause of the show verb's refusal, row 183), and counting a required waiting step (an approval, a pin-held step) as nothing open; both are fixed, the property dropped before the seat's decode, so show, stands and the health read every record again; the five-minute bound stays a value named in the code with the rule it comes from (H-A-322). It joins the merges waiting on the operator's word, now five (rows 174, 177 and 187). Meanwhile the lead resumed the home server's Go build module, found paused with a capacity of one while the operator's desktop took every check ask (row 189), and the laptop's, whose Go build module a passed pipeline had delivered at 18:20 (main.131, release 0.1.125, read by a watcher); check asks now run on three nodes. The packet filter's design parts are whole at 41005dfc, with every build form through H-A-321 (rows 183, 187 and 189); the pipeline runner (`mesh-delivery-pipeline`), the Go build module (`mesh-build-go`) and the packet filter module. Owed, by H-A-322: a settings form a tools program can read. | H1's tail (the runner); other (the packet filter) |
|
||||
| The packet filter's build (rows 185 to 190) reached its third repository at 20:56: the node-engine seat's whole definition in the contracts repository gained the read verb `converged` (the node's convergence state: adopted or converged, since when, and the found firewall when adopted) and the composition answer's field `withheld-parts` (which part a compose kept because its read did not answer, and why), with the fixtures and the generated Go and TypeScript packages, the seat generator's check clean; the holder's build takes the verb from that package, and the node-engine's serving of it follows in the fourth repository. The group's heads so far: the networking repository's seat definition (being amended for the reviews' forms), the catalog repository's holder (the same), and the contracts repository's seat of the node-engine (rows 185, 186 and 190); the packet filter module and the node-engine. | other (the packet filter) |
|
||||
| The packet filter's fourth part is built at 21:08: the node-engine renders one rule per allowance after the derived ports, with the comment carrying the allowance's key and time, a timed allowance as a one-element set with a timeout, and, with no allowance, the filter file byte for byte as today; its compose asks the holder's allowed verb within a new setting, keeps the filter file as it runs when the verb does not answer, without holding the holder's module, says the withheld part once, hears the event on its own node's subject, and serves the verb `converged` from its record. The developer read four facts the lead's lines had wrong or left open, three settled by H-A-324: an allowance with no interface would have opened a node's outward link (a hub's internet-facing one), so "no interface" now excludes outward links too, and an outward link is opened only when named; a timed allowance's render again reloads the filter and arms the remaining time again, accepted; the converged answer's since is optional for older records; and the allowances go to the renderer rather than to the reader of the derived rules, since the adoption's openings read the latter. The group's heads: the networking repository 32f0ade8, the catalog repository 09d57583, the contracts repository efcef83c, the node-engine 9c357b6f; H-A-324's change of the render and the validator's verdicts on the node-engine's manifest are the last subtask before the group's one review (rows 186, 190 and 191); the node-engine and the packet filter module. | other (the packet filter) |
|
||||
| The catalog repository's pipeline of 36 movers (rows 184 and 189) stood still a second time: every test had ended by 20:53 (the zfs and forge fixes among them, passed), yet two movers waited "for mesh-grants' packages before their build", though those packages had been published at 20:00, before the wait was written, so no publish event ever came for them; the pipeline runner's health said healthy; the lead restarted the runner at 21:15, and its start pass placed them, the third restart of this kind tonight. H-A-326 settles it on the runner's open branch (a wait on a package is a read first and an event second; a pipeline whose movers only wait on packages counts as nothing open for the stalled rule; the journal says which way a wait resolved), so the fifth merge waiting on the operator (row 190) moves to a new head after its review. The packet filter's design gained H-A-325: the holder reads no shape of the loaded table to tell an outward link; the converged answer carries the node's links (the tunnel's name, the list of outward links) as the node-engine classifies them for its render, and a kept allowance names the outward link it opens; the design parts are at 3a969c6b (rows 184, 189 and 192); the pipeline runner (`mesh-delivery-pipeline`), the node-engine and the packet filter module. | H1's tail (the runner); other (the packet filter) |
|
||||
| The restart of row 193 ended the catalog repository's pipeline at 21:15:30 through the pipeline runner's start pass (row 159's rule that ends an empty pipeline, at work): it ended failed on the Node build module's integration tests, whose setup took forty seconds against a thirty-second bound while three nodes' checks ran, and on the recovery module's whole test; the zfs and forge test fixes passed in it, so their kinds are closed, while the laptop's Go build module stays at its earlier release, since a failed pipeline writes no wants; the next pipeline was placed at 21:15:42 (rows 159, 165 and 193); the pipeline runner (`mesh-delivery-pipeline`), the Node build module and the recovery module. Owed, by H-A-327, of H-A-294's kind: a setup bound read from the step's own bound; a whole-module test that needs the bus's time under load says NOT RUN rather than failing; both fixed in their modules before the next release that carries them. | H1's tail (recorded); H2 (the two tests) |
|
||||
| H-A-326's read (row 193) met the fact that the pipeline runner's record knows only the publishes it heard, and a package published before a pipeline existed is in no record of it (the two movers' packages had been published by an earlier pipeline at 20:00); the builder owns publishes, so H-A-328 gives the seat mesh-builds a read verb `published` (module, artifact and fingerprint; answering published, version, digest and when), served by the builder from its reservations and the registries' record, which the runner asks once when it writes a mover's wait on a package, the publish event staying the second path. The seat mesh-builds is defined in the delivery repository's own contracts module (not in the contracts repository, as the lead's map had it; H-A-328 is corrected so), so the runner's open branch stays one branch in one repository, holding the seat's definition, the builder's serving and the runner's asking, and the fifth merge waiting on the operator (row 190) keeps one head, new after its review (rows 190, 193 and 194); the pipeline runner (`mesh-delivery-pipeline`) and the builder. | H1's tail (the runner and the builder) |
|
||||
| The packet filter's group was complete at 21:23, an hour after the operator's decision (rows 180 to 195): the networking repository's seat definition, made whole (the six verbs, the event, the state per machine, a kept allowance naming its outward link, rules listing what is loaded but not kept); the catalog repository's holder (27 tests, type-checked against the generated packages, the catalog's 33 checks green, the manifest validator accepting its manifest); the contracts repository's seat of the node-engine (the read verb `converged` with the node's state and links, the composition answer's withheld parts); and the node-engine (the compose asking allowed within its bound, the filter kept as it runs when unanswered, the render with timed sets and the default excluding outward links, the event heard, `converged` served from the render's own sources); the one review of the four heads began at 21:24. One fact for the pipeline's check: the manifest validator, run against the trunk's seat files, refuses the node-engine's manifest in both cases for a cause that predates the change (two registry seats' versions verbs absent from those files), which the live seat list is believed to carry; the pipeline's own validate decides (rows 186, 192 and 195); the packet filter module and the node-engine. | other (the packet filter) |
|
||||
| The pipeline runner's open branch (rows 190, 193 and 195) gained H-A-326 and H-A-328 at 21:25 in three commits: a step held waiting on a package's publish counts as nothing open for the stalled rule; the seat mesh-builds gains the read verb `published` (module, artifact and fingerprint; answering published, version and digest), served by the builder from a reservation of that fingerprint whose artifact is marked published, or from a kept release of it; and the runner, when it writes a mover's wait on a package, asks it once per package and fingerprint and places the mover at once when the answer is published, the journal saying "placed from the published record" apart from an event; a package published before the pipeline existed thus no longer holds a pipeline until a restart. Two manifests and the seat's definition changed, so the manifest validator runs before the branch's third review; the approved head of row 190 is superseded by this one (rows 190, 193 and 195); the pipeline runner (`mesh-delivery-pipeline`) and the builder. Owed: the answer's time, never filled because the builder keeps no publish time, with that record. | H1's tail (the runner and the builder) |
|
||||
| The manifest validator's run on the pipeline runner's branch (row 197) at 21:28 found the change adding no problem: with the branch's seat definition, the change case's verdicts equal the trunk case's for every one of 157 manifests. But the builder's and the runner's manifests are refused in both cases, on fifteen and three lines naming verbs of the registry and build seats that the validator program does not see in the repositories' trunk seat files (they declare acts and accepts), lines the live validate of the same modules passed today; every developer and reviewer runs the validator this way, because the live answer of the seat list is too large to read into a session. The branch's third and last review began at 21:30 (rows 190, 196 and 197); the pipeline runner (`mesh-delivery-pipeline`), the builder and the indexer's manifest validator. Owed, by H-A-329: the seat mesh-catalog answers the seat list as one object a validator run takes; and the validate step counts only the problems new against its before case for a touched module (the reader found it counts every problem). | H1's tail (the runner); H2 (the validator's reads) |
|
||||
| The two reviews came back at 21:34 and 21:35, neither approving. The packet filter's group (row 196): five findings, one a real fault (the holder accepted an expiry without seconds that the node-engine's time reader refuses, so every later compose would have withheld the filter), the others form (the verbs served before the holder's start had said started; the holder copying the seat's names instead of importing the generated package, the copies already drifted; the seat definition's description of the default set stale; the stored copy of the node's grant lacking the event's subscription), all in one developer's hands; the holder's ten-second bound on its converged ask stays a value (H-A-330). The pipeline runner's branch (row 197), third round: one finding, the published answer never carrying its time, and never the digest for a release, which the builder did not keep; H-A-331 settles it (the publish time kept on the mark from now on, a release keeping its digest, both absent for older records and said so; a withdrawn number never answered published). The lead takes a fourth look at that one commit rather than a fourth round: the rule of three rounds bent for a detail of form, and said here (rows 196, 197 and 198); the packet filter module, the node-engine, the pipeline runner (`mesh-delivery-pipeline`) and the builder. | other (the packet filter); H1's tail (the runner) |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,347 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H
|
||||
updated: 2026-11-20
|
||||
decisions:
|
||||
- "ADR 0499"
|
||||
- "ADR 0573"
|
||||
- "ADR 0682"
|
||||
---
|
||||
# 47, milestone H — the pin rule: its specification and its gaps
|
||||
|
||||
The rule by which a catalog entry pins the mesh packages a module's build resolves, written whole from the lead's
|
||||
answers H-A-147, 151, 154, 155, 156, 157, 161, 162, 165, 167, 168, 170, 172, 173, 183, 184, 185, 186, 188, 192, 194,
|
||||
198, 201, 202, 203, 204, 205 and 206 ([H-lead-answers.md](H-lead-answers.md)), G §370
|
||||
([G-7-answers.md](G-7-answers.md)), ADR 0499 §1 to §4 and ADR 0573 §2 and §4 (the knowledge base), then held against
|
||||
the code as it stands after the evening's three fix branches.
|
||||
|
||||
A word first. The glossary's **pin** is a person's choice of provider for a consumer (Provisioning). This file, as the
|
||||
lead's answers do, uses "pin" for the version a catalog entry names for a mesh package its module's build resolves.
|
||||
That is a second sense the glossary does not hold; the proposed word is **package pin** (a catalog entry's version of
|
||||
one mesh package its module's build resolves, its key the package's Go module path), to be added in its own pull
|
||||
request. Until then "pin" below means the package pin, and "revision pin" means a record keeping a catalog revision
|
||||
(the indexer's state `pins`).
|
||||
|
||||
## The code read
|
||||
|
||||
| Part | Repository | Read at |
|
||||
|---|---|---|
|
||||
| The indexer (seat `mesh-catalog`) | mesh-delivery, module mesh-delivery-indexer | main `b9cc9747` plus branch `fix/47-H1-indexer-repin` at `94202fb6` (commits `0418a2b9`, `94202fb6`); the tool commit said to be in progress was not in the branch's worktree (clean at `94202fb6`) |
|
||||
| The pipeline runner (seat `mesh-pipeline-runner`) | mesh-delivery, module mesh-delivery-pipeline | branch `fix/47-H1-runner-step-pins` at `e3fed775` (commits `a926a40e`, `e3fed775`) over main `b9cc9747` |
|
||||
| The builder (seat `mesh-builds`) | mesh-delivery, module mesh-delivery-builder | branch `fix/47-H1-builder-revision-picture` at `0fcc614e` (one commit over main; its worktree clean) |
|
||||
| The Go build module (seat `node-build-go`) | mesh-catalog, module mesh-build-go | main `34a884ff` |
|
||||
| The delivery SDK's build step and step runner | mesh-delivery, module mesh-delivery-sdk, packages `buildstep`, `steprun` | main `b9cc9747` |
|
||||
|
||||
Every fact below names its file and function, read with `git show` at those heads; no line numbers (they move).
|
||||
|
||||
## 1. The specification
|
||||
|
||||
### What an entry pins
|
||||
|
||||
- **S1** An entry's `packages` names every mesh package its module's Go build requires, read from the `require` lines of
|
||||
the go.mod files at the take-in, at any version, the zero version and `// indirect` included, with no build needed
|
||||
(H-A-157, H-A-201).
|
||||
- **S2** The set is transitive across the module graph the go.mod files give, not only the module's direct requirements
|
||||
(H-A-201).
|
||||
- **S3** A requirement of the module's own repository is never pinned: it is built from the tree (H-A-198, H-A-201,
|
||||
H-A-202), whether or not that package is also published.
|
||||
- **S4** A pin's key is the package's Go module path as go.mod requires it, a nested module's whole path included
|
||||
(`<repository>/modules/<m>/go/clients/<c>`), never a root path or a module's name (H-A-183: "the package path").
|
||||
- **S5** A pin's version is the newest version the registry seat published for that package path, as the registry's
|
||||
published events name it (path and version); never a module's release number, never a commit (H-A-161, H-A-183;
|
||||
G §370: a Go package's version is its tag).
|
||||
- **S6** The pin stays within the series the module accepts: the one its manifest names in `packages`, the default
|
||||
where it names none, whether or not a series value holds contents; a publish in another series pins nothing and moves
|
||||
nothing (H-A-184, H-A-185). A package artifact's series is its module's version series (H-A-188).
|
||||
- **S7** The pin is always the newest release in that series; an older version never stands over a newer release
|
||||
(H-A-167).
|
||||
- **S8** A requirement of another repository with no published version in its series is named with an empty version,
|
||||
never left out (H-A-161, H-A-204).
|
||||
- **S9** A pin is written `vMAJOR.MINOR.PATCH` everywhere it is carried (G §370's tag form; the step contract's
|
||||
semantic-version form), and only an empty version stands for "none yet".
|
||||
- **S10** A Go package path another module imports is a declared package artifact of its module; the catalog's check
|
||||
refuses a manifest whose Go module imports a mesh package path no module declares (H-A-186).
|
||||
|
||||
### When an entry is computed and pinned again
|
||||
|
||||
- **S11** The entry and its pins are computed at the take-in of every watched branch, for every module the take-in
|
||||
holds (H-A-157; H §743).
|
||||
- **S12** A package's publish pins again every kept entry, of any repository and whether or not its module changed,
|
||||
that names the path with no version or an older one in its accepted series (H-A-165, H-A-204).
|
||||
- **S13** The pins move on the event, never waiting for a merge or a hand act (H-A-165).
|
||||
- **S14** A pin that moves moves the importer's fingerprint; the importer becomes a mover, and the builder builds a new
|
||||
key against the release (H-A-167; ADR 0573 §3).
|
||||
- **S15** A failed re-pin is not acknowledged, so the publish is delivered again (H-A-167).
|
||||
- **S16** The indexer answers one entry's `packages` and paths at a revision through a tool, without the whole revision
|
||||
(H-A-204; tools-are-how-a-module-is-spoken-to).
|
||||
|
||||
### What the fingerprint takes in
|
||||
|
||||
- **S17** Every form's fingerprint (the version line's and the import form's) takes the module's pins, sorted; a
|
||||
fingerprint with no pin stays as it was (H-A-167, H-A-172; ADR 0573 §2).
|
||||
- **S18** The objects of every same-repository module directory the build derives from the go.mod files enter the tree
|
||||
input, a line per directory, for every form, without being written into the entry; the entry's `paths` keep the
|
||||
manifest's form (H-A-199 as H-A-202 amends it).
|
||||
- **S19** A module whose every artifact names its paths takes its tree input from the manifest and those paths (ADR
|
||||
0499 §2).
|
||||
- **S20** A build's reported imports refine the go.mod's set and never replace it with an empty one while go.mod names
|
||||
a mesh package (H-A-157).
|
||||
|
||||
### Who carries the pins into which ask
|
||||
|
||||
- **S21** The builder takes a build's pins from the catalog entry alone and never computes one (H-A-192).
|
||||
- **S22** The builder's own build ask of a lane (the trunk build it puts on the build seat's stream) carries the same
|
||||
pins (ADR 0573 §2: the build writes those versions into its workspace; H-A-192).
|
||||
- **S23** The runner puts the entry's pins into every step ask's fetch (lint, unit, integration), the same pins the
|
||||
builder gives the build (H-A-203).
|
||||
- **S24** A run on request's build step ask names no source revision (H-A-162).
|
||||
|
||||
### What waits
|
||||
|
||||
- **S25** A build step ask names its branch and source revision; when the builder's picture does not hold that revision
|
||||
yet, the ask waits for the picture to take it in, woken by the state's change events and by each revision the view
|
||||
takes in, up to `revision-wait-minutes` (1 to 60, default 2), then fails loud naming the revision and the branch; a
|
||||
build with no version is never made (H-A-155, H-A-156, H-A-162).
|
||||
- **S26** The builder's picture holds every kept revision: a revision below the newest it heard is read by number
|
||||
through the catalog seat's `revision`; only one above the newest is waited for (H-A-205).
|
||||
- **S27** A build whose entry names a package with an empty pin first asks the package registry seat's `versions` once
|
||||
for that path and takes the newest in the accepted series; else it waits for the registry's published of that path
|
||||
and series, up to `package-wait-minutes` (1 to 120, default 10), and pins the version that event carries; past the
|
||||
bound it fails "package <path> has no released version" (H-A-165, H-A-192, H-A-194).
|
||||
- **S28** The runner asks a Go artifact's lint, unit and integration steps only when every pin of its entry has a
|
||||
version; until then the steps stand as "waits on the publish of <path>", and end as the build ends when the bound
|
||||
passes; the publish pins the entry again and moves the mover to its new fingerprint, whose pipeline runs them
|
||||
(H-A-206).
|
||||
|
||||
### What refuses
|
||||
|
||||
- **S29** The Go build module refuses, loud, a requirement of another repository the ask gives no pin for (H-A-192).
|
||||
- **S30** It never takes another path's version, a sibling's version or the latest for it (H-A-192, H-A-201).
|
||||
- **S31** It builds a same-repository requirement from the fetched tree, transitively through those modules' own
|
||||
go.mod files, and keeps those directories in the narrowed tree (H-A-198, H-A-202; ADR 0499 §4: a build sees only its
|
||||
named paths).
|
||||
- **S32** A version a repository's go.mod names is read as the oldest it accepts, and nothing more; nobody fixes a
|
||||
version by hand (ADR 0573 §2).
|
||||
|
||||
### What keeps the revision an entry lives in
|
||||
|
||||
- **S33** The take-in pins the branch's newest kept revision for the same pipeline record as its own, and writes that
|
||||
revision's number as the field `base` on the revision it writes, absent on a branch's first take-in; both are freed
|
||||
with the pipeline (H-A-147, H-A-151, H-A-154).
|
||||
- **S34** A passed pipeline pins, under `release.<branch>.<module>`, the revision of each mover that released a version;
|
||||
a newer pipeline's `pipeline-wanted` with outcome running frees it from the revisions below only where the newer
|
||||
revision holds that module's release record (H-A-168, H-A-170, H-A-173).
|
||||
|
||||
### From the records, not judged here
|
||||
|
||||
- **S35** A delivery group's check builds its members against the group's own heads (ADR 0573 §4). Milestone H's runs
|
||||
on request replace the earlier model's group check; whether §4 still asks anything of the pin rule is a question for
|
||||
the lead, not this table.
|
||||
|
||||
## 2. The gap table
|
||||
|
||||
Sizes: S one function (under an hour), M one module's part (a day), L the part's shape (more than a day).
|
||||
|
||||
| Line | Status | Where | What the code does instead | Size |
|
||||
|---|---|---|---|---|
|
||||
| S1 | built | mesh-delivery-indexer: `cmd/.../named.go` (the go.mod read, `fingerprint.MeshRequiresOf`); `internal/index/package_trees.go` `otherRequired`; `internal/index/versions.go` `releasedPins` (branch indexer-repin, its `required` argument) | | |
|
||||
| S2 | built otherwise | `internal/index/package_trees.go` `sameRepositoryRequired`, `otherRequired` | The reading follows only same-repository modules' go.mod files; a pinned package's own requirements (another repository's go.mod) are never read, so a transitive requirement is pinned only where the module's own go.mod lists it as `// indirect` (a tidied go.mod). | M |
|
||||
| S3 | built | `releasedPins` (skips `trunk.SameRepository`); `fingerprint.OtherPackages` | The indexer never pins a same-repository package, published or not. The Go build module's side is S31. | |
|
||||
| S4 | built | indexer `HearVersion` (`GoModule` from the registry's published `Module`), `releasedPins` (`s.GoModule == p`); builder `PackagePublished` (keyed by the published `Name`); mesh-build-go `takeZeroRequirements` (`asked[p.module]`) | The key is the full Go module path on every side. Live: the registry holds `.../modules/mesh-grants/busgrants` at 0.1.48 under its nested path (the indexer's `indexer_package_users`). | |
|
||||
| S5 | built | `releasedPins` (branch); `fingerprint.WithPins` | The entry's pins are registry versions. The fingerprint's version line still takes commits (leftover L1). | |
|
||||
| S6 | built | `releasedPins` (`m.AcceptedSeries(s.Name)`); builder `awaitPublished` (`man.AcceptedSeries(p)`) | The rule that a package artifact's series is its module's version series (H-A-188) lives in the catalog's check, outside these modules: not judged. | |
|
||||
| S7 | built | `releasedPins` (the highest in the series) | | |
|
||||
| S8 | built | `releasedPins` with `required` (branch indexer-repin `0418a2b9`) | The empty version is refused by a run on request's candidate: `internal/index/candidate_values.go` `checkCandidateModule` runs `sdkstep.PackageVersions.Check`, which accepts only a commit or a semantic version, on `runcandidates.go`'s values copied from the module's `Packages`. A run of a module with a package not yet published fails. | S |
|
||||
| S9 | built | indexer `releasedPins` (`"v"+`), series kept without it (`HearVersion`); builder `publishedPin` (`"v"+`), `PackagePublished` (trims it); runner `stepAsk` (copies); sdk `buildstep` `PackageVersions.Check` (needs `v`); mesh-build-go `takeVersion` (`path@v…`) | One form throughout. The empty version is the one exception S8 names. | |
|
||||
| S10 | not judged | the catalog's check (mesh-catalog's manifest check), not one of the modules held here | | |
|
||||
| S11 | built otherwise | indexer `takeInSource` (`takein_source.go`), `recomputeLocked` (`toolchains.go`) | On the first watched branch every module is computed. On another branch the take-in recomputes only the moved repositories' modules and those whose pins name a package of a moved repository; every other entry is carried from that branch's newest revision with the pins it had. | M |
|
||||
| S12 | built otherwise | `cmd/.../series.go` `heardVersion` (a registry's published runs `Recompute` of every module); `versions.go` `releaseVersion` calls `repin`; `toolchains.go` `Repin` (branch: by pins and by kept requirements) | Two paths move the pins, both in the first watched branch's view only (`ix.Modules`). A kept catalog revision is never rewritten, and another branch's entries are not pinned again. | M |
|
||||
| S13 | built otherwise | as S12; `catalog_revisions.go` `keepBranchEntries` is called only from `takeInSource` | The view moves on the event, but an entry anyone reads (the builder, the runner, the node-engine through the revision) changes only when the next take-in of that branch writes a revision, which only a merge on that branch makes. | L |
|
||||
| S14 | missing | `internal/index/movers.go` `moversOf` | A mover is a module of a moved repository whose fingerprint changed, or a module whose pins name a package a mover publishes. A module whose fingerprint moved by a re-pin is neither, so no pipeline builds or tests it. The builder's picture builds the new fingerprint on its own once a later revision carries it (leftover L5), outside any pipeline, with no test step and no want. | L |
|
||||
| S15 | contradicts (one of two paths) | `cmd/.../series.go` `heardVersion` | The version-released path returns the re-pin's error, so the package-published is not acknowledged (built). The registry-published path logs a failed `Recompute` and acknowledges the event, so that re-pin is lost until the next publish. | S |
|
||||
| S16 | missing | indexer tools (branch indexer-repin holds none) | The seat verb `mesh-catalog.entry` answers one whole entry by fingerprint, not at a revision. The tool H-A-204 asks is the commit still in progress. | S |
|
||||
| S17 | built | `versions.go` `pinnedOf`; `fingerprint.WithPins`; `form.go` `formOf` (import form `stands` kept only while its built pins equal the new ones) | | |
|
||||
| S18 | built | `package_trees.go` `derivedDirs`, `derivedTree` (main `b9cc9747`, merged #296) | | |
|
||||
| S19 | built | `fingerprint.NamedTree` | | |
|
||||
| S20 | built | `form.go` `refined` | | |
|
||||
| S21 | built | builder `internal/build/step.go` `buildEntry` (entry by fingerprint through `mesh-catalog.entry`, then `awaitPublished`) | | |
|
||||
| S22 | built | builder `internal/build/run.go` `runLane` (`awaitPublished`, `ask.Packages`) | Its `delete(ask.Packages, fb.Package)` loop runs over `req.Builds`, which nothing sets (leftover L6). | |
|
||||
| S23 | built | runner `internal/pipeline/place.go` `stepAsk` (branch runner-step-pins `a926a40e`) | Empty pins are left out, so a step waits for them (S28). | |
|
||||
| S24 | built | runner `place.go` `place` (source 0 for a run) | | |
|
||||
| S25 | built | builder `internal/build/revisionwait.go` `awaitRevision`, `PictureHeld`; `module.json` `revision-wait-minutes` | | |
|
||||
| S26 | built | builder `revisionwait.go` `keptRevisionHolds`; `cmd/.../keptrevision.go` `keptRevisionVia` (branch builder-revision-picture) | The kept revision is judged by its source and its fingerprints; the pins used are then the entry read by fingerprint (S21). | |
|
||||
| S27 | built | builder `revisionwait.go` `awaitPublished`, `PackagePublished`; `cmd/.../versions.go` `publishedVersionsVia`; `cmd/.../seats.go` (the published heard); `module.json` `package-wait-minutes` | | |
|
||||
| S28 | built otherwise | runner `place.go` (`unpinnedPackage`, `PinWait`, `endPinHeld`); `steps.go` `OnStepEndedShared`, `endPipeline` (branch runner-step-pins `e3fed775`) | A failed build ends the waiting steps with its outcome (built). When the build passes, `endPinHeld` ends none and nothing asks them: a waiting required step holds `endPipeline`, so the pipeline never ends and holds its place in the queue. The line counts on S14 (a new pipeline at the re-pinned fingerprint), which is missing. | M |
|
||||
| S29 | built | mesh-build-go `cmd/mesh-build-go/pins.go` `takeZeroRequirements` ("no pin for … the builder pins or waits") | | |
|
||||
| S30 | built | as S29; `versions.go` `takeRequirementsOf` leaves forge modules to their own rule | | |
|
||||
| S31 | built otherwise | mesh-build-go `pins.go` `takeZeroRequirements`, `useOwnModules`; `narrow.go` `ownZeroPackageDirs` | Only a same-repository requirement at the zero version comes from the tree. One at a real version is fetched at that version through the Go seat, while the indexer's fingerprint takes the tree's objects (S18): the build and its key disagree. The repository test is the literal owner prefix `"novox/"+p.repo`, a value written into the code. | S |
|
||||
| S32 | built | mesh-build-go `versions.go` `takeVersion` (a newer go.mod version is built, and said) | | |
|
||||
| S33 | built | indexer `catalog_revisions.go` `keepBranchEntries` (`rev.Base`, the newest pinned in the same write); `pins.go` `HeardPins`, `unpinElsewhere` | | |
|
||||
| S34 | built | indexer `pins.go` `HeardPins` (a release record only for a mover with a version), `HeardPipelineWanted` (running only; the newer revision's own release record) | | |
|
||||
| S35 | not judged | | The question of whether ADR 0573 §4 still binds after the runs on request is the lead's. | |
|
||||
|
||||
Counts: 35 lines; built 24, built otherwise 6, contradicts 1, missing 2, not judged 2.
|
||||
|
||||
### The six points the lead asked about
|
||||
|
||||
1. **The pin key's form.** On the branches every side keys by the full Go module path: the indexer from go.mod and the
|
||||
registry's published `Module`, the builder from the published `Name`, the Go build module by `p.module`. A nested
|
||||
path is pinned when the registry published that path (H-A-186's artifacts). The builder writes one git tag per
|
||||
release, `go/v<version>` (`internal/versions/tag.go` `GoTagOf`), never `<package dir>/v<version>`. The fetch asks the
|
||||
Go seat first, so the tag is not on the path, but if the seat misses and the fetch falls through to the forge's git,
|
||||
a nested path's `@v0.1.x` is an unknown revision (leftover L9). I think the refusals of nested paths seen earlier
|
||||
came from the pins of H-A-161 (the module's release number) and the undeclared artifacts H-A-186 names. Both are
|
||||
fixed on main and on the branches; the running indexer predates them (section 3).
|
||||
2. **Reported imports against the go.mod graph.** `formOf` takes the import form when a build reported imports, and
|
||||
`fingerprint.Resolve` gives versions only for the holders of what was imported. Since `0418a2b9`, `releasedPins`
|
||||
adds every requirement the go.mod graph names (`required`), so the entry's pin set no longer shrinks to the imports.
|
||||
The `stands` case keeps `prev.Packages` only while those equal the new pins (`pinnedOf`), so a moved pin moves the
|
||||
fingerprint (S17).
|
||||
3. **The recompute of unchanged modules of other repositories** (`recomputeLocked`, the held-stands guard). At a
|
||||
take-in naming repository R, a module of another repository is recomputed only when its new pins name a package of
|
||||
R (`importsOf`). Since `0418a2b9` that set includes requirements with an empty pin, so an importer of R's package is
|
||||
recomputed. Any other module keeps its held value. A publish recomputes every module of the first watched branch's
|
||||
view (`Recompute` on the registry's published) or the modules naming the released module's packages (`Repin`).
|
||||
Other watched branches are not reached (S11, S12).
|
||||
4. **The lane path's trunk asks.** `runLane` waits in `awaitPublished` and copies the filled pins into `ask.Packages`
|
||||
for a Go fetch with any pin (S22). The lane runs both for a step ask and for the builder's own picture-driven builds
|
||||
(L5).
|
||||
5. **A same-repository requirement that is also published.** The indexer never pins it. The Go build module builds it
|
||||
from the tree only when go.mod names it at the zero version; at a real version it is fetched from the Go seat at
|
||||
that version (S31).
|
||||
6. **The "v" prefix.** It is one form across the indexer, builder, runner, step contract and Go build module (S9). The
|
||||
empty version is the one value the step contract refuses, which breaks runs on request (S8).
|
||||
|
||||
## 3. The leftovers
|
||||
|
||||
| What | Where | What it does | Line it contradicts |
|
||||
|---|---|---|---|
|
||||
| L1 The version line's commit form | indexer `form.go` `lineVersions` (`fingerprint.HeldVersionsOf`, the gate's heads for an unpublished package, G A-365); `fingerprint.VersionLine` | The fingerprint takes, for each other-repository package, the held module's commit or the branch head's commit. A merge of a package's repository moves every importer's fingerprint before anything is published. | S5 in spirit (H-A-161: never a commit). The pins themselves are versions. |
|
||||
| L2 The accepted series' contents read at the published commit | indexer `series.go` `HearVersion` (`packagesAt`), `acceptedSeries` (DLV-I6) | Reads the published version's package digests through the forge for the import form, keeps a commit form where it cannot. | none (ADR 0593 §2's import form), but a second source of package versions beside the pins |
|
||||
| L3 A whole recompute on every registry publish | indexer `cmd/.../series.go` `heardVersion` | `Recompute` of every module on each published version, beside the targeted `Repin` on version-released. | none; it duplicates S12's path, and acknowledges on failure (S15) |
|
||||
| L4 The requirements state from go.sum | indexer `requirements.go` (`indexer_requirements`, `keepRequirements`, `RequiredOf`) | Keeps per package the highest version each consumer's go.sum names, for the builder's floor. Under the zero version go.sum names none (H-A-157). | none directly; H-A-157 says go.sum is never read for package edges, and H-A-159 removed the builder's own numbering it served |
|
||||
| L5 The builder's picture-driven builds | builder `internal/build/run.go` (the picture's take calls `consider`), `Reconsider`, `Sweep`; `numbers.go` `PackageNamed` | Builds every fingerprint a watched branch's picture takes in, outside any step ask. It is the only path by which a re-pinned fingerprint is ever built today. | none of this part's lines (the earlier model's "the builder builds every fingerprint of the catalog half"); a builder that builds what no pipeline asked is a question for the lead |
|
||||
| L6 Dead pin deletion | builder `run.go` `runLane` (`for _, fb := range req.Builds`) | Deletes from the pins the packages `builds` names, over a list nothing fills. | none |
|
||||
| L7 Commit pins and pull-request heads | mesh-build-go `versions.go` `takeVersion` (a commit resolved to a pseudo-version, else `placePin` from `refs/pull/*/head`), README "A pin on a pull request's head" | Accepts a 40-hex commit as a pin and places a pull request's head beside the workspace. | S5 (H-A-161: never a commit) for a delivery build; it served ADR 0573 §4's group heads |
|
||||
| L8 The literal owner prefix | mesh-build-go `pins.go` `takeZeroRequirements`, `narrow.go` `ownZeroPackageDirs` (`"novox/"+repo`) | Decides "same repository" by a written owner name. | principle 11 |
|
||||
| L9 One Go tag per release | builder `internal/versions/tag.go` `GoTagOf`, `reserve.go` | Tags `go/v<version>` once per module, whatever paths its Go packages have. | none of this part's lines; H-A-183 names `<package dir>/v<version>` as what the forge's Go seat looks for |
|
||||
| L10 The candidate check on pins | indexer `candidate_values.go` `checkCandidateModule`; sdk `buildstep` `PackageVersions.Check` | Refuses an empty version. | S8 |
|
||||
|
||||
## 4. Live against main
|
||||
|
||||
Read through the mesh at 23:00 to 23:10 CET with read tools only (`mesh-delivery-view.node_haves`,
|
||||
`mesh-catalog.entry`, `mesh-delivery-indexer.indexer_package_users`). Machines are named by role; the mapping is a
|
||||
guess (section 7).
|
||||
|
||||
**The indexer**
|
||||
|
||||
| Machine | Build that runs | Main's or by hand | What main and the branches have that it lacks |
|
||||
|---|---|---|---|
|
||||
| the control-node | fingerprint `src2:9ac151c2…`, its entry at commit `f00d3467` (main, 2026-11-20 17:35 UTC) | the entry is main's commit; whether a pipeline or a hand placed it the tools do not say | 8 commits of main on the module: H-A-183, 184, 185 (the pin by path and series), H-A-186, H-A-200, H-A-201, H-A-202; and both commits of branch indexer-repin. Live, the entries of the indexer and the runner still carry 40-hex commits as pins, and the busgrants user `nats` shows no pin though 0.1.48 is published. |
|
||||
|
||||
**The pipeline runner**
|
||||
|
||||
| Machine | Build that runs | Main's or by hand | What main and the branch have that it lacks |
|
||||
|---|---|---|---|
|
||||
| the control-node | `src2:adf598f2…`, entry commit `9598b92c` (main, 17:37 UTC) | the entry is main's commit | H-A-187, H-A-189, H-A-190, H-A-191 (steps per mover); branch runner-step-pins (H-A-203, H-A-206) |
|
||||
|
||||
**The builder**
|
||||
|
||||
| Machine | Build that runs | Main's or by hand | What main and the branch have that it lacks |
|
||||
|---|---|---|---|
|
||||
| the workstation | `src2:48cabb7e…`, held: "entry-missing … src2:f34620ec…" since 17:49 CET | no kept entry names `48cabb7e`, so I take it for a build placed by hand or from before the clean state | not readable: no entry gives its commit |
|
||||
| the control-node | removed ("the applied declaration no longer holds the module") | | |
|
||||
|
||||
**The Go build module**
|
||||
|
||||
| Machine | Build that runs | Main's or by hand | What main has that it lacks |
|
||||
|---|---|---|---|
|
||||
| the control-node, a build node | `src2:ae502407…`, phase failed: "the want … names no digest for mesh-build-go:files, mesh-build-go:tools" | no kept entry names it: placed by hand or from before the clean state | not readable |
|
||||
| the workstation, the laptop | `src2:c69b0f1c…`, the same failure | the same | not readable |
|
||||
|
||||
The delivery SDK is a package, not a running module; nothing of it runs on its own.
|
||||
|
||||
## 5. The tests
|
||||
|
||||
Counted as `func Test` per file; a file whose header carries `//go:build integration` counts as integration. Table
|
||||
rows inside one function count once.
|
||||
|
||||
| Module (head) | Unit | Integration | Starts the module whole against a bus and a store | What the tests would not catch of the gaps |
|
||||
|---|---|---|---|---|
|
||||
| indexer (indexer-repin) | 163 | 6 | yes, `TestIndexerWhole` (`takein_integration_test.go`) | It covers revision pins (S33, S34), not pins of packages: no whole test publishes a package and reads the entry pinned again, the re-pinned module made a mover (S14), another branch's entries (S11, S12) or an acknowledgement after a failed re-pin (S15). Unit tests `TestAnEntryNamesEveryRequirementPinnedOrWaiting` and `TestAReleaseRepinsAnEntryNamingItsPackageWithNoPin` (branch) prove S8 and S12 in the view only. |
|
||||
| builder (builder-revision-picture) | 154 | 18 | yes, `integration_test.go` runs `run` | Nothing ties the lane's pins to an entry with an empty pin across a restart; the branch's unit test proves S26. |
|
||||
| runner (runner-step-pins) | 91 | 4 | yes, `run_integration_test.go` runs `run` | No test builds a mover whose pin-held steps outlive a passed build (S28); the branch's `testruns_integration_test.go` checks the pins in the fetch (S23). |
|
||||
| Go build module (main) | 217 | 18 | I found none that runs the module's `run` (guess; section 7) | Nothing fetches a same-repository requirement at a real version (S31) or a transitive other-repository requirement not in the go.mod (S2). |
|
||||
| delivery SDK `steprun` + `buildstep` (main) | 113 (of the module's 150) | 13 (all in `steprun`) | not applicable (a package) | Nothing runs `PackageVersions.Check` on an empty version from a candidate (S8). |
|
||||
|
||||
All five are inside the budget of 500 unit and 50 integration tests per module.
|
||||
|
||||
## 6. Fix in place or write again
|
||||
|
||||
**The indexer.** Fix in place. 14 of its 21 lines here are built. The pin's computation (S1 to S9, S17 to S20) and the
|
||||
revision pins (S33, S34) follow the design. Its shape breaks in one place: a re-pin reaches only the in-memory view of
|
||||
the first watched branch, and nothing turns a moved fingerprint into a catalog revision and a mover (S12 to S14, L).
|
||||
That is a design question before it is code. A revision is numbered by its source (H-A-32), and a publish has no
|
||||
source, so the design must say what takes in a re-pin (a take-in the publish itself starts, or a revision of its own
|
||||
form). The rest are S: the acknowledgement (S15), the empty pin in a run's candidate (S8), the tool (S16).
|
||||
|
||||
**The builder.** Fix in place. Its four lines (S21, S22, S25 to S27) are built on the branch, in the design's shape
|
||||
(events and a bound, the versions verb read before the wait). Its open question is L5: it builds every fingerprint its
|
||||
picture takes in, outside any pipeline. Today that is the only path that builds a re-pinned key, so it must not be
|
||||
removed before S14 is built.
|
||||
|
||||
**The pipeline runner.** Fix in place. S23 and S24 are built, and S28 is built but for one case: a pin-held step whose
|
||||
build passed is never asked and never ended (M). It needs a design line for that case, for example asking the steps
|
||||
with the pins the build resolved, which its step end would have to carry, or ending them "not asked" in favour of the
|
||||
re-pinned mover's pipeline once S14 exists.
|
||||
|
||||
**The Go build module.** Fix in place. S29, S30 and S32 are built; S31 holds only at the zero version and on a
|
||||
literal owner name (S each). L7, the commit and pull-request-head pins, is the earlier model's and can go once no ask
|
||||
names a commit.
|
||||
|
||||
**The delivery SDK.** Fix in place: one change, the candidate check's treatment of an empty pin (S8), shared with the
|
||||
indexer.
|
||||
|
||||
## 7. What I could not read, and what I guessed
|
||||
|
||||
- I could not send the lead an interim status mid-run: this agent has no messaging tool but its final report.
|
||||
- **The tool commit of branch indexer-repin** was not in its worktree (clean at `94202fb6`), so S16 is judged missing.
|
||||
Check: `git log fix/47-H1-indexer-repin` once it lands.
|
||||
- **The builder's and the Go build module's running builds** have no kept entry (`mesh-catalog.entry` answers "no
|
||||
entry of fingerprint … is kept"), so their commits are unknown. That they were placed by hand is a guess. Check: the
|
||||
node-engine's composition of those modules on each machine (`<node>/node-engine.composition`).
|
||||
- **Whether a pipeline or a hand placed the indexer and the runner** is not said by the tools I used; their entries'
|
||||
commits are main's.
|
||||
- **The role of each machine** is a guess from the mesh's instructions (the control-node, the workstation, the laptop,
|
||||
a build node). Check: `mesh-controller.nodes`.
|
||||
- **The Go build module's whole test:** I searched its tests for a call of `run` and found none. A test that starts it
|
||||
another way may exist. Check: read its `*_integration_test.go` files.
|
||||
- **S2 in practice:** whether every mesh go.mod lists its transitive mesh requirements as `// indirect` I did not read.
|
||||
Check: `go mod tidy` is a lint step, or read a module's go.mod at main.
|
||||
- **The cause of the earlier nested-path refusals** (point 1) is a guess from the lead's answers, not from a record of
|
||||
those builds. Check: `records_search` with the refused build's words.
|
||||
- Line numbers are not given, by this agent's way of working (they move with every commit); each fact names its file
|
||||
and function.
|
||||
|
||||
## 8. The shortest list of changes still missing after the three branches
|
||||
|
||||
1. **A re-pin becomes a revision and a mover** (S12, S13, S14). Owner: the indexer (its take-in), after a design
|
||||
line from the lead or the design writer on what takes a re-pin in, since a revision is numbered by its source
|
||||
(H-A-32). It also covers every watched branch, not only the first (S11). Size L.
|
||||
2. **A pin-held step whose build passed** is asked with the pins the build resolved, or ended for the re-pinned
|
||||
mover's pipeline (S28). Owner: the runner, with a design line. Size M.
|
||||
3. **A failed re-pin on the registry's published is not acknowledged** (S15). Owner: the indexer, `heardVersion`.
|
||||
Size S.
|
||||
4. **An empty pin passes a run on request's candidate** (S8, L10). Owner: the indexer's `checkCandidateModule`, or the
|
||||
SDK's `PackageVersions.Check` with an "empty allowed" form for entries. Size S.
|
||||
5. **The tool answering one entry's pins and paths at a revision** (S16). Owner: the indexer. Size S (in progress).
|
||||
6. **A same-repository requirement at a real version comes from the tree**, and "same repository" is read from a
|
||||
setting or the fetch, not the literal owner (S31, L8). Owner: the Go build module. Size S.
|
||||
7. **Transitive other-repository requirements** are pinned from the pinned packages' own go.mod files, or a check
|
||||
refuses an untidied go.mod (S2). Owner: the indexer, or the catalog's check. Size M; needed only if a go.mod is
|
||||
found that does not list them.
|
||||
|
||||
L1 (the commit form in the fingerprint's version line) is left in place until item 1 lands, since today a
|
||||
package's merge moving its importers' fingerprints is what makes them code dependents in that pipeline at all.
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
---
|
||||
# 47 H2 build map: `mesh-catalog`
|
||||
|
||||
Read at `origin/main` `553bfb0ccf7c` (2026-11-21 18:30 UTC), from an archive of that commit. Design: hq `35ddd45e`.
|
||||
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
|
||||
|
||||
## What exists today
|
||||
|
||||
Searches as run, from the archive's root `mesh-catalog/`: the holders of each seat by `"name": "<seat>"` in
|
||||
`modules/*/module.json` with `claims`; `grep -n "function \|mint\|vault\|lease\|401" modules/gitea/token.ts`;
|
||||
`grep -rn "not the sweep\|purge\|chunk" --include='*.go' modules/distribution`; `grep -rn "check-needs\|NeedsMarker"
|
||||
--include='*.go' modules/mesh-build-go`; `grep -rn "over-budget\|budget" --include='*.go' modules/mesh-self-check
|
||||
modules/mesh-delivery-gate`; `grep -rn "H-A-237\|cancel" --include='*.go' modules/nats/internal/keeper/requests.go`; each
|
||||
tool of the H2 tools table by its quoted name.
|
||||
|
||||
1. **What exists today.**
|
||||
- Holders: the seat `git`, `go-package-registry` and `npm-package-registry` are `gitea`'s (the forge module, TypeScript);
|
||||
`oci-artifact-registry`, `container-image-registry` and `mesh-artifact-store` are `distribution`'s; the sweep's seat is
|
||||
`mesh-artifact-sweep`, held by `artifact-store-tools`; `node-packet-filter` is `nftables`' (TypeScript, verbs `rules`,
|
||||
`reload`, `remove`, one tool `firewall_rules`); `mesh-broker` is `nats`'; `mesh-self-check` is `mesh-self-check`'s;
|
||||
`mesh-delivery` is the gate's (`modules/mesh-delivery-gate`).
|
||||
- The forge module mints its admin token per process into a 0600 file in its state directory with a lock file beside it
|
||||
(`modules/gitea/token.ts:5-33`, `:131-285`); it answers a refused admin as `AdminRefused` worded as an account to create
|
||||
(`token.ts:95-101`); its seat error answers say `refused` or `failed` (`modules/gitea/seat.ts:71`). No tool reads a
|
||||
token lease; no `forge_merged`.
|
||||
- The gate keeps the ledger `records` (requires, ledger template, 768 MiB; `modules/mesh-delivery-gate/module.json`
|
||||
`requires`) and the state `source`; its tools include `gate_record`, `gate_records`; no `gate_times`.
|
||||
- The self-check holds no delivery budget probe (search above found none).
|
||||
- The build modules ask for `steps` (state, TTL 172,800 s, objects 256 MiB), `detected-steps`, and the Go one
|
||||
`kept-builds` objects; none keeps `outputs` (`modules/mesh-build-{go,node,image}/module.json` `requires`).
|
||||
`check-needs` is a marker file in a package's directory, chosen "not a manifest field"
|
||||
(`modules/mesh-build-go/cmd/mesh-build-go/digest.go:59-66`).
|
||||
- The registry refuses a removal by any caller but the sweep (`modules/distribution/internal/holder/verbs.go:165-166`);
|
||||
its `list` takes `name` only (the seat's definition in `mesh-delivery`); its chunk delete is
|
||||
`cmd/distribution-tools/bounded.go:62`.
|
||||
- The bus module's tools: `nats_consumer` (one), `nats_connections`, `nats_backlog`; no `nats_consumers`
|
||||
(`modules/nats/module.json` `tools`). The keeper asks a drop or recreate at the approve level, naming H-A-237
|
||||
(`modules/nats/internal/keeper/requests.go:75`, `:334`); a refused request does not cancel its ask (no cancel call in
|
||||
that file).
|
||||
- The vault's seat serves `own` to the node-engine of a machine only, read-only, sealed to the machine's key, and a
|
||||
two-step sealed write exists only for the licence manager (`licence-put`) (the seat's definition in `mesh-contracts`
|
||||
`identity-and-access/seats/mesh-vault/seat.json`; claim in `modules/mesh-vault/module.json`). No verb writes a
|
||||
module's own secret from the module.
|
||||
- `nfs-server` and `pacman` hold 0 and 3 integration tests by `-tags integration` (below).
|
||||
2. **What the change touches, and what relies on each.** The token file and its lock (`token.ts`): read only by the forge
|
||||
module's processes. The removal refusal (`verbs.go:165`): relied on by nobody else (every account may call every
|
||||
verb, §813 (7)). The registry's `list` answer whole: read by the sweep (`modules/artifact-store-tools`). The marker
|
||||
file `check-needs`: read by the Go build module's digest (`digest.go:68-80`) and `mesh-delivery-sdk`
|
||||
`steprun.AskNeeds`. The gate's whole-revision ledger entry: read by `gate_record`, `gate_records`, `delivery_status`,
|
||||
the gate's `deliveries` and `show` verbs (`cmd/mesh-delivery-gate/recordtools.go`, `verbs.go`).
|
||||
3. **Fates.** The per-process mint goes (§808); the refusal "not the sweep's" goes (§813 (7)); the whole-revision entry
|
||||
goes (§809); the Node build module's and the recovery module's setup bounds in code go (§800); the marker file's fate
|
||||
against §800's manifest field is DMC-6. New parts and their lines: state `token-lease` (§808, §820), `outputs` objects
|
||||
(§791, §820), settings `owed-away-bound` (§807, the bridge's), `token-ttl`, `mint-lease` (§808), `budget-core`,
|
||||
`budget-leaf` (§810), `again-delays` (§799), tools `forge_token_lease`, `forge_merged`, `gate_times` (the tools table).
|
||||
|
||||
## Rows
|
||||
|
||||
| line | files and functions | subtask | acceptance (cites) | test |
|
||||
|---|---|---|---|---|
|
||||
| §776 | `modules/gitea/seat.ts:71`, `token.ts:95-101`, the version read | C1 forge says `away` (waits DMC-2) | a 401 with the version read failing answers `away`; with the read passing and the fresh token refused answers `refused`; the store stopped 30 s, a merge call answers `away` and lands when called again (§776) | unit, whole (forge module) |
|
||||
| §775 | `modules/gitea` the seat `git`'s act verbs (`writes.ts`, `mergecall.ts`): take an ask once by its id, state `taken` | C2 forge takes once | a holder given the same ask id twice acts once (§775) | unit |
|
||||
| §796 | `modules/gitea` `tags` (`seat.ts`, `readall.ts`) answers `commit` per tag | C3 tags with commit (uses `mesh-delivery` D5) | §796 whole (builder) | whole |
|
||||
| §808 | `modules/gitea/token.ts` (vault read and write, lease `mint` in `token-lease`, delete the replaced token), `modules/gitea/tools` `forge_token_lease`, manifest settings | C4 one mint at a time (waits DQ-7) | two processes, one holding the old token, both refused, mint one token in all; the forge holds one token after; a minter killed holding the lease is replaced after `mint-lease` (§808) | unit, whole |
|
||||
| §812 | `modules/gitea/tools` `forge_merged` (repository, from, to) | C5 merged pull requests | per tools table (§812) | unit |
|
||||
| §815 | `modules/gitea/mergecall.ts`, `failedsteps.ts`: judge a source-only head by its registration's policy from the runner's step events | C6 merge a source-only head | an hq pull request whose Go checks fail is refused naming the failed step (§815) | whole |
|
||||
| §809 | `modules/mesh-delivery-gate/cmd/mesh-delivery-gate/record.go`, `recordevents.go`, `recordtools.go`: head entry `<branch>.<source>`, per mover `<branch>.<source>.<module>`, refusal over 64 KiB, finding `record-too-large`; manifest `records` 1 GiB | GT1 ledger per module | 126 movers write 127 entries, none over 64 KiB; an entry made too large raises the finding, cleared at the end (§809) | whole (gate) |
|
||||
| §810 | `record.go` (end: `delivery-time`, `class`, `phases`), `settings.go` (`budget-core`, `budget-leaf`), tool `gate_times` | GT2 delivery times (uses `mesh-delivery` D2) | §810 whole (gate and probe) | whole |
|
||||
| §811 | `verbs.go` `deliveries` filters and cap | GT3 filtered reads (uses D6) | `deliveries` by repository over 4 MB answers under 768 KB (§811) | unit |
|
||||
| §815 | `takenin.go`, `record.go`: a source-only merge watched as any branch, record ends `nothing to deliver` | GT4 source-only record | raises no `head-untaken` and ends `nothing to deliver` (§815) | whole |
|
||||
| §810 | `modules/mesh-self-check` a probe reading the gate's times, condition `over-budget` by class | SC1 over-budget probe | a core record 11 min after `merge-called` raises `over-budget` for `core`; the next within ten minutes clears it (§810) | whole |
|
||||
| §799 | `modules/mesh-build-go`, `mesh-build-node`, `mesh-build-image`: fetch and publish faults end the run `again`; setting `again-delays`; third run `fetch:` or `publish:` | BM1 again on a part away (waits DMC-7) | the kit holds a fetch met by a 401 and a publish met by no responders to `again`, and three such runs to failed with `fetch:` and `publish:` (§799) | conformance kit |
|
||||
| §800 | `modules/mesh-build-go` summary `not-run`, setup bound from `MESH_TEST_LEVEL_BOUND`, could-not-run at the third starved setup; unpack an install archive | BM2 not run and starved setup (waits DMC-6) | the forge module's whole-seat test runs with its npm tree; a starved setup runs again and ends could-not-run at the third (§800) | whole (Go build module) |
|
||||
| §800 | `modules/mesh-build-node`: accepted kind `install`, `npm ci` with no install scripts, the archive in `outputs` under the lock's digest; its setup bound in code goes | BM3 install | an install runs no script (§800) | unit (Node build module) |
|
||||
| §791 | the three build modules: `outputs` objects (1 GiB, 7 days), the verb `output` | BM4 outputs kept | §791 whole (Go build module) | whole |
|
||||
| §801 | the three build modules: `current` per holder, steps read tools never empty while steps run | BM5 current | a paused holder answers `paused` (§801) | whole |
|
||||
| §775 | `modules/distribution` publish: take an ask once by its id, state `taken` | RG1 registry takes once | §775 unit | unit |
|
||||
| §813 (7) | `modules/distribution/internal/holder/verbs.go:165` (refusal goes), `list` paged by `module` and cursor; `modules/artifact-store-tools` reads page by page | RG2 paged list and sweep removals (waits DMC-10) | a pass over 20,000 artifacts removes what it judges (§813 (7)) | whole (sweep) |
|
||||
| §813 (8) | `modules/distribution/cmd/distribution-tools/bounded.go:62`: purge a deleted chunk's subjects | RG3 chunk leftovers | after 1,000 chunks deleted, messages equal live objects (§813 (8)) | whole (registry) |
|
||||
| §813 (5) | `modules/nats/cmd/nats-tools/consumer.go`, `main.go`: `nats_consumers` sorts, `nats_connections` busiest subscriptions | N1 flow tools (waits DMC-11) | unit (§813 (5)) | unit |
|
||||
| §813 (6) | `modules/nats/internal/keeper/requests.go`: a refused request cancels its ask on `operator-channel` | N2 keeper cancels | unit | unit |
|
||||
| §813 (11) | `requests.go:75`, `:334`: the bend's line names the research as its end | N3 bend line | a drop asks at the approve level (§813 (11)) | unit |
|
||||
| §813 (4) | `modules/nftables/client.ts`, `tools/index.ts`: read a port's scope from `rules` | P1 scope from the rule (waits DMC-12) | `allow` without a source is refused for a `private-network` port (§813 (4)) | whole (packet filter) |
|
||||
| §781 | `modules/nftables`: ask `converged` within the verb's `timeout` | P2 converged (waits DMC-12) | §790 | whole |
|
||||
| §808 | `modules/mesh-vault/cmd/mesh-vault` a write verb of a module's own secret (H-A-345) | VA1 (waits DQ-7) | per its answer | unit |
|
||||
| §800 | `modules/mesh-recovery` tests' setup bound in code goes | MR1 | §800 | unit |
|
||||
| §783, §812, §820 | manifests of the gate, the three build modules, `distribution`, `gitea`: findings stream, caps | M1 manifests (waits DQ-5) | the manifest check of §814 | whole |
|
||||
| §819 | `modules/nfs-server`, `modules/pacman` tests | NP1 shrink to 50 integration | the check's counts | check |
|
||||
|
||||
## Order and writers
|
||||
|
||||
- After `mesh-delivery`'s D3, D4, D5, D6 and mesh-sdk's S1 to S3, S6, S11. C3 after D5; GT2 after D2; BM1 to BM5 after D3
|
||||
and the kit (`mesh-delivery` `modules/mesh-delivery-sdk/steprun/conformance`, written by this map's build modules'
|
||||
agent). P1 after the node-engine's render (the node-engine's map, E6).
|
||||
- One writer per file: one agent for `modules/gitea` (TypeScript); one for the gate and the self-check; one for the three
|
||||
build modules and the conformance kit; one leaf agent for `distribution`, `artifact-store-tools`, `nats`, `nftables`,
|
||||
`mesh-vault`, `mesh-recovery`, `nfs-server`, `pacman`.
|
||||
|
||||
## Local facts
|
||||
|
||||
- Placement of the siblings: as the `mesh-delivery` map says (`modules/mesh-build-go/cmd/mesh-build-go/workspace.go:17-60`).
|
||||
The TypeScript modules (`gitea`, `nftables`) build with their `package.json`; their tests are not counted by `go test`.
|
||||
|
||||
## Test budget (§819), `go test -list '.*'`, without and with `-tags integration`, top-level functions
|
||||
|
||||
Counted 22:20 to 22:30 CET (unit / integration): gate 30 / 2; Go build module 205 / 15; Node build module 117 / 8; image
|
||||
build module 56 / 6; `distribution` 9 / 1; `artifact-store-tools` 23 / 1; `nats` 38 / 7; `mesh-self-check` 10 / 1;
|
||||
`mesh-vault` 143 / 2; `mesh-recovery` 24 / 1; `nfs-server` 51 / 0; `pacman` 118 / 3; `gitea`'s Go part 176 / 2. §819's
|
||||
"NFS server 51 integration, package manager 121 integration" are the build node's counts, which take untagged tests in
|
||||
(plan section 10: the build node counts untagged tests into a module's integration count); by the tag they hold 0 and 3 (DQ-14).
|
||||
@@ -1,52 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
---
|
||||
# 47 H2 build map: `mesh-contracts`
|
||||
|
||||
Read at `origin/main` `87eab81be134` (2026-11-20 07:12 UTC), from an archive of that commit. Design: hq `35ddd45e`.
|
||||
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
|
||||
|
||||
## What exists today
|
||||
|
||||
Searches as run: `ls seats */seats`; the verbs of `seats/node-engine/seat.json`, `seats/mesh-broker/seat.json`,
|
||||
`identity-and-access/seats/mesh-vault/seat.json` by `python3`; `grep -rn "DisallowUnknownFields" --include='*.go' go`;
|
||||
`grep -rl '"node-packet-filter"'` over every repository (found only in `mesh-sdk`'s test seat list); live: `mesh_search`
|
||||
"node-engine composition" answered `mesh-vault.own` "from the node-engine o…" (22:27 CET).
|
||||
|
||||
1. **What exists today.**
|
||||
- The node-engine seat: 18 verbs, none `converged`, none with `timeout` (`seats/node-engine/seat.json`).
|
||||
- `mesh-broker`: `list`, `show`, `check`, `orphans`, `create`, `apply`, `recreate`, `drop` and the snapshot verbs
|
||||
(`seats/mesh-broker/seat.json`): §783's and §812's reads through `show`, `list`, `apply` exist.
|
||||
- `mesh-vault`: `own` answers the node-engine of one machine about its own machine (the caller as the bus proves it),
|
||||
sealed to the key it stated with `node-key`, read-only; `get` answers one secret sealed to the asker's key to an
|
||||
asker the vault allows; `licence-put` is a two-step sealed write for the licence manager alone; no verb writes a
|
||||
module's own secret from that module (`identity-and-access/seats/mesh-vault/seat.json`, verbs `own`, `get`,
|
||||
`licence-put`, `rotate`, `move-in`).
|
||||
- Every generated decoder here refuses unknown fields (`go/seats/meshmoduleassigner/contract.go` 8 places,
|
||||
`go/seats/nodeengine/contract.go` 9, `go/seats/meshconfig/contract.go` 1, `go/clients/nodeengineclient` 2); no
|
||||
definition carries `form`.
|
||||
- No seat definition of `node-packet-filter` here.
|
||||
2. **What relies on each.** Every module importing a generated contract here (the node-engine, the assigner, the tool
|
||||
runner, the vault, the provisioner) reads with these decoders.
|
||||
3. **Fates.** Regenerated tolerant (§780). New parts: the vault's write verb (§808, H-A-345; DQ-7), `converged` and
|
||||
`timeout` (§781; DMC-12).
|
||||
|
||||
## Rows
|
||||
|
||||
| line | files | subtask | acceptance (cites) | test |
|
||||
|---|---|---|---|---|
|
||||
| §780 | every `seats/*/seat.json` and `*/seats/*/seat.json` (`form`), regenerated `go/`, `ts/` with `mesh-delivery`'s `seatgen` | K1 regenerate tolerant, `form` | §780 unit | unit |
|
||||
| §808 | `identity-and-access/seats/mesh-vault/seat.json`: a write of a module's own secret (H-A-345) | K2 vault write verb (waits DQ-7) | the forge module writes and reads its token through the vault seat (§808) | unit, whole (forge module) |
|
||||
| §781 | `seats/node-engine/seat.json`: `converged` with `timeout` (waits DMC-12) | K3 | §781 | unit |
|
||||
|
||||
## Order and writers
|
||||
|
||||
K1 after `mesh-delivery` G1 (the generator); K2 before `mesh-catalog` C4 and VA1; K3 before `mesh-catalog` P2. One agent.
|
||||
|
||||
## Test budget (§819)
|
||||
|
||||
Not a module H2's count names; its packages' tests are read in the check.
|
||||
@@ -1,191 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
---
|
||||
# 47 H2 build map: `mesh-delivery`
|
||||
|
||||
Read at `origin/main` `7e597a623eb2` (2026-11-21 21:01 UTC), from an archive of that commit (`git archive origin/main`),
|
||||
never a working tree. The design read is hq `35ddd45e` (branch `design/47-H2-part`). Every row cites the design line it
|
||||
builds ("design 47 H2 §n"). Where a line meets code that cannot take it, the row points to the entry under *Design meets
|
||||
code* (DMC-n) or *Design questions* (DQ-n) at the end of
|
||||
[H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md); such a subtask waits for its answer.
|
||||
|
||||
## What exists today
|
||||
|
||||
Searches as run, from the archive's root `mesh-delivery/`:
|
||||
`grep -rn "CallKept\|DoKept\|DoRepeatable" --include='*.go' modules`; `grep -rn "Subscribe(" --include='*.go'
|
||||
modules/mesh-delivery-builder/cmd modules/mesh-delivery-assigner/cmd`; `python3` over every
|
||||
`modules/mesh-delivery-contracts/seats/*/seat.json` listing verbs, accepts and events; `grep -rn "DisallowUnknownFields"
|
||||
--include='*.go' modules`; each tool of the H2 tools table searched by its quoted name in every `module.json` and Go
|
||||
file; live: `nats.nats_streams` with `stream` `SEAT_MESH_BUILDS` and `SEAT_MESH_WANTS` (answered by novox, 22:25 CET).
|
||||
|
||||
1. **What exists today.**
|
||||
- The kept call is built in mesh-sdk (`CallKept`, `busretry.DoRepeatable`, `DoKept`) and used by the runner
|
||||
(`cmd/mesh-delivery-pipeline/drop.go`, `main.go`, `verbs.go`), the assigner (`main.go`, `puts.go`, `askended.go`,
|
||||
`compositionrun.go`), the builder (`buildrun/asks.go:183`, `cmd/.../reads.go`), the bridge (`moves.go`, `bound.go`).
|
||||
The runner puts step asks by a JetStream publish with the ask id as message id
|
||||
(`modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/asks.go:27-42`), one try.
|
||||
- Seats `mesh-builds` and `mesh-wants` each accept one kind, `step` (`seats/mesh-builds/seat.json` `accepts`,
|
||||
`seats/mesh-wants/seat.json` `accepts`); neither declares `ask-taken` nor `version-reserved`. The grants part derives
|
||||
their work-queue streams `SEAT_MESH_BUILDS` and `SEAT_MESH_WANTS` with a shared worker, ack wait 60 s, max deliver 5,
|
||||
max age 7 days (`modules/mesh-grants/internal/buscompose/derived.go:86-110`, `:343-358`). The builder hears asks by a
|
||||
plain subscription (`modules/mesh-delivery-builder/cmd/mesh-delivery-builder/step.go:78`), the assigner likewise
|
||||
(`modules/mesh-delivery-assigner/cmd/mesh-delivery-assigner/compositionstep.go:257`). Live: `SEAT_MESH_BUILDS` holds
|
||||
1,558 messages, `SEAT_MESH_WANTS` 1,598, each with 0 consumers, max age 168 hours.
|
||||
- The runner treats `mesh-builds` and `mesh-wants` as silent seats with `ask-silent-bound` (45 min) and the build seats
|
||||
as seats that say `ask-taken`, with a second put under `AgainID` and a second bound key `ask2.`
|
||||
(`modules/mesh-delivery-pipeline/internal/pipeline/asks.go:17-160`, `cmd/.../askbounds.go:20-35`).
|
||||
- The runner's step record has no `asked-at` or `taken-at`; `pipeline-ended` has no `phases` or `unfinished`
|
||||
(`seats/mesh-pipeline-runner/seat.json`). Its stalled bound is the constant `StalledAfter` 5 minutes
|
||||
(`internal/pipeline/consumers.go:26`). It keeps step outputs in objects `step-outputs` (`internal/pipeline/steps.go:138`,
|
||||
`cmd/.../steps.go:100`; manifest `objects` `step-outputs` 1,024 MiB). Its tools: 14 (`module.json`), with
|
||||
`runner_health`; no `runner_show`, `runner_movers`, `runner_cancel`, `runner_step_output` or `runner_unfinished*`.
|
||||
- Delivery modules ask for their stores in the manifest's old sections (`state`, `streams`, `objects`): the runner's
|
||||
findings stream `mesh-delivery-pipeline-findings` 16 MiB 7 days (`module.json:222-232`), the builder's likewise
|
||||
(`module.json:140`); the bridge asks for `performed` in `requires` by the state template, TTL 604,800 s
|
||||
(`modules/mesh-delivery-forge-bridge/module.json:40-45`).
|
||||
- Generated seat decoders refuse unknown fields (`DisallowUnknownFields` in every `go/seats/*/contract.go`); no seat
|
||||
definition carries `form` (each has the file's `format: 1`). The seat generator is `modules/mesh-delivery-sdk/seatgen`
|
||||
(`gogen.go`, `tsgen.go`), not in mesh-sdk.
|
||||
- Two copies of the contracts and the delivery SDK stand: `contracts/` and `sdk/` at the repository's root (used only by
|
||||
each other) and `modules/mesh-delivery-contracts`, `modules/mesh-delivery-sdk` (used by every module).
|
||||
- The build-step part (`modules/mesh-delivery-contracts/parts/build-step.json`) already has the verbs `current`
|
||||
(answer: the steps running, capacity, paused), `output` (a chunked whole answer by `ask` and `call`), `drop`, and the
|
||||
event `ask-taken` on `ask-taken.<node>`.
|
||||
- The builder's tag form is `go/v<version>` (`modules/mesh-delivery-builder/internal/versions/tag.go:4`,
|
||||
`reserve.go:264`); its floor reads tags by `TagPrefix` (`claim.go:50-56`). Its unbuildable plans are said per module
|
||||
(`buildrun/buildseats.go:114`). Its publish items are a state bucket (`cmd/mesh-delivery-builder/publishitem.go:44-110`),
|
||||
read with `builder_publish_queue` (exists). Its published mark keeps `published-at` and kept releases keep `digest`
|
||||
(`internal/versions/reserve.go:57-59`, `:95-98`, `:102-106`, `:460-463`): §798 is built on main.
|
||||
- The fingerprint is computed in the indexer alone (`modules/mesh-delivery-indexer/internal/fingerprint/fingerprint.go:1-5`,
|
||||
`Of`), over the directory's tree or the named paths (`internal/index/inputs.go:97-118`); a repository's commit enters
|
||||
through unpublished packages and the import form's versions (`internal/index/form.go:27-50`, `:113-125`).
|
||||
- The indexer's dry run is a copy of its states kept in memory that still writes manifests and packages to the bus
|
||||
(`internal/index/dryrun.go:12-40`). The validate step and `causedProblems` are the assigner's
|
||||
(`cmd/mesh-delivery-assigner/validatestep.go:124`, `:203-230`), counting every problem of a touched module. The seat
|
||||
`mesh-catalog` has `seat-definitions`, no `seat-list`; a registration is keyed `<module>` and requires `module`,
|
||||
`origin`, `path`, `branches`, `policy` (`seats/mesh-catalog/seat.json` `defs.Registration`).
|
||||
- The teller keeps a wait for room and its tests (`modules/mesh-delivery-teller/cmd/mesh-delivery-teller/ends.go:16-68`,
|
||||
`room_test.go`).
|
||||
2. **What the change touches, replaces or removes, and what relies on each.**
|
||||
- Plain subscriptions on `mesh.seat.mesh-builds.accept.step` and `mesh.seat.mesh-wants.accept.step`: written by the
|
||||
runner (`asks.go:27`), heard by the builder (`step.go:78`) and the assigner (`compositionstep.go:257`); nothing else
|
||||
subscribes (search above).
|
||||
- `ask-silent-bound`, `SilentWhy`, `AgainID`, `ask2.` keys: written and read only in the runner
|
||||
(`internal/pipeline/asks.go`, `bounds.go`, `cmd/.../askbounds.go`, `main.go:172`); the setting's file
|
||||
`MESH_RUNNER_ASK_SILENT_BOUND_FILE` is named in the runner's manifest.
|
||||
- Objects `step-outputs`: written by the runner's hearer (`internal/pipeline/steps.go:305`), read by `read.go:25-42`.
|
||||
- The builder's publish-items bucket: written by `publishitem.go:96`, read by `republish.go` and the tools bundle
|
||||
(`cmd/mesh-delivery-builder-tools/republish.go:37`).
|
||||
- The runner's drop of `kept-revisions` before the seat decode (`internal/pipeline/steps.go:203-207`, `verbs.go:609`,
|
||||
`moverkeys.go:294-300`).
|
||||
- The tag form `go/v<version>`: read by the builder's floor (`claim.go:213`) and by Go's toolchain at fetch.
|
||||
- The teller's room wait: written and read in the teller only (`ends.go`, `assignerasks.go:20-24`).
|
||||
3. **What happens to each, and the test.** Plain subscriptions go (design 47 H2 §777; proven by the whole-module tests of
|
||||
§777). `ask-silent-bound` and its key go (§777); `AgainID` and `ask2.`: no line gives their fate on the build seats
|
||||
(DQ-4). `step-outputs` goes, dropped through the bus module (§791; the search for its name finds no reader). The
|
||||
publish-items bucket goes after one move (§793). The `kept-revisions` drop goes (§780). `go/v` tags go from new
|
||||
versions (§796). The room wait goes (§813 (10); the teller's suite holds no such test). New exported parts and their
|
||||
placing lines: `ask-taken` and `version-reserved` events (§777, §805, §821), `phases` and `unfinished` (§785, §786),
|
||||
`asked-at`, `taken-at` (§778), states `unfinished` (§786, §820), `taken` (§775, §820), `dry-runs` (§804, §820), work
|
||||
queue `publishes` (§793, §820), verb `seat-list` (§814), the source-only registration (§815; its key is DQ-9).
|
||||
|
||||
## Rows: each design line, where it lands, its subtask
|
||||
|
||||
Labels: `D` contracts (`modules/mesh-delivery-contracts`, regenerated by `seatgen`), `G` the generator
|
||||
(`modules/mesh-delivery-sdk`), `R` the runner, `B` the builder, `I` the indexer, `A` the assigner, `F` the bridge, `T` the
|
||||
teller, `V` the view. Each acceptance cites its design line's *How it is checked*.
|
||||
|
||||
| line | files and functions | subtask | acceptance (cites) | test |
|
||||
|---|---|---|---|---|
|
||||
| §780 | `modules/mesh-delivery-sdk/seatgen/gogen.go`, `tsgen.go`, `load.go` (decoders, `form`, the generator's check) | G1 tolerant decoders and `form` (waits DMC-4) | a value, event, answer with an unknown field decode and return their form; absent `form` reads 1; a definition whose fields changed with `form` unchanged fails (§780) | unit, `seatgen` |
|
||||
| §780 | every `go/seats/*/contract.go`, `ts/` (regenerated) | D0 regenerate all seats from G1 | the generated decoders keep unknown fields (§780) | unit, `mesh-delivery-contracts` |
|
||||
| §777, §821, §805 | `seats/mesh-builds/seat.json`, `seats/mesh-wants/seat.json`: accepted kinds as work queues with their settings, `ask-taken` (`<seat>.ask-taken.<ask>`: `ask`, `node`, `at`), `version-reserved` (`module`, `artifact`, `path`, `version`, `fingerprint`, `revision`) | D1 queues and events of the two seats (waits DQ-1, DQ-2, DMC-1) | the seat list carries each family and name (§821) | unit, `mesh-delivery-contracts` fixtures |
|
||||
| §778, §785, §786, §789, §821 | `seats/mesh-pipeline-runner/seat.json`: step `asked-at`, `taken-at`; `pipeline-ended` `phases`, `unfinished`; `show` filters `mover`, `step`, `state`, answer `capped`, `total`, `next`; the re-pin's event (DQ-13) | D2 runner seat | `pipeline-ended` of two movers carries each step kind's span (§785) | unit, fixtures |
|
||||
| §791, §800, §801 | `parts/build-step.json` (`output` input `ask`, answer last 64 KB, size, failing tests, "no longer kept"; `current` per holder takes or why not, every ask; summary `not-run`), `seats/node-build-node/seat.json` (accepted kind `install`) | D3 build-step part (waits DMC-6, DMC-16) | per §791, §800, §801 checks | unit, fixtures |
|
||||
| §806, §814, §815 | `seats/mesh-catalog/seat.json`: `registrations` filters `module`, `repository`, `capped`, cursor; verb `seat-list` (`digest`, `size`, `object`); the source-only registration (`repository`, `branch`, `policy`, `check`) | D4 catalog seat (waits DQ-9) | §806 unit; §815 whole | unit, fixtures |
|
||||
| §776, §796 | `seats/git/seat.json`: `tags` answer `commit` per tag, the listing's description of `not-found`, `ErrorKind` gains `away` | D5 git seat (waits DMC-2, DMC-3) | §796 whole (builder) | unit, fixtures |
|
||||
| §811 | `seats/mesh-delivery/seat.json`: `deliveries` filters `repository`, `module`, `outcome`, `since`, answer `capped`, `total`, cursor | D6 delivery seat | `deliveries` by repository over 4 MB answers under 768 KB (§811) | unit (gate) |
|
||||
| §775 | `modules/mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/asks.go` `busStepAsker.AskStep`, every seat call of the runner | R1 asks as kept calls with the pace and `ask-unanswered-bound` | a composition ask whose holder is away 40 s passes its step with no hand act (§775) | whole, runner |
|
||||
| §777, §778 | `internal/pipeline/asks.go` (`Silent`, `AskClock`, `AskUnanswered`), `bounds.go`, `cmd/.../askbounds.go`, `consumers.go` (hear `ask-taken` of both seats), the step record | R2 bound from the pull, untaken bound, drop at the bound, put again only on a transport fault (waits DMC-15, DQ-4) | ask taken 9 min before a restart with a 10 min bound ends 1 min after start and is dropped; untaken for `stalled-bound` named by health; untaken for the whole bound ends could-not-run naming the holder; a put refused for a full stream is said and asked again (§777, §778) | unit, runner |
|
||||
| §784 | `internal/pipeline/steps.go` (the one place saying `step-ended`), the place an ask is put | R3 journal lines | each way a step ends writes that line once (§784) | unit |
|
||||
| §785 | `internal/pipeline/steps.go` `endPipeline` (`:731`) | R4 phases | two movers end with each kind's span (§785) | unit |
|
||||
| §786 | new state `unfinished`; `endPipeline`; the take-in consumer; tools bundle `runner_unfinished`, `_drop`, `_place` | R5 movers put in a pipeline again | of two movers one fails unit; `pipeline-ended` names the other; the next take-in's pipeline carries it; it is wanted (§786) | whole, runner |
|
||||
| §787, §780 fate | `internal/pipeline/steps.go:203-207`, `verbs.go:609`, `moverkeys.go:294-300` | R6 `kept-revision-unread`, drop of `kept-revisions` goes | unit (§787) | unit |
|
||||
| §788 | `internal/pipeline/registration_missing.go`, the registrations view, `runner_health` | R7 registrations read first | a start with the view unread raises none, answers `registrations-read` false, places once read (§788) | unit |
|
||||
| §789 | `internal/pipeline/read.go` `Show`, the `show` verb, new tools `runner_show`, `runner_movers` | R8 a pipeline in parts (waits DMC-8) | one mover of 129 under 64 KB; `runner_movers` of 1,000 under 768 KB (§789) | unit |
|
||||
| §790 | `internal/pipeline/consumers.go:26` `StalledAfter` to the setting `stalled-bound`; process and tools program read it | R9 stalled bound a setting (uses mesh-sdk S6) | at one minute, health names such a pipeline after one minute, not once a step is placed (§790) | whole |
|
||||
| §791 | new tool `runner_step_output`; `step-outputs` dropped (`internal/pipeline/steps.go:138`, `:305`, `read.go`) | R10 step output where kept | a failing unit test's words read through `runner_step_output`; past max-age "no longer kept" (§791) | whole (Go build module) |
|
||||
| §815 | the run on request of a source-only registration's head as one step (`cmd/.../testruns.go`, `internal/pipeline` run path) | R11 a source-only check | a source-only pull request is run on request (§815) | whole (indexer, runner, gate) |
|
||||
| §783, §820 | `modules/mesh-delivery-pipeline/module.json` (findings stream 8 MiB, `findings-max-age`; `unfinished`; `taken`; setting `stalled-bound`; drop `step-outputs` and `ask-silent-bound`) | R12 runner's manifest (waits DQ-5) | 10,000 findings past the cap refuse none (§783) | whole |
|
||||
| §775, §777 | `cmd/mesh-delivery-builder/step.go` `serveSteps` (pull the worker, in-progress, ack at the end, `ask-taken`, `taken`); `buildrun/asks.go` publish asks to registries as kept calls | B1 pull and take once | a build ask put while the builder is stopped is taken and ended after its start (§777) | whole, builder |
|
||||
| §777 | new tools `builder_asks`, `builder_ask_drop` | B2 queue tools | per tools table | unit |
|
||||
| §792 | `step.go` (the build step's finish) | B3 answered line | unit (§792) | unit |
|
||||
| §793 | `cmd/mesh-delivery-builder/publishitem.go`, `internal/versions/republish.go`, tools `builder_publish_queue` (exists), `builder_publish_drop`, `builder_publish_first`; the one move of the bucket | B4 publishes work queue (waits DQ-6) | a live publish behind 100 `again` is sent first; a dropped item never sent; a move run twice puts each once (§793) | whole |
|
||||
| §794 | `internal/versions/heard.go` (handling of `published`, `package-published`), health | B5 one read and one write | 1,000 events over 2,000 reservations: one read and one write each; a backlog held six minutes named (§794) | unit, whole |
|
||||
| §795 | `buildrun/buildseats.go:114`, new tool `builder_unbuildable` | B6 one summary line | 6,500 unbuildable plans write one line (§795) | unit |
|
||||
| §796 | `internal/versions/claim.go`, `reserve.go:264`, `tag.go` | B7 tags read before reserve, `version-tagged-elsewhere`, tag `<directory>/v<version>` | a tag at another commit makes the next number and the finding, cleared at the next release (§796) | whole |
|
||||
| §797 | `modules/mesh-delivery-sdk/buildrecord` and the builder's writer | B8 build record end | unit (§797) | unit |
|
||||
| §798 | `internal/versions/reserve.go:57-106`, `:452-466` | none: built on main | a publish heard now answers its time (§798): read the existing test | unit (exists) |
|
||||
| §799 | the builder's reading of a step's why (`buildrun/heardends.go`, `faults.go`) | B9 `fetch:` and `publish:` said apart | per §799 | unit |
|
||||
| §801 | new tool `build_current` (asks every holder's `current`) | B10 build current | an ask the builder put is listed by `current` while it runs (§801) | whole (Go build module) |
|
||||
| §805 | `internal/versions/reserve.go` (say `version-reserved` at the reservation) | B11 version-reserved | §805 whole (indexer) | whole |
|
||||
| §802 | the builder's read of the fingerprint (`internal/build/run.go`) | B12 builder takes the new fingerprint (waits DMC-5) | §802 whole (indexer) | whole |
|
||||
| §783, §820 | `modules/mesh-delivery-builder/module.json` (findings, `publishes`, `taken`) | B13 builder's manifest (waits DQ-5) | §783 | whole |
|
||||
| §802 | `internal/fingerprint/fingerprint.go` `Of`, `internal/index/form.go` `formOf`, `lineVersions` | I1 fingerprint over the module's own build source (waits DMC-5, DQ-8) | a commit touching two test files of two modules of 36 moves those two and their importers alone (§802) | whole, indexer |
|
||||
| §803 | the take-in's waits on the seat `git`, versions, a registry; value of `takeins` (`waiting-on`); finding `take-in-waiting` | I2 take-in says what it waits on | 70 s writes one line and `waiting-on`; six minutes raises the finding, cleared at the answer (§803) | unit |
|
||||
| §804 | `internal/index/dryrun.go`, `runcandidates.go:213`; state `dry-runs`; tool `indexer_dry_runs` | I3 dry run's own state | trunk packages byte for byte as before; a start finds `dry-runs` empty (§804) | whole |
|
||||
| §805 | the re-pin path (`internal/index` pins, the consumer of `package-published`), consume `version-reserved` | I4 re-pin once at the reservation | a release importing twenty packages of its pipeline keeps one re-pin revision (§805) | whole |
|
||||
| §806 | the `registrations` verb, new tool `indexer_registrations` | I5 registrations in one call | unit (§806) | unit |
|
||||
| §814 | verb `seat-list` (one object in the indexer's objects by digest), `cmd/mesh-judge` reads it by address, `judge/rules.go` refuses an uncapped store of a delivery module, tool `indexer_validate_before` | I6 seat list and the uncapped refusal (waits DMC-9, DQ-10) | a run by hand against `seat-list` gives the live validate's verdicts for the builder's and the runner's manifests; an uncapped entry refused, a foundation part's capped old-section entry not (§814) | whole, unit |
|
||||
| §815 | registrations state and `register`; take-in of a source-only branch with no movers; refusal when the repository holds a manifest | I7 source-only registration (waits DQ-9) | §815 whole | whole |
|
||||
| §818 | `indexer_recompute` (exists) | none: a run, not code | the lead reads `runner_movers` (§818) | live |
|
||||
| §775 | `cmd/mesh-delivery-assigner/compositioninputs.go:24`, `:109` (`compose-candidate` as kept call, `compose-ask-bound`) | A1 compose-candidate kept | §775 whole (runner) | whole |
|
||||
| §777 | `compositionstep.go:257` (pull), new tools `assigner_asks`, `assigner_ask_drop` | A2 pull validate and compose (waits DQ-1) | a validate ask put while the assigner is stopped is taken after its start; after a pipeline's end both consumers hold 0 pending (§777) | whole, assigner |
|
||||
| §792 | `compositionstep.go`, `validatestep.go` | A3 answered line | unit | unit |
|
||||
| §813 (1) | the composition writer (`compositionrun.go`, `puts.go`): `run`, compare-and-set refusing a lower `run` | A4 one writer per composition key (waits DQ-12) | unit (§813 (1)) | unit |
|
||||
| §813 (2) | the keeping of assignment graph revisions (`revisions.go`, `graphkept.go`), setting `keeping-retry`, finding `keeping-failed`, tool `assigner_keep_now` | A5 failed keeping runs again | unit (§813 (2)) | unit |
|
||||
| §814 | `validatestep.go:203-230` `causedProblems` (drop the touched clause) | A6 only new problems (waits DMC-9) | a problem the before case holds is not counted (§814) | unit |
|
||||
| §807 | `cmd/mesh-delivery-forge-bridge/acts.go`, `call.go`, `bound.go` (`owed-away-bound`), `cmd/mesh-delivery-forge-bridge-tools/owed.go` (`bridge_owed_again` `record`, preconditions again) | F1 owed through a part away | forge away 60 s: a note act is performed after, no hand act; a closed pull request's act is ended (§807) | whole, bridge |
|
||||
| §811, §812 | `bridge_owed` by pull request in the process; `performed` prune and `performed-keep` | F2 performed capped | a write past 70 % prunes to 50 %; a key under `state_keep` survives (§812) | whole, bridge |
|
||||
| §813 (10) | `modules/mesh-delivery-teller/cmd/mesh-delivery-teller/ends.go`, `assignerasks.go`, `room_test.go` | T1 room wait goes | the teller's suite holds no such test (§813 (10)) | unit |
|
||||
| §813 (9) | `modules/mesh-delivery-view` usage reading | V1 usage by `current` | unit (view) | unit |
|
||||
|
||||
## Order and writers
|
||||
|
||||
- **Order.** G1, then D0 (regenerate), then D1 to D6 (one contracts agent, one commit each). mesh-sdk's S1, S2, S3, S6,
|
||||
S8, S11 (the mesh-sdk map) come before every user. Then R, B, I, A, F, T, V start from D's last commit. Within the
|
||||
runner, R1 before R2; R2 before R3, R5, R8. Within the builder, B1 before B2, B4; B11 before I4. I1 and B12 land in one
|
||||
commit pair read together (§802: one release). Merge order of the group: contracts and generator, then the indexer
|
||||
and the builder (§802), the assigner after the node-engine's tolerant reading (§813 (1)'s edge, the node-engine's map),
|
||||
then the runner, bridge, teller and view.
|
||||
- **Ordering edges.** §813 (1): the node-engine that reads `run` tolerantly runs before the assigner writes it (an edge
|
||||
of the module graph). §818: once the indexer and builder of §802 run, the recompute moves every module once, before
|
||||
the proofs. §777's stream rebuild through `nats_recreate` runs before the new builder and assigner start (a live act on
|
||||
the operator's warrant, not code).
|
||||
- **One writer per file.** One agent per module directory: the contracts agent writes `modules/mesh-delivery-contracts`
|
||||
and `modules/mesh-delivery-sdk/seatgen`; the runner agent `modules/mesh-delivery-pipeline`; the builder agent
|
||||
`modules/mesh-delivery-builder` and `modules/mesh-delivery-sdk/buildrecord`; the indexer agent
|
||||
`modules/mesh-delivery-indexer`; the assigner agent `modules/mesh-delivery-assigner`; one leaf agent the bridge, the
|
||||
teller and the view. `modules/mesh-delivery-sdk/steprun/conformance` is the build modules' agent's (mesh-catalog map).
|
||||
- **Not to touch.** `contracts/` and `sdk/` at the repository's root (no line names them).
|
||||
|
||||
## Local facts
|
||||
|
||||
- Worktree per playbook 07 item 2 under `.work/<slug>/mesh-delivery`, branch `feat/<slug>`; `TMPDIR` under the worktree.
|
||||
- **Placement of the siblings**, as the Go build module places them (`mesh-catalog`
|
||||
`modules/mesh-build-go/cmd/mesh-build-go/workspace.go:17-60`): a `go.work` that `use`s the module and, transitively,
|
||||
every module it requires at the zero version `v0.0.0-00010101000000-000000000000`, each found by module path among the
|
||||
sibling clones (`mesh-sdk`, `mesh-contracts`, `mesh-delivery`, `mesh-catalog`, `mesh-tools`, `mesh-host`,
|
||||
`mesh-networking`), with `replace <path> v0.0.0-00010101000000-000000000000 => <dir>` for each. No agent writes another.
|
||||
- Unit suite: `GOWORK=<that go.work> go test ./...` per module; integration compiled: `go vet -tags integration ./...`.
|
||||
|
||||
## Test budget (§819), by `go test -list '.*'` without and with `-tags integration`, top-level functions
|
||||
|
||||
Counted at this commit, 22:20 to 22:30 CET (unit / integration): runner 105 / 4; builder 167 / 18; indexer 167 / 6;
|
||||
assigner 86 / 9; bridge 10 / 2; teller 50 / 5; view 84 / 8; `mesh-delivery-sdk` 149 / 12; `mesh-delivery-contracts` 47 / 0.
|
||||
§819 names the indexer 170 / 6 and the assigner 87 / 9: the counts differ by 3 and 1 (DQ-14). Each module H2 changes ends
|
||||
below its start.
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
---
|
||||
# 47 H2 build map: `mesh-host` (the node-engine)
|
||||
|
||||
Read at `origin/main` `637cfb1fd044` (2026-11-21 20:48 UTC), from an archive of that commit. Design: hq `35ddd45e`.
|
||||
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
|
||||
|
||||
## What exists today
|
||||
|
||||
Searches as run, from `mesh-host/`: `grep -rn "TOOL_ENV\|RuntimeToolEnv" --include='*.go' internal`;
|
||||
`grep -rn "compose-candidate\|ComposeCandidate" --include='*.go' internal`; `grep -rn "comment" --include='*.go'
|
||||
internal/firewall`; `grep -rln "engine_" --include='*.go' .`; `grep -rln "node-tools\|tool runner" --include='*.go'
|
||||
internal`; the node-engine seat's verbs from `mesh-contracts` `seats/node-engine/seat.json`; live: `mesh_search`
|
||||
"node-engine composition" (22:27 CET).
|
||||
|
||||
1. **What exists today.**
|
||||
- The node-engine composes `MESH_TOOL_ENV`, each module's words by module, into the tool runner's process
|
||||
(`internal/compositions/composed.go:296-336`, `internal/compose/composed.go:369-410`, `:476`); a module's settings
|
||||
reach its own process as files the manifest names (`${config:<key>}`), and whether they reach its tools bundle's
|
||||
words is not said in the code read (DMC-13).
|
||||
- The verb `compose-candidate` answers within `candidateWithin` (`internal/selfcompose/candidate.go:44-49`,
|
||||
`:101-104`); it takes no ask id and keeps no `taken`.
|
||||
- The node-engine renders each opening as a ufw rule with the comment `Mark`: `mesh-host <id> <digest>`
|
||||
(`internal/firewall/firewall.go:415-427`, `:782`), and recognises its own rules by that mark (`markedFor`, `:426`).
|
||||
- The node-engine has no tools of its own: it serves the seat `node-engine`'s verbs (live: `ace/node-engine.composition`,
|
||||
`.compose`, `.packages`, `.compose-candidate`, each also on g14, novox, shanks); no `engine_composition_diff`.
|
||||
- The node-engine seat has no verb `converged` and no verb carries `timeout` (`mesh-contracts`
|
||||
`seats/node-engine/seat.json`, 18 verbs, each `timeout` absent).
|
||||
- The composition's value carries `run` as a string (`mesh-contracts` `go/seats/nodeengine/contract.go:1764`); the
|
||||
generated decoders refuse unknown fields (9 places in that file).
|
||||
- The tool runner is placed as a unit of the node-engine's composition (`internal/compose/input_held.go`,
|
||||
`internal/link/engineseat.go`); no drain wait before the new one starts was found.
|
||||
2. **What relies on each.** The mark `mesh-host <id> <digest>`: read by the node-engine's own reconciling
|
||||
(`firewall.go:426`, `:452`, `:536-616`) and by the packet filter's holder reading `rules` (`mesh-catalog`
|
||||
`modules/nftables/client.ts`). `MESH_TOOL_ENV`: read by the tool runner (`mesh-tools` `internal/launch`).
|
||||
`compose-candidate`: asked by the assigner (`mesh-delivery` `compositioninputs.go:109`).
|
||||
3. **Fates.** The mark's form against §813 (4)'s comment is DQ-11. New parts: `run` as the composition run's sequence
|
||||
(§813 (1)), the setting `drain-bound` read by the node-engine (§813 (12)), the tool `engine_composition_diff` (§813 (3);
|
||||
its place is DQ-12b).
|
||||
|
||||
## Rows
|
||||
|
||||
| line | files and functions | subtask | acceptance (cites) | test |
|
||||
|---|---|---|---|---|
|
||||
| §780 | the node-engine's readers of another part's values (`internal/link`, the generated `nodeengine` contract from `mesh-contracts`) | E1 tolerant reading | §780 unit (mesh-sdk) | unit |
|
||||
| §775 | `internal/selfcompose/candidate.go` `ComposeCandidate`: take an ask once by its id (`taken`) | E2 compose-candidate once | a holder given the same ask id twice acts once (§775) | unit |
|
||||
| §781 | `internal/compositions/composed.go:296-336`: a module's settings into its slice of `MESH_TOOL_ENV` | E3 settings to the tools program (waits DMC-13) | §781 unit (mesh-sdk) | unit |
|
||||
| §813 (1) | the apply of a composition (`internal/apply`, `internal/compositions`): apply again only when a readable part differs and `run` is newer; journal names the run | E4 only a newer run (waits DQ-12) | unit (§813 (1)) | unit |
|
||||
| §813 (3) | a composition diff by resource, environment by name, secrets masked | E5 composition diff (waits DQ-12b) | unit (§813 (3)) | unit |
|
||||
| §813 (4) | `internal/firewall/firewall.go` `Mark`, `:782`: comment `derived <module> <listen> scope <any\|private-network\|local-network>` | E6 derived rule's scope (waits DQ-11) | unit (node-engine render) (§813 (4)) | unit |
|
||||
| §813 (12) | the replacement of the tool runner's unit: wait `drain-bound` for the old to exit | E7 drain wait | the new tool runner starts only after the old exits or the bound passes (§813 (12)) | unit |
|
||||
| §819 | the node-engine's tests | E8 shrink | the check's counts against the start | check |
|
||||
|
||||
## Order and writers
|
||||
|
||||
- E1 first (the edge of §813 (1): the node-engine reading `run` tolerantly runs before the assigner writes it); then E2 to
|
||||
E7. E6 before `mesh-catalog` P1. One agent writes this repository.
|
||||
|
||||
## Local facts
|
||||
|
||||
- Placement as the `mesh-delivery` map says; `mesh-networking` is among the siblings.
|
||||
|
||||
## Test budget (§819)
|
||||
|
||||
1,715 unit and 11 integration top-level tests by `go test -list` (22:30 CET); §819 names 1,716 and 11 (DQ-14). Over the
|
||||
budget of 500 unit: H2's change ends below 1,715.
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
---
|
||||
# 47 H2 build map: `mesh-sdk`
|
||||
|
||||
Read at `origin/main` `bdc5cff0d63d` (2026-11-21 15:51 UTC), from an archive of that commit. Design: hq `35ddd45e`.
|
||||
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
|
||||
|
||||
## What exists today
|
||||
|
||||
Searches as run, from `mesh-sdk/go/`: `grep -n -i "kept" process/call.go`; `sed -n 1,60p busretry/busretry.go`;
|
||||
`grep -rn "\"refused\"\|ErrorKind" --include='*.go' .`; `grep -rn "func .*Setting" --include='*.go' .`;
|
||||
`grep -rn "func .*Fingerprint" --include='*.go' .`; `grep -n "Fill\|StateFilled" buscalls/buscalls.go`;
|
||||
`grep -rln "findings" --include='*.go' views`; `grep -rn "func (s KeptState)" state.go`.
|
||||
|
||||
1. **What exists today.**
|
||||
- The kept call: `Conn.CallKept`, `CallKeptOn`, `CallKeptWhileOpen` (`process/call.go:54-104`) over
|
||||
`busretry.DoRepeatable` and `DoKept` (`busretry/busretry.go:81`, `:116`), with process-wide `Bound` 30 s,
|
||||
`FirstWait` 250 ms, `MostWait` 4 s (`busretry.go:29-33`), no jitter, no ask id, no per-caller bound, no journal line
|
||||
per seat. No `taken` helper.
|
||||
- No seat error answer in mesh-sdk: error kinds are each seat definition's own (`git`'s `ErrorKind`: `refused`,
|
||||
`not-found`, `failed`, in `mesh-delivery`'s contracts).
|
||||
- The bundle's state page: `KeptState.Page(after, maxBytes, budget)` (`state.go:120`), served by the tool runner's
|
||||
`mesh/state.page` in key order after a key (the mesh-tools map).
|
||||
- No settings reader: each module reads `${config:<key>}` files its manifest names (for example the runner's
|
||||
`askbounds.go:20-35` in `mesh-delivery`); the tool runner hands each bundle its module's words from
|
||||
`MESH_TOOL_ENV` (`catalogue/runtime.go:39-43`).
|
||||
- The findings writer keeps the state `findings` and says three events (`views/writer.go:23-125`); its history stream
|
||||
is each module's manifest entry, not the writer's.
|
||||
- A state write answers its revision only (`state.go:177`, `:190`); `buscalls.Fill` and `StreamFilled` exist for a
|
||||
`fill` call (`buscalls/buscalls.go:87-92`, `:255-260`), not in a write's answer.
|
||||
- The seat list's bootstrap copy of `git` is `seatlist/bootstrap/git.json`, with its test copy
|
||||
`seatlist/seatlisttest/seats/git.json`.
|
||||
- No fingerprint function: the indexer holds the one (`mesh-delivery`
|
||||
`modules/mesh-delivery-indexer/internal/fingerprint/fingerprint.go:1-5`, "left mesh-sdk").
|
||||
- The seat generator is not here (`mesh-delivery` `modules/mesh-delivery-sdk/seatgen`).
|
||||
- The test bus is `testbus` (`testbus/testbus.go:36`, `:58`); no setup bound from the environment.
|
||||
2. **What relies on each.** Every caller of `CallKept*` (the `mesh-delivery` map lists them; also `mesh-host`
|
||||
`internal/link/engineseat.go`, `mesh-tools` `cmd/node-tools/approvals.go`, `mesh-catalog` `modules/restic`,
|
||||
`modules/mesh-recovery`); every test that sets `busretry.Waits` (`busretry.go:35-45`); every user of `KeptState.Page`
|
||||
(`views/views.go`, `views/tools.go`, the assigner's `store_pages.go`, the builder's tools' `republish.go`).
|
||||
3. **Fates.** Each stays and gains what its line names; no line removes a part here. New parts and their lines: the pace
|
||||
settings `kept-call-pace-first`, `kept-call-pace-max` (§775), the state `taken` (§775, §820), the kind `away` (§776),
|
||||
the cursor `next` and `seen-again` (§779), the settings reader in a bundle (§781), `state_prune_now`, `state_keep`
|
||||
(§812), the catalog's `check-needs` (§800; DMC-6), `MESH_TOOL_ENV`'s settings (§781).
|
||||
|
||||
## Rows
|
||||
|
||||
| line | files and functions | subtask | acceptance (cites) | test |
|
||||
|---|---|---|---|---|
|
||||
| §775 | `busretry/busretry.go` (pace from settings, jitter 20 %, the caller's bound), `process/call.go` (ask id carried), journal line per seat at first fault then at most once a minute | S1 kept call paced | no responders twice then answered returns the answer and logs one line; past its bound returns every try; a refusal returns at once (§775) | unit |
|
||||
| §775, §820 | a helper keeping the ids an owner took, state `taken`, key `<seat>.<ask>`, TTL the ask's bound | S2 take once | a holder given the same ask id twice acts once (§775) | unit |
|
||||
| §776 | the seat error answer kind `away` with `part`, `words` (waits DMC-2) | S3 `away` | callers read `away` as a transport fault (§776) | unit |
|
||||
| §779 | `state.go` `KeptState.Page`, `stdio.go` (`next` opaque, `seen-again`) | S4 page by cursor (with mesh-tools T1) | §779 whole (tool runner) | whole |
|
||||
| §781 | a settings reader for a process and a bundle (waits DMC-13) | S6 settings in a bundle | a tools bundle reads a setting the manifest sets (§781) | unit |
|
||||
| §782 | the wrappers around one bus handle (waits DQ-3) | S7 safe for concurrent use | concurrent gets, puts and watches through one wrapper under the race detector (§782) | unit, `-race` |
|
||||
| §783 | `views/writer.go` (the writer's `requires`: events template, 8 MiB, `findings-max-age`) | S8 findings history drops its oldest (waits DQ-5) | §783 whole (runner) | whole |
|
||||
| §800 | `testbus` and the test helpers: setup bound half of `MESH_TEST_LEVEL_BOUND`; `catalogue` field `check-needs` | S9 setup bound; S10 `check-needs` (waits DMC-6) | a starved setup runs again (§800) | unit |
|
||||
| §812 | a prune helper judging the fill from the write's answer at `prune-mark` to `prune-target`, the generic tools `state_prune_now`, `state_keep` written in the hand-act log (waits DMC-14) | S11 prune helper and tools | a write past 70 % prunes to 50 %; a kept key survives (§812) | unit, whole (bridge) |
|
||||
| §814 | `catalogue`: what the manifest validator needs to refuse an uncapped delivery store | S12 caps in the catalog | §814 unit (validator) | unit |
|
||||
| §796 | `seatlist/bootstrap/git.json`, `seatlist/seatlisttest/seats/git.json` | S13 bootstrap copy of `git` (uses `mesh-delivery` D5) | the copy equals the contract | unit |
|
||||
| §802 | "mesh-sdk's one fingerprint function": none here (DMC-5) | none until answered | | |
|
||||
|
||||
## Order and writers
|
||||
|
||||
- S1, S2, S3 first (the kept call and its errors); S4 with mesh-tools T1 in one pair; S6, S8, S11 before every module's
|
||||
use. S13 after `mesh-delivery` D5. One agent writes this repository; the mesh-tools T1 agent reads S4's commit.
|
||||
- Every module builds against the latest published mesh-sdk (ADR 0573 §2): the order between repositories is the
|
||||
package edges; S1 to S13 are published once before their users' check.
|
||||
|
||||
## Local facts
|
||||
|
||||
- Placement: as the `mesh-delivery` map says. Unit suite `go test ./...` in `go/`; the TypeScript half (`src/`) with
|
||||
`npm test`, untouched by these rows except S3 if its answer puts `away` in the TypeScript seat helpers (DQ-15).
|
||||
|
||||
## Test budget (§819)
|
||||
|
||||
`go/` holds 331 unit and 38 integration top-level tests by `go test -list` (22:30 CET).
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
---
|
||||
# 47 H2 build map: `mesh-tools` (the tool runner and the mesh MCP server)
|
||||
|
||||
Read at `origin/main` `02675a43eaf8` (2026-11-21 18:13 UTC), from an archive of that commit. Design: hq `35ddd45e`.
|
||||
DMC-n and DQ-n are the entries at the end of [H2-the-delivery-systems-owed-work](../H2-the-delivery-systems-owed-work.md).
|
||||
|
||||
## What exists today
|
||||
|
||||
Searches as run, from `mesh-tools/node-tools/`: `grep -n "StatePage" internal/bus/state.go`; `grep -rn "mesh/state.page"
|
||||
--include='*.go' .`; `grep -rln "mesh_wait" --include='*.go' .`; `grep -rn "UseSeats\|seatlist\." --include='*.go' .`;
|
||||
`grep -rn "SIGTERM\|Shutdown\|drain" --include='*.go' cmd internal`; `grep -rn "NakWithDelay" --include='*.go' internal`.
|
||||
|
||||
1. **What exists today.**
|
||||
- `mesh/state.page` (`internal/launch/launch.go:493`) is `Conn.StatePage` (`internal/bus/state.go:231-300`): the
|
||||
values in key order after `after`, each page reading every current value of the bucket again (`currentOf`), with
|
||||
`Next` the last key given.
|
||||
- `mesh_wait` (`internal/console/wait.go:60-140`) resolves `<seat>.<event>` against the seat list the tool runner reads
|
||||
live (`cmd/node-tools/seatlist.go:49-65`, `catalogue.UseSeats`) and a module's manifest events
|
||||
(`wait.go:195-262`); an undeclared event of a known seat is waited on and said undeclared at the time-out.
|
||||
- A stop: `signal.NotifyContext` on SIGTERM (`cmd/node-tools/main.go:58`); bundles get SIGTERM with the group
|
||||
(`internal/launch/launch.go:173-181`, `:728-735`); no drain of calls in flight, no `drain-bound`.
|
||||
- A seat ask a bundle did not take is offered again after `WorkBackoff` (5 s doubling to 10 minutes,
|
||||
`internal/bus/seat.go:71-79`, `:315`); a bundle's own delay is `seat_pull.go:193` `NakWithDelay(delay)`.
|
||||
2. **What relies on each.** `StatePage`: every bundle's `KeptState.Page` (the mesh-sdk map lists its users).
|
||||
`WorkBackoff`: every seat work queue a bundle pulls.
|
||||
3. **Fates.** `StatePage`'s key order and per-page replay go (§779). New parts: `drain-bound` (§813 (12)).
|
||||
|
||||
## Rows
|
||||
|
||||
| line | files and functions | subtask | acceptance (cites) | test |
|
||||
|---|---|---|---|---|
|
||||
| §779 | `internal/bus/state.go` `StatePage` (an ordered consumer after the cursor's sequence, 768 KB, `next`, `seen-again`), `internal/launch/launch.go:493` | T1 page by cursor (with mesh-sdk S4) | 10,000 keys read in pages deliver each kept message once; a key written again mid-read is marked `seen-again` (§779) | whole (tool runner) |
|
||||
| §813 (12) | `cmd/node-tools/main.go:58`, `internal/launch`, `internal/console`: take no new call after the stop, finish in flight within `drain-bound`, cut and say past it | T2 drain at stop | a stop during a 20 s call finishes it and refuses a call after the stop; a 40 s call is cut at 30 s and said (§813 (12)) | whole (tool runner) |
|
||||
| §799 | `internal/bus/seat_pull.go:193`, `seat.go:315`: the delay a run ended `again` is settled with (waits DMC-7) | T3 again-delays | §799 (kit) | unit |
|
||||
| §821 | `internal/console/wait.go`: nothing to build while the seat list carries each event (§821 is built in the contracts and holders) | none | a wait by seat and event name is answered (§821) | whole (each holder) |
|
||||
|
||||
## Order and writers
|
||||
|
||||
T1 with mesh-sdk S4 (one pair, the contract of the call first); T2 and T3 independent. One agent.
|
||||
|
||||
## Test budget (§819)
|
||||
|
||||
`node-tools` holds 160 unit and 9 integration top-level tests by `go test -list` (22:30 CET).
|
||||
@@ -1,190 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0682"
|
||||
- "ADR 0668"
|
||||
- "ADR 0664"
|
||||
- "ADR 0619"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0571"
|
||||
- "ADR 0304"
|
||||
- "ADR 0282"
|
||||
- "ADR 0259"
|
||||
---
|
||||
# 47, milestone H2: the forge bridge, the gate, the parts beyond the chain, the stores and the tools
|
||||
|
||||
The second file of milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md); the part opens at
|
||||
[H2-the-delivery-systems-owed-work](H2-the-delivery-systems-owed-work.md), whose introduction holds for this file too,
|
||||
and both are read whole. Lines are cited as "design 47 H2 §n" whichever file holds them.
|
||||
|
||||
### The forge bridge, the gate and the forge module
|
||||
|
||||
- §807 **An owed act failing on a part away stays owed.** (H-A-300 (1), (4), H-A-338 (5); row 177) The forge bridge
|
||||
performs an owed act of the gate's stream `owed` as a kept call (§775) through transport faults and `away` until
|
||||
`owed-away-bound` (a setting of the bridge, default 60 minutes), and only then says `owed.ended` with
|
||||
`could-not-be-performed`, naming its tries. `bridge_owed_again` gains `record` (a delivery record's source revision)
|
||||
to perform again every act of that record that ended could-not-be-performed; it is written in the hand-act log, and
|
||||
each act performed again checks its preconditions again (the pull request still open, the note not yet written)
|
||||
before it acts. Built in H2 in the bridge. How it is checked: whole (bridge): with the forge away for 60 s, a note act
|
||||
owed in that minute is performed after it, with no hand act; an act whose pull request closed meanwhile is ended,
|
||||
not performed.
|
||||
- §808 **One process mints the forge token at a time, and the token is a secret.** (ADR 0596; H-A-300 (3), H-A-338
|
||||
(1), H-A-339 (8), H-A-340 (4), H-A-344 (2), (10); row 177) The forge module's processes share one admin token, kept
|
||||
where the module keeps its secrets, its own in the vault, written and read through the seat `mesh-vault`'s verb
|
||||
`own` and never into another module's store or plain in a state, with the TTL `token-ttl` (a setting, default
|
||||
24 hours). A process the forge refuses first reads the vault's token; it takes the lease and mints only when the
|
||||
refused token is the vault's current one, else it uses the vault's newer token, so a refusal of a stale token mints
|
||||
nothing. A process that mints creates the lease key `mint` in the module's state `token-lease` (§820; create only, TTL
|
||||
`mint-lease`, a setting, default 60 s), mints, writes the token to its vault place, deletes at the forge the token
|
||||
it replaces, and deletes `mint`. A process that finds the lease taken waits for the token to change, at most the
|
||||
lease; past it, the lease has expired and the waiter creates the lease itself. `forge_token_lease` reads the lease's
|
||||
holder and since when and the token's age, never the token, which every read tool masks. Fate: each process's own
|
||||
mint goes. Built in H2 in the forge module. How it is checked: unit (forge module): two processes, one
|
||||
holding the old token, both refused, mint one token in all; whole: the forge holds one token for the account after; a minter killed while holding the lease is replaced after
|
||||
`mint-lease`.
|
||||
- §809 **The gate's ledger keeps one entry per module and revision.** (ADR 0595 §3; H-A-299 (1), H-A-338 (10), H-A-340
|
||||
(3), H-A-341 (3); row 176) The gate's ledger `records` (§820) writes one head entry per delivery record,
|
||||
`<branch>.<source>` (its outcome, the count of its movers and the times of §810), and one entry per mover,
|
||||
`<branch>.<source>.<module>` (its pipeline, version, machines and their `running` times); no entry names two modules.
|
||||
The gate refuses an entry over 64 KiB with the finding `record-too-large` (scope delivery), cleared when that entry is
|
||||
next written within 64 KiB or at the record's end. The ledger is never pruned; as a kept ledger it refuses when full
|
||||
(ADR 0595 §3), and the bus module's fill condition speaks for it. `gate_record` and `gate_records` join the entries.
|
||||
Fate: the whole-revision entry goes; the two records refused on 2026-11-21 are not written again. Built in H2 in the
|
||||
gate (mesh-catalog). How it is checked: whole (gate): a record of 126 movers writes 127 entries, none over 64 KiB,
|
||||
its head counting 126; an entry made too large raises `record-too-large`, and the record's end clears it.
|
||||
- §810 **A delivery record keeps its delivery time; the self-check judges it against its budget.** (ADR 0282 §1, §6,
|
||||
§7; ADR 0304; H-A-341 (1); row 111) At its end the gate writes on the head entry `delivery-time` (from `merge-called`
|
||||
to the last `running` of its movers on every present placing machine), `class` (`core` when it moves a core module of
|
||||
ADR 0282 §1, else `leaf`) and the phases of §785. `gate_times` answers each class's budget, the last seven days'
|
||||
median and worst, and every delivery over its budget with its longest phase (ADR 0282 §6's `times`), the budgets
|
||||
being the gate's settings `budget-core` (default 10 minutes, ADR 0282) and `budget-leaf` (default 3 minutes, ADR
|
||||
0304). As ADR 0282 §7 has it, the self-check's probe (the seat `mesh-self-check`) reads the gate's times and raises
|
||||
`over-budget` with the class as its id, naming the source revision and its longest phase; the next delivery of that
|
||||
class within its budget clears it; the gate raises nothing. Built in H2 in the gate and the self-check's probe. How it
|
||||
is checked: whole (gate and probe): a core record ended 11 minutes after its `merge-called` raises `over-budget` for
|
||||
the class `core`; the next core record within ten minutes clears it.
|
||||
- §811 **Every read filters before it sizes.** (H-A-299 (3); row 176) Every read verb and read tool of a delivery
|
||||
module applies its filters while it reads and answers at most 768 KB with `capped`, `total` and the cursor of §779,
|
||||
never "too big": among them the gate's `deliveries` (filters `repository`, `module`, `outcome`, `since`) and the
|
||||
bridge's `bridge_owed` by pull request (reading only that pull request's keys, in the bridge's process). How it is
|
||||
checked: the tools table of each pull request (principle 4); unit (gate): `deliveries` by repository over 4 MB of
|
||||
records answers under 768 KB.
|
||||
- §812 **Every kept store has a cap its owner prunes toward, judged at its own writes.** (ADR 0595 §3, §5, §6; H-A-227,
|
||||
H-A-299 (2), H-A-338 (10), H-A-339 (2), (8), H-A-340 (3), H-A-341 (2); rows 103, 176) Every state, log and objects
|
||||
entry a delivery module asks for names its cap. At each write it makes to such an entry, its owner judges the entry's
|
||||
fill from the figures the write's own answer gives (H-A-227, H-A-344 (7)), with no extra read, no poll and no timer, and when the fill passes `prune-mark` (a
|
||||
setting, default 70 %, below the bus module's raise mark of 75 %) prunes it, oldest first, down to `prune-target`
|
||||
(default 50 %), one journal line per prune. Ledgers, the hand-act log, `taken`, `unfinished`, `token-lease` and every state whose
|
||||
deleter §820 names other than the prune are never pruned; such a store refuses when full, said in its owner's
|
||||
journal (H-A-344 (1)). mesh-sdk's generic state
|
||||
tools gain `state_prune_now` (entry, why: prunes to the target now) and `state_keep` (entry, key, until, why: a key
|
||||
never pruned before its until), both written in the hand-act log; the fill is read and the limits applied through
|
||||
the seat `mesh-broker`'s `list`, `show` and `apply`. First the bridge's state `performed` (full on 2026-11-21), which
|
||||
also drops entries older than `performed-keep` (default 3 days). A forge tool, `forge_merged` (repository, from, to),
|
||||
lists merged pull requests by number with merge commit, time and whether a merge call made it (row 103). Built in H2
|
||||
in mesh-sdk (the prune helper and the tools), every delivery module and the forge module. How it is checked: the
|
||||
manifest check of §814; whole (bridge): a write that takes `performed` past 70 % prunes it to 50 %; a key under
|
||||
`state_keep` survives the prune.
|
||||
|
||||
### The assigner, the node-engine, the tool runner, the bus module, the registry and the teller
|
||||
|
||||
- §813 **The parts this milestone touches beyond the chain.** (each clause names its source)
|
||||
1. *One writer per composition key, and the engine applies only a newer write* (H-A-302 (1) to (3), H-A-303,
|
||||
H-A-306, H-A-338 (8); row 179): a composition write carries `run`, the composition run's pipeline sequence, and
|
||||
the holder of `mesh-wants` writes by compare-and-set refusing a lower `run`; a run whose pipeline ended writes
|
||||
nothing more; the node-engine applies a composition again only when a part it could read differs and its `run` is
|
||||
newer than the one it applied, naming the run in its journal. The order is an edge of the module graph the delivery
|
||||
derives (the composition value's form): the node-engine that reads `run` tolerantly (§780) runs before the
|
||||
assigner writes it. Built in the assigner and the node-engine. Checked: unit (each).
|
||||
2. *A failed keeping runs again* (row 137): a keeping of the assignment graph revisions that fails marks itself
|
||||
wanted and runs again after `keeping-retry` (a setting, default 30 s, the holder's own deadline, ADR 0682 §11),
|
||||
raising `keeping-failed` (scope module) at the third failure in a row, cleared at the next that succeeds;
|
||||
`assigner_keep_now` (why) runs the keeping at once, written in the hand-act log (H-A-344 (4)). Checked: unit.
|
||||
3. *Composed values read by resource* (H-A-306 (4); row 181): the node-engine's tool `engine_composition_diff`
|
||||
(module, a revision or digest) answers, per resource, the entries that differ between the running composition
|
||||
and the other, environment entries by name with secret values masked. Checked: unit.
|
||||
4. *The render marks a derived rule's scope* (ADR 0683; H-A-319; row 188): the node-engine writes on each derived
|
||||
accept rule of the packet filter the comment `derived <module> <listen> scope <any|private-network|local-network>`,
|
||||
and the holder of `node-packet-filter` reads a port's scope from `rules`, not from the rule's shape. Checked: unit
|
||||
(node-engine render); whole (packet filter): `allow` without a source is refused for a `private-network` port.
|
||||
5. *The bus module's tools read flow* (row 124): `nats_consumers` sorts by `delivered-rate` (messages a second
|
||||
measured over `rate-window`, an argument, default 10 s, within the one call) and by creation time;
|
||||
`nats_connections` answers a connection's busiest subscriptions by messages. Checked: unit.
|
||||
6. *The keeper withdraws a refused request's ask* (row 123): a drop or rebuild request the keeper refuses at once
|
||||
cancels its ask on the seat `operator-channel` in the same pass (ADR 0259 §3's cancel). Checked: unit.
|
||||
7. *The registry's list is paged, and it takes the sweep's removals* (ADR 0571 §2; ADR 0682 §10; H-A-250 (3); row
|
||||
125): the artifact registry seat's `list` takes `module` and the cursor of §779 and answers at most 768 KB; the
|
||||
artifact store's sweep reads it page by page once per pass; the registry takes a removal from the seat
|
||||
`artifact-store`'s holder, and its refusal "not the sweep's" goes (every account may call every verb). Checked:
|
||||
whole (sweep): a pass over 20,000 artifacts removes what it judges.
|
||||
8. *The registry drops a deleted chunk's leftovers* (H-A-227): when it deletes chunks it purges their subjects from
|
||||
the object store, so a store's kept descriptions equal its live objects. Checked: whole (registry): after 1,000
|
||||
chunks are deleted, the store's messages equal its live objects.
|
||||
9. *The usage view judges a build module by its running asks* (row 138): the status view reads a build module's
|
||||
work from its seat's `current` (§801), not from the node-engine's held phase. Checked: unit (view).
|
||||
10. *The teller's ask-again for want of room goes* (ADR 0682 §14; H-A-295): with A-424, the teller's ask-again for an
|
||||
ask refused for room and its test are removed. Checked: the teller's suite holds no such test.
|
||||
11. *The destroy-level answer's channel waits for its research* (ADR 0259; H-A-237, H-A-334 (2); row 114): the
|
||||
bus module's keeper asks its drop and rebuild warrants at the approve level, as H-A-237 bends it, until a research
|
||||
effort designs the channel that carries the destroy proof; H2 builds no such channel, and the bend's line in the
|
||||
keeper's code names that research as its end. Checked: unit (keeper): a drop asks at the approve level.
|
||||
12. *The tool runner drains at a stop* (H-A-342 (2); row 179): once told to stop, the tool runner takes no new call,
|
||||
finishes the calls in flight within `drain-bound` (a setting, default 30 s), then exits; a call that outlives the
|
||||
bound is cut, with a journal line naming the bundle, the verb and the call's age, and its caller sees a transport
|
||||
fault. The node-engine, replacing the tool runner, waits the drain bound for the old one to exit before it starts
|
||||
the new one. Built in the tool runner (mesh-tools) and the node-engine. Checked: whole (tool runner): a stop during a
|
||||
20-second call finishes it and refuses a call made after the stop; a 40-second call is cut at 30 s and said; unit
|
||||
(node-engine): the new tool runner starts only after the old one exits or the bound passes.
|
||||
|
||||
### The new stores
|
||||
|
||||
- §820 **Every store this part adds names its form, cap, key life and deleter.** (ADR 0595 §2, §3; H-A-338 (6),
|
||||
H-A-339 (7), H-A-341 (7)) Each is asked for in its owner's `requires` by its template; a foundation part (ADR 0619 §1, ADR 0666 §4) declares
|
||||
each of its stores (`unfinished`, `publishes`, `taken`, `dry-runs`, the findings stream) in its old section with the
|
||||
same cap and life (H-A-229, H-A-344 (3)). A put refused because a store
|
||||
or queue is full is said in the owner's journal and asked again at the kept-call pace (§775).
|
||||
|
||||
| store | owner | template | cap | life of a key | deleted by |
|
||||
|---|---|---|---|---|---|
|
||||
| `taken` | every holder of a kept call (§775) | state | 8 MiB | the ask's bound (TTL) | the TTL |
|
||||
| asks of `mesh-builds` and `mesh-wants` | the broker, from the seats (§777) | work queue | 10,000 messages | 1 day | the holder's acknowledgement |
|
||||
| `unfinished` | pipeline runner (§786) | state | 8 MiB | none | the runner, or `runner_unfinished_drop` |
|
||||
| `outputs`, install archives included | each build module, their owner (§791, §800) | objects | 1 GiB | 7 days (the store's max-age) | the bus, at the max-age; no sweep |
|
||||
| the findings stream | every module (§783) | events | 8 MiB | 7 days | the bus, oldest first |
|
||||
| `publishes` | builder (§793) | work queue | 64 MiB | 7 days | the builder's acknowledgement or termination |
|
||||
| `token-lease` | forge module (§808) | state | 1 MiB | `mint-lease` (TTL) | the minter, or the TTL |
|
||||
| `dry-runs` | indexer (§804) | state | 16 MiB | 1 hour (TTL) | the indexer at the answer and at its start |
|
||||
| `records` | gate (§809) | ledger | 1 GiB | none | never |
|
||||
|
||||
How it is checked: the manifest check of §814 refuses each without its cap; each owner's whole test fills its store
|
||||
to the mark and reads the prune or the refusal said.
|
||||
|
||||
### The tools this part adds
|
||||
|
||||
| tool | module | reads or steers | line |
|
||||
|---|---|---|---|
|
||||
| `builder_asks`, `builder_ask_drop`; `assigner_asks`, `assigner_ask_drop` | builder; assigner | what waits on and is taken from the seats' queues; one ask ended | §777 |
|
||||
| `assigner_keep_now` | assigner | the keeping of the graph's revisions, now | §813 (2) |
|
||||
| `runner_unfinished`, `runner_unfinished_drop`, `runner_unfinished_place` | pipeline runner | the movers put in a pipeline again; one placed now | §786 |
|
||||
| `runner_health` (`registrations-read`) | pipeline runner | whether the registrations view is read | §788 |
|
||||
| `runner_movers`, `runner_show` (filters) | pipeline runner | one pipeline in parts | §789 |
|
||||
| `runner_step_output` and the build seats' `output` | pipeline runner, build modules | a step's output | §791 |
|
||||
| `builder_publish_queue`, `builder_publish_drop`, `builder_publish_first` | builder | the publish queue | §793 |
|
||||
| `builder_unbuildable` | builder | the plans no seat builds | §795 |
|
||||
| `build_current` and the build seats' `current` | builder, build modules | what each holder takes and runs | §801 |
|
||||
| `indexer_dry_runs` | indexer | the dry runs' scratch state | §804 |
|
||||
| `indexer_registrations` | indexer | the registrations | §806 |
|
||||
| `bridge_owed_again` (`record`) | forge bridge | every owed act of a record again | §807 |
|
||||
| `forge_token_lease` | forge module | the token lease and the token's age | §808 |
|
||||
| `gate_times` | gate | delivery times against their budgets | §810 |
|
||||
| `state_prune_now`, `state_keep` | mesh-sdk, every module | prune now; keep a key from the prune | §812 |
|
||||
| `forge_merged` | forge module | merged pull requests by number | §812 |
|
||||
| `engine_composition_diff` | node-engine | composed values by resource | §813 (3) |
|
||||
| `nats_consumers`, `nats_connections` (sorts) | bus module | flow per consumer and connection | §813 (5) |
|
||||
| `seat-list`, `indexer_validate_before` | indexer (seat `mesh-catalog`) | the seat list as one object; the problems validate did not count | §814 |
|
||||
@@ -1,606 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
design: 47
|
||||
milestone: H2
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0682"
|
||||
- "ADR 0668"
|
||||
- "ADR 0666"
|
||||
- "ADR 0664"
|
||||
- "ADR 0619"
|
||||
- "ADR 0596"
|
||||
- "ADR 0595"
|
||||
- "ADR 0573"
|
||||
- "ADR 0571"
|
||||
- "ADR 0548"
|
||||
- "ADR 0527"
|
||||
- "ADR 0525"
|
||||
- "ADR 0499"
|
||||
- "ADR 0436"
|
||||
- "ADR 0304"
|
||||
- "ADR 0282"
|
||||
- "ADR 0267"
|
||||
---
|
||||
# 47, milestone H2: the delivery system's owed work, as design lines
|
||||
|
||||
Milestone H2's part of [design 47](../47-delivery-from-commit-to-delivered.md), read whole by its builders with its
|
||||
second file, [H2-stores-and-tools](H2-stores-and-tools.md) (the forge bridge, the gate and the forge module, the parts
|
||||
beyond the chain, the new stores and the tools). Milestone H1 (the clean state and the one chain,
|
||||
[H-deliver-the-delivery-system](H-deliver-the-delivery-system.md)) ended at 19:31 on 2026-11-21 with both its proofs
|
||||
shown; what its live run met and did not build is owed here: every item the lead's answers H-A-227 to H-A-331
|
||||
([H-lead-answers](H-lead-answers.md)) name as owed to H2, every *Owed* of rows 103 to 199 of the plan's section 10,
|
||||
and the answers to the four reviews by architectural domain (H-A-338 to H-A-341). The lines are numbered after
|
||||
milestone H's §774 and cited as "design 47 H2 §n". Where an H2 line and an H line or a lead's answer differ, the H2
|
||||
line holds. Every module named builds against the latest published mesh packages (ADR 0573 §2), so the order between
|
||||
repositories is the module graph's (the package edges), not this part's. The records each line follows are named in
|
||||
it; a choice within them that no record or answer made is this part's own, given with its reason. A line that changes
|
||||
a shared form (a seat's definition, mesh-sdk's catalog) rebuilds every module that imports it, once, in H2's one
|
||||
pipeline of every module (§818).
|
||||
|
||||
H2 is one release of playbook 07: prepared by `mesh-preparer`, built, reviewed once, checked once, and delivered by
|
||||
its own pipelines, with no hand pack (section 7 of the plan). Its two proofs (§816, §817) close it.
|
||||
|
||||
### The asks between the delivery parts
|
||||
|
||||
- §775 **Every ask of a delivery part to a seat is a kept call, paced.** (ADR 0668 §1 to §3, §7; ADR 0664 §1; H-A-296,
|
||||
H-A-300 (1), H-A-338 (6), H-A-339 (4), H-A-340 (2); rows 170, 177) The pipeline runner's asks (build, lint, unit,
|
||||
integration, validate, composition, install and the seat `mesh-builds`' `published`), the holder of the seat
|
||||
`mesh-wants`' `compose-candidate` asks to each node-engine, the forge bridge's owed acts on the seat `git` and the
|
||||
builder's publish asks to the registry seats are made through mesh-sdk's kept-call form, marked safe to repeat: each
|
||||
carries its ask id, and every holder takes an ask once by its id (ADR 0668 §2), keeping the ids it took in its own
|
||||
state `taken`, key `<seat>.<ask>`, TTL the ask's bound (§820): the builder, the holder of `mesh-wants`, every
|
||||
node-engine for `compose-candidate`, the forge module for the seat `git`'s verbs and each registry for its publish.
|
||||
On a transport fault (ADR 0664 §1's classes, a call's own deadline, and the kind `away` of §776) the form calls
|
||||
again after `kept-call-pace-first` (default 1 s), doubling to at most `kept-call-pace-max` (default 30 s), each wait
|
||||
drawn within 20 % of its value so many callers do not call in step: settings every module using the form declares
|
||||
with these defaults (principle 11), chosen so a holder between two lives (a restart takes 20 to 50 s, row 179) is
|
||||
met within one minute without a call a second. It writes one journal line per seat at the first fault and then at
|
||||
most once a minute, naming the seat, the verb, the asks waiting and the count of calls; it stops at the caller's
|
||||
bound: the runner's `ask-unanswered-bound` (H-A-238, default 10 minutes), the holder's `compose-ask-bound` (a
|
||||
setting, default 10 s), the bridge's `owed-away-bound` (§807). Past the bound the step ends could-not-run, or the act
|
||||
could-not-be-performed, naming every call's time and words; `call-unanswered` is written at five minutes as ADR 0668
|
||||
§3 has it. A refusal of what was asked ends at once, as today. Fate: the runner's and the holder's one-shot asks,
|
||||
which ended a step at the first "no responders", go. Built in H2 in mesh-sdk (the pace, the `taken` state), the
|
||||
pipeline runner, the assigner, the forge bridge and the builder (mesh-delivery), the node-engine, the forge module
|
||||
and the registries. How it is checked: unit (mesh-sdk): a call met by no responders twice and then answered returns
|
||||
the answer and logs one line; a call past its bound returns every try; a refusal returns at once; a holder given the
|
||||
same ask id twice acts once. Whole (runner): a composition ask whose holder is away for 40 s passes its step with no
|
||||
hand act.
|
||||
- §776 **A holder says `away` when a part it depends on is away.** (ADR 0668 §1 and ADR 0664 §1 (insights of
|
||||
2026-11-21, accepted); H-A-300 (2), H-A-301, H-A-334 (3), H-A-339 (5); rows 177, 178) mesh-sdk's seat error answer
|
||||
gains the kind `away`, with `part` (what did not answer) and `words`. The forge module, holder of the seat `git`,
|
||||
answers `away` when the forge answers 401, 502 or 503 or a connection fault and the forge's own unauthenticated
|
||||
version read fails or names its store unavailable; it answers `refused`, "the forge refuses the mesh's admin
|
||||
account", only when that read succeeds and a freshly minted token (§808) is refused too, and it never words a refusal
|
||||
as an account to create. Every caller reads `away` as a transport fault (§775). This adds one class, a holder's own
|
||||
word that what it depends on is away, to the classes ADR 0664 §1 and ADR 0668 §1 list; the line rests on those two
|
||||
insights, accepted on 2026-11-21. Built in H2 in mesh-sdk (the error kinds) and the forge module
|
||||
(mesh-catalog). How it is checked: unit (forge module): a 401 with the version read failing answers `away`; a 401
|
||||
with the read passing and the fresh token refused answers `refused`. Whole (forge module): with the store stopped for
|
||||
30 s, a merge call in that window answers `away` and lands when called again.
|
||||
- §777 **The seats `mesh-builds` and `mesh-wants` take their asks from a work queue and say `ask-taken`.** (ADR 0525
|
||||
§1, §2, §6; ADR 0436 §6; ADR 0664 §2; H-A-241, H-A-243 (1), (2), H-A-320 (2), H-A-338 (4), (7), H-A-339 (7), (8),
|
||||
H-A-340 (1), H-A-341 (4); rows 118, 130, 189) Each seat's definition (the delivery repository's contracts module)
|
||||
declares its accepted kinds as work-queue streams the broker derives, as ADR 0525 §2 has it for the build seats:
|
||||
`build` on `mesh-builds`, `validate` and `compose` on `mesh-wants`; each `max-age` 1 day and `max-msgs` 10,000, one
|
||||
shared worker consumer its holder pulls, with ack wait 60 s, in-progress every 20 s, max ack pending 1,000, max
|
||||
deliveries 5 (above ADR 0664 §2's three) and a duplicates window of 2 minutes (ADR 0436 §6). The holder pulls every
|
||||
ask waiting at once, never one at a time, acknowledges an ask when it says the ask's end, sends in-progress while it
|
||||
works (ADR 0525 §6), and says `ask-taken` on the seat's family at the pull, subject `<seat>.ask-taken.<ask>`,
|
||||
carrying `ask`, `node` and `at`; the definition declares `ask-taken`, so only the seat's holder publishes it. The
|
||||
runner consumes both seats' `ask-taken`. An ask put while its holder is down waits on the stream. The runner puts an
|
||||
ask again only when its put met a transport fault; a put refused by a full stream is said in the journal and asked
|
||||
again at the kept-call pace (§775). `builder_asks` and `assigner_asks` read what waits and what is taken on their
|
||||
seat's stream; `builder_ask_drop` and `assigner_ask_drop` (ask, why) end one ask, written in the hand-act log. Fate:
|
||||
the holders' plain subscriptions go; the runner's putting again of every open ask on the holder's `running`
|
||||
(H-A-243 (1)) goes; `ask-silent-bound` and its bound key (H-A-243 (2)) go; the mesh-builds stream that no consumer
|
||||
took (1,524 asks on 2026-11-21) is rebuilt empty through the bus module's tool `nats_recreate`, on the operator's
|
||||
warrant (ADR 0595 §5), before the new builder and the new assigner start, so the rebuilt stream carries no message.
|
||||
Built in H2 in mesh-delivery (the contracts module, the builder, the assigner, the runner). How it is checked: whole
|
||||
(builder): a build ask put while the builder is stopped is taken and ended after its start; whole (assigner): the
|
||||
same for a validate ask; after a pipeline's end the streams' consumers hold 0 pending; unit (runner): a put refused
|
||||
for a full stream is said and asked again.
|
||||
- §778 **The unanswered bound counts from the pull.** (H-A-238 (5), H-A-320 (4), H-A-340 (1), H-A-341 (4); ADR 0664
|
||||
§4; row 189) The runner keeps on each step of its record `asked-at` (when the ask is put) and `taken-at` (from the
|
||||
seat's `ask-taken`), RFC 3339. The bound key `ask.<seat>.<ask>` is armed at `ask-taken` with the bound less the time
|
||||
since `taken-at`, and again at every start for every open ask, so a restart never grants a fresh bound; an ask whose
|
||||
time is spent at a start ends could-not-run at once. A step ended by its bound drops its ask through the seat's
|
||||
`drop` (as ADR 0664 §4 has it for the build seats), so no holder works on it after. An ask not taken counts no bound:
|
||||
the runner's health names a step whose ask is untaken past `stalled-bound` (§790), and an ask still untaken
|
||||
`ask-unanswered-bound` after its `asked-at` ends the step could-not-run "its ask was not taken: <seat>'s holder takes
|
||||
none", so no slot is held without end (H-A-344 (6)). Built in H2 in the runner. How it is checked: unit (runner): an
|
||||
ask taken 9 minutes before a restart, with a 10-minute bound, ends one minute after the start and is dropped; an ask
|
||||
untaken for `stalled-bound` is named by the health; an ask untaken for the whole bound ends could-not-run naming the
|
||||
holder as not taking.
|
||||
|
||||
### mesh-sdk: the shared forms
|
||||
|
||||
- §779 **A page read continues from an opaque cursor in sequence order.** (H-A-254, H-A-255 (2), H-A-292, H-A-293;
|
||||
row 129) The state page read that the tool runner serves (`mesh/state.page`) reads a state's keys in sequence order
|
||||
from an ordered consumer starting after the cursor's sequence, never a replay of the bucket per page. The cursor is
|
||||
an opaque string the caller hands back (`next`, empty at the end); a page holds at most 768 KB, and a key written
|
||||
again between two pages comes again in a later page with `seen-again` set, so a reader knows it. Every reader of a
|
||||
large state may page; H-A-292's and H-A-293's one-page exception ends. Built in H2 in mesh-sdk (the call's contract
|
||||
and client) and the tool runner (mesh-tools), and its callers in the same group. How it is checked: whole (tool
|
||||
runner): a state of 10,000 keys read in pages delivers each kept message once across all pages; a key written again
|
||||
mid-read is marked `seen-again`.
|
||||
- §780 **A reader of another part's value decodes it tolerantly and says its form.** (H-A-309, H-A-338 (8), H-A-341
|
||||
(6); row 183) Every seat value, event body and verb answer gains `form`, an integer the seat's definition raises at
|
||||
every field added or removed; `form` is left out while it is 1, and an absent `form` reads as 1. mesh-sdk's
|
||||
generated decoders for reading another part's value, event or answer keep unknown fields, never refuse them, and
|
||||
return `form`; a tool whose record's `form` differs from the one it was built with says "form N, this reader knows M"
|
||||
in its answer. A writer still validates its own value strictly before it writes. Fate: the runner's dropping of
|
||||
`kept-revisions` before the seat's decode (row 190) goes. Built in H2 in mesh-sdk (the seat generator and its
|
||||
decoders) and every seat definition (a regeneration). How it is checked: unit (mesh-sdk): a value, an event and an
|
||||
answer with an unknown field decode and return their form; an absent `form` reads as 1; the seat generator's check
|
||||
fails a definition whose fields changed with `form` unchanged.
|
||||
- §781 **A tools program reads its module's settings.** (H-A-322, H-A-330; rows 190, 199) The node-engine composes a
|
||||
module's settings into the module's slice of the tool runner's `MESH_TOOL_ENV` in the same files it composes for the
|
||||
module's process, and mesh-sdk's settings reader reads them in a tools bundle as in a process. A bound one module
|
||||
keeps on another's verb is that verb's `timeout` in its seat definition (built in H1), read by the caller from the
|
||||
seat list: the packet filter's holder asks the node-engine seat's `converged` within that verb's `timeout`, and its
|
||||
named 10 s goes. Built in H2 in the node-engine (`mesh-host`), mesh-sdk and the packet filter module. How it is
|
||||
checked: unit (mesh-sdk): a tools bundle reads a setting the manifest sets; whole (runner): §790.
|
||||
- §782 **The bus wrappers are safe for concurrent use.** (row 137, met twice) mesh-sdk's wrappers around one bus
|
||||
handle guard each call the client does not allow at once with a lock inside the wrapper, so no module needs a
|
||||
handle per goroutine (one place, principle 7). Built in H2 in mesh-sdk. How it is checked: unit under the race
|
||||
detector: concurrent gets, puts and watches through one wrapper.
|
||||
- §783 **A module's findings history drops its oldest.** (ADR 0595 §2, §3; H-A-227, H-A-344 (3), (5); row 104) The
|
||||
stream a module's findings writer appends to (three stood full on 2026-11-21: the runner's, the builder's, the
|
||||
node-engine's) is asked for by the events template, which drops the oldest when full, with `max-bytes` 8 MiB and
|
||||
`findings-max-age` (default 7 days); a foundation part (ADR 0619 §1, ADR 0666 §4) declares it in its old section
|
||||
with the same cap and life (H-A-229). Its fill is read through the seat `mesh-broker`'s `show`. The findings state itself is unchanged. Built in H2 in mesh-sdk (the
|
||||
writer's requires) and every delivery module's manifest. How it is checked: whole (runner): 10,000 findings written
|
||||
past the cap refuse none.
|
||||
|
||||
### The pipeline runner (seat `mesh-pipeline-runner`; mesh-delivery-pipeline)
|
||||
|
||||
- §784 **An ask placed and a step's end are journal lines.** (H-A-320 (1), H-A-333, H-A-341 (5); row 189) The runner
|
||||
writes one line when it places an ask, "`<pipeline>` `<mover>` `<step>` asked on `<seat>`", and one when a step ends,
|
||||
"step ended `<pipeline>` `<mover>` `<step>` `<outcome>` in `<duration>`", the latter in the one place that says
|
||||
`step-ended`, so every end writes it: the unanswered bound's, the end at placing, a supersede, a re-pin, the
|
||||
approval's end, the start pass and the verbs that end a step. Beside these two lines per step only the per-mover wait
|
||||
lines (H-A-326 (3), §787) and §775's fault lines are written. Built in H2. How it is checked: unit: each way a step
|
||||
ends writes exactly that line once.
|
||||
- §785 **`pipeline-ended` carries the pipeline's phases.** (ADR 0282 §1, §6; row 111) `pipeline-ended` gains
|
||||
`phases`: `taken` (the take-in), `placed`, `ended`, and for each step kind (build, lint, unit, integration, validate,
|
||||
composition) the earliest start and the latest end across its movers, RFC 3339. Each mover's own step times stay in
|
||||
the step log, read with `runner_show` (§789). Built in H2 in the runner and the seat's definition. How it is checked:
|
||||
unit: a pipeline of two movers ends with each step kind's span; the gate reads it (§810).
|
||||
- §786 **A mover left unfinished by another's failure is put in a pipeline again.** (ADR 0682 §6; H-A-339 (7), (8);
|
||||
rows 133, 147, 162, 167) When a pipeline ends `failed`, `cancelled` or `could-not-run`, each mover whose own required
|
||||
steps all passed or never ran, and whose fingerprint no newer revision moved, is kept in the runner's state
|
||||
`unfinished` (§820), key `<branch>.<module>`, value `fingerprint`, `revision`, `pipeline` and `outcome`, and named in
|
||||
`pipeline-ended`'s new field `unfinished`. At the branch's next kept catalog revision of any `call-kind`, the runner
|
||||
adds each such mover whose fingerprint is still its entry's there to that revision's pipeline, or starts one for them
|
||||
alone when the revision moves nothing, with one journal line per mover added again. The key is deleted by the runner
|
||||
when the mover's pipeline ends passed or a newer fingerprint moves it, or by `runner_unfinished_drop` (one key, with
|
||||
`why`); `runner_unfinished_place` (one key, with `why`) puts the mover in a pipeline of its own at once; both are
|
||||
written in the hand-act log, and `runner_unfinished` reads the state. A mover whose own required step failed waits
|
||||
for its fingerprint to move, as today. Fate: the lead's probe merges of row 167 end. Built in H2. How it is checked:
|
||||
whole (runner): of a pipeline of two movers one fails its unit step; `pipeline-ended` names the other in
|
||||
`unfinished`, the next take-in's pipeline carries it, and it is wanted.
|
||||
- §787 **A kept mover waiting on its revision says so.** (H-A-171, H-A-284, H-A-287) A kept mover whose kept revision
|
||||
the runner's view does not hold yet carries `unplaced` `kept-revision-unread` with `revision`, said once in the
|
||||
journal ("waits for its kept revision N to be read") and read with `runner_show`. Built in H2. How it is checked:
|
||||
unit.
|
||||
- §788 **The registration check waits for its view.** (H-A-262, H-A-265 (4), H-A-339 (8); row 141) The runner judges
|
||||
`registration-missing` only once its registrations view's first read is in; before that it says "registrations not
|
||||
yet read" once and places no step whose registration it has not read. `runner_health` answers
|
||||
`registrations-read` (true or false, and since when). Built in H2. How it is checked: unit: a start with the view
|
||||
unread raises no `registration-missing`, answers `registrations-read` false, and places the movers once it is read.
|
||||
- §789 **A pipeline is read in parts.** (H-A-299 (3); rows 136, 142) The verb `show` and the tool `runner_show` take
|
||||
`mover`, `step` and `state` filters applied while reading, and answer at most 768 KB with `capped`, `total` and the
|
||||
cursor of §779; `runner_movers` (a pipeline's key) answers each mover with one word per step (`passed`, `failed`,
|
||||
`running`, `waiting`, `not-run`). Built in H2. How it is checked: unit: one mover's steps of a record of 129 movers
|
||||
answer under 64 KB; `runner_movers` of 1,000 movers answers under 768 KB.
|
||||
- §790 **The stalled bound is a setting.** (H-A-311 (3), H-A-313, H-A-322; row 190) The five minutes after which the
|
||||
runner's health names a running pipeline with nothing open, or a step whose ask is untaken (§778), become the
|
||||
runner's setting `stalled-bound` (default 5 minutes, the rule nothing-moved-in-five-minutes), read by its process
|
||||
and its tools program (§781). Built in H2. How it is checked: whole: with `stalled-bound` at one minute, the health
|
||||
names such a pipeline after one minute, and no longer names it once a step is placed in it.
|
||||
- §791 **A step's output is read where it is kept.** (H-A-294, H-A-341 (7); rows 144, 165, 168) A build module keeps a
|
||||
run's output in its `outputs` objects (§820), named on its step key `<node>.<ask id>` (ADR 0525 §6); the build seats
|
||||
`node-build-go`, `node-build-node` and `node-build-image` gain the read verb `output` (input `ask`; answer the
|
||||
output's last 64 KB, its size, and the failing tests' names with their words, or "no longer kept" past the objects'
|
||||
max-age), and the runner's tool `runner_step_output` (pipeline, mover, step) asks it of the holder on the node the
|
||||
step key names. Fate: the runner's objects `step-outputs`, which hold 0 bytes, go, dropped through the bus module.
|
||||
Built in H2 in the build seats' definitions, the three build modules (mesh-catalog) and the runner. How it is
|
||||
checked: whole (Go build module): a failing unit test's words are read through `runner_step_output`; an output past
|
||||
its max-age answers "no longer kept".
|
||||
- §821 **Every event of the delivery parts is waited on by its seat and name.** (H-A-338 (4), H-A-343) Every event
|
||||
the runner says (`pipeline-started`, `step-ended`, `pipeline-ended`, `wait-held`, `wait-ended` and the re-pin's), the
|
||||
builder's `ask-taken` and `version-reserved` and the holder of `mesh-wants`' `ask-taken` are declared in their
|
||||
seat's definition under the seat's events family, so a wait by seat and event name (`mesh_wait` with
|
||||
`mesh-pipeline-runner.pipeline-ended`) is answered and no session reads a journal on a timer. Built in H2 in the
|
||||
delivery repository's contracts module (the seat definitions) and the three holders. How it is checked: the seat list
|
||||
carries each family and name; each holder's whole-module test waits on each of its events by name and is answered.
|
||||
|
||||
### The builder (seat `mesh-builds`; mesh-delivery-builder)
|
||||
|
||||
- §792 **An answered ask is a journal line.** (H-A-320 (1), H-A-333; row 189) The builder writes one line per build
|
||||
ask it answers, "answered `<ask>` `<pipeline>` `<movers>` `<step>` `<outcome>`", in the one place an ask is answered
|
||||
(its build step's finish), beside the line per entry saying an existing build or one built now; the holder of
|
||||
`mesh-wants` one per validate or compose ask answered. Built in H2 (builder, assigner). How it is checked: unit.
|
||||
- §793 **The publish queue is a work-queue stream.** (H-A-290, H-A-291, H-A-338 (5); row 158) The builder's publish
|
||||
items travel on its work queue `publishes` (§820), subject `publish.<holder>.<class>.<module>.<version>` with class
|
||||
`live` (a build a pipeline's step waits on) or `again` (asked again at a start), one consumer per holder and class
|
||||
that the builder pulls, `live` first, at most four sends in flight per holder (H-A-290 (3)); an item is acknowledged
|
||||
when its publish is heard or confirmed (H-A-274), terminated when its build is withdrawn or superseded (H-A-290 (2),
|
||||
H-A-291 (1)). `builder_publish_queue` reads the stream's counts per holder and class, the oldest and newest, and a
|
||||
capped list; `builder_publish_drop` (module, version, why) terminates one item; `builder_publish_first` (module,
|
||||
version, why) puts one item again as `live` and terminates the old; both are written in the hand-act log. Fate: the
|
||||
state bucket of publish items, its listing and its relisting go; its items are put on the stream once at the
|
||||
builder's first start of this release, each with the message id `<holder>.<module>.<version>`, so a move started
|
||||
twice puts each item once within the duplicates window; then the bucket is dropped through the bus module. Built in
|
||||
H2. How it is checked: whole (builder): a live publish enqueued behind 100 `again` items is sent first; a dropped
|
||||
item is never sent; a move run twice puts each item once.
|
||||
- §794 **The builder's handling of an event costs one read and one write.** (H-A-269, H-A-271, H-A-280, H-A-340 (7);
|
||||
row 152) A heard `published` or `package-published` costs one read of the index by digest (or by version on a miss,
|
||||
H-A-271) and one write; the builder logs any event whose handling passed 100 ms, with its duration and why, and its
|
||||
health names an events backlog whose oldest message is older than five minutes. Built in H2. How it is checked: unit
|
||||
(builder): handling 1,000 published events over 2,000 reservations makes exactly one index read and one write each;
|
||||
whole: a backlog held six minutes makes the health name it.
|
||||
- §795 **A plan no seat can build is said once.** (H-A-226's owed; rows 101, 166) A module whose artifact no seat
|
||||
builds is kept in the builder's memory with its language and kind, worked out again at every start and every change
|
||||
of the seat list, and said in one summary line each time, "N modules have an artifact no seat builds:" with each
|
||||
language and kind and its count; `builder_unbuildable` lists them. Fate: the line per module and definition goes.
|
||||
Built in H2. How it is checked: unit: 6,500 unbuildable plans write one line.
|
||||
- §796 **A tag names its commit; the builder reads it before it reserves.** (H-A-234 (2), H-A-245, H-A-246, H-A-341
|
||||
(3); rows 73, 121) The seat `git`'s `tags` answer gains `commit` per tag, and its listing's description says a
|
||||
missing directory answers `not-found` (H-A-232): one contract change, its holder the forge module and mesh-sdk's
|
||||
bootstrap copies in one group. The builder reads a module's tags once per catalog revision it reserves under, and
|
||||
skips a number whose tag stands at another commit, with the finding `version-tagged-elsewhere` (scope module),
|
||||
cleared at the module's next `version-released`; a read that meets a transport fault or `away` (§776) lets the
|
||||
reservation go on, said in the journal. A tag is never moved. The tag the builder writes for a Go package is
|
||||
`<directory>/v<version>`, which the Go toolchain's direct fallback reads (row 73); the `go/v<version>` tags go from
|
||||
new versions. Built in H2 in the seat `git`'s definition, the forge module, mesh-sdk's copies and the builder. How it
|
||||
is checked: whole (builder): a tag standing at another commit makes the builder reserve the next number and raise
|
||||
the finding, which clears at the next release.
|
||||
- §797 **The build record carries its end.** (H-A-257) The builder's record of a build carries `ended` and `outcome`
|
||||
when it ends, so a reader of the builds (the artifact store's sweep) reads no key history. Built in H2. How it is
|
||||
checked: unit.
|
||||
- §798 **A publish keeps its time.** (H-A-328, H-A-331; row 197) A reservation's published mark keeps `at` (when the
|
||||
builder heard or confirmed the publish) and a kept release keeps the published `digest`; the verb `published` answers
|
||||
both where kept and leaves them out for marks written before. Where H1's tail already built this, H2's prepare reads
|
||||
it on main and builds only the rest. How it is checked: unit (builder): a publish heard now answers its time.
|
||||
|
||||
### The build modules (seats `node-build-go`, `node-build-node`, `node-build-image`)
|
||||
|
||||
- §799 **A fetch or a publish that meets its holder away is a transport fault.** (ADR 0668 §1 and ADR 0664 §1 (insights of 2026-11-21,
|
||||
accepted); ADR 0664 §2; H-A-301, H-A-341 (8), H-A-342 (1); row 178) A build or check step whose fetch of its source meets a connection fault or a 401 or 5xx
|
||||
answer of the forge, or whose publish to a registry seat meets no responders or a bundle that exited, ends its run
|
||||
`again`, never the step (ADR 0664 §1), with no seat call to learn why; the tool runner settles the ask with a
|
||||
delay of 15 s after the first run and 60 s after the second (`again-delays`, a setting of each build module, default
|
||||
"15s,60s", so three runs span the one-minute absence met on 2026-11-21), and a third run's fault ends the step failed
|
||||
with the why `fetch: <words>` or `publish: <words>`, whichever met the fault (ADR 0664 §2), which the builder and the runner say apart from a build's failure. Built
|
||||
in H2 in the build seats' conformance kit (ADR 0664 §6) and the three build modules. How it is checked: the
|
||||
conformance kit holds a fetch met by a 401 and a publish met by no responders to `again`, and three such runs to the step failed
|
||||
with `fetch:` and with `publish:` respectively.
|
||||
- §800 **A test that cannot run says NOT RUN; a starved setup runs again; a needed npm tree is installed.** (H-A-294,
|
||||
H-A-327, H-A-338 (3), H-A-339 (6), H-A-340 (6), H-A-341 (7); rows 168, 170, 194) A step's summary counts `not-run`
|
||||
apart from passed and failed, with each test's name and reason; a level whose tests passed or did not run passes,
|
||||
its not-run listed; a test lacking tooling its step does not give says NOT RUN (H-A-294). A Go artifact may declare
|
||||
`check-needs` with the value `node-modules` in its manifest: the runner then asks the seat `node-build-node` a step of
|
||||
the new accepted kind `install` (input: the module's package lock at the commit) before the integration level; the
|
||||
Node build module installs from the npm registry seat with an integrity-checked install (`npm ci`) and no install
|
||||
scripts, keeps the tree as an archive in its `outputs` under the lock's digest (§820), and the step's end carries the
|
||||
archive object's name (ADR 0666 §16), which the integration ask names and the Go build module unpacks into the
|
||||
workspace. Each level gets its bound in the environment as `MESH_TEST_LEVEL_BOUND`, and mesh-sdk's test helpers take a
|
||||
setup bound of half of it, never a value in the test; a whole-module test whose setup wait on the bus passes that
|
||||
bound ends its run `again` by §799's delays, and a third such run ends the step could-not-run "the bus did not answer
|
||||
in setup within <bound> under load", never failed. An assertion that fails is never `again` and never NOT RUN. Fate:
|
||||
the Node build module's and the recovery module's setup bounds in code go. Built in H2 in mesh-sdk (the helpers, the
|
||||
catalog's `check-needs`), the build seats' definitions, the three build modules and those two modules' tests. How it
|
||||
is checked: whole (Go build module): the forge module's whole-seat test runs with its npm tree; a test whose setup
|
||||
is starved runs again and ends could-not-run at the third run; unit (Node build module): an install runs no script.
|
||||
- §801 **Every build seat says what it takes and what runs.** (ADR 0525 §4, §10; H-A-302 (4), H-A-320 (3); rows 99,
|
||||
179, 189) Each build seat's verb `current` answers, per holder, whether it takes check asks and why not (`paused`,
|
||||
`capacity 0`, `unhealthy`, with since when), and every ask it runs, whoever asked it (the builder's delivery asks
|
||||
included); the build modules' steps read tools answer the steps state they keep, never empty while steps run;
|
||||
`build_current` (the builder's tool) asks every holder and answers them together. Built in H2 in the three build
|
||||
modules and the builder. How it is checked: whole (Go build module): an ask the builder put is listed by `current`
|
||||
while it runs; a paused holder answers `paused`.
|
||||
|
||||
### The indexer (seat `mesh-catalog`'s holder; mesh-delivery-indexer)
|
||||
|
||||
- §802 **A module moves only when its own build source changes.** (ADR 0267 §1, §2; ADR 0499 §2; H-A-202, H-A-298 (1),
|
||||
H-A-338 (9); row 175) A module's fingerprint tree input is ADR 0499 §2's: the hash over its manifest and its named
|
||||
paths where every artifact names `paths`, else its directory's tree object at the commit, with the directories of
|
||||
its same-repository requirements taken in as H-A-202 has it; never the repository's commit. A commit outside them
|
||||
moves nothing. The indexer and the builder take the new fingerprint function in one release. Fate: the fingerprint
|
||||
over the repository's commit goes; every module's fingerprint changes once, at H2's delivery (§818). Built in H2 in
|
||||
the indexer, the builder and mesh-sdk's one fingerprint function (ADR 0499 §2). How it is checked: whole (indexer): a
|
||||
commit touching two test files of two modules in a repository of 36 moves those two and their importers alone.
|
||||
- §803 **A take-in says what it waits on.** (H-A-298 (2); row 175) A take-in waiting longer than a minute on another
|
||||
part (the seat `git`'s listing, a package's versions, a registry) writes one journal line naming the part, the verb
|
||||
and since when, and keeps it on its value in `takeins` as `waiting-on` (`part`, `verb`, `since`), read with
|
||||
`indexer_pending`; past five minutes it raises the finding `take-in-waiting` (scope merge, id the source revision),
|
||||
cleared when the wait ends. Built in H2. How it is checked: unit: a listing answered after 70 s writes one line and
|
||||
`waiting-on`; one answered after six minutes raises `take-in-waiting`, which clears at the answer.
|
||||
- §804 **A dry run keeps to its own scratch state.** (H-A-297, H-A-339 (7), (8); row 174) A dry run of a branch's
|
||||
take-in writes only to the indexer's state `dry-runs` (§820), keys `<branch>.<call>.<kind>.<name>`, deleted by the
|
||||
indexer when the dry run answers and every one at the indexer's start, and leaves the trunk's packages state
|
||||
untouched; `indexer_dry_runs` reads the state. Built in H2. How it is checked: whole (indexer): a branch dry run
|
||||
leaves the trunk's packages state byte for byte as before, and a start finds `dry-runs` empty.
|
||||
- §805 **A release re-pins once, at its reservation.** (H-A-204, H-A-283's owed, H-A-338 (4); row 153) The builder says
|
||||
`version-reserved` on the seat `mesh-builds`' family (`module`, `artifact`, `path`, `version`, `fingerprint`,
|
||||
`revision`) when it reserves a package's number; the seat's definition declares the event, so only its holder
|
||||
publishes it, and the indexer consumes it. The indexer re-pins every importer once at that event, and a
|
||||
`package-published` of the pinned version keeps no revision; a withdrawn reservation re-pins to the series' newest
|
||||
released version. Test steps still wait for the publish (H-A-206). Fate: the re-pin per publish goes. Built in H2 in
|
||||
mesh-delivery (contracts, the builder, the indexer). How it is checked: whole (indexer): a release of a module
|
||||
importing twenty packages of its own pipeline keeps one re-pin revision.
|
||||
- §806 **The registrations are read in one call.** (row 140) `indexer_registrations` answers the registrations state
|
||||
with `module` and `repository` filters applied while reading, at most 768 KB, with `capped` and the cursor of §779.
|
||||
Built in H2. How it is checked: unit.
|
||||
|
||||
### The catalog's checks
|
||||
|
||||
- §814 **The validator reads the mesh's seat list, counts only new problems, and refuses an uncapped store.**
|
||||
(H-A-299 (2), H-A-329, H-A-338 (10), H-A-339 (1), (8); rows 196, 198) The seat `mesh-catalog` gains the read verb
|
||||
`seat-list` answering the seat list the mesh holds as one object in the indexer's objects, by digest (`digest`,
|
||||
`size`, `object`), which the manifest validator program takes by address, so a run by hand reads what the live
|
||||
validate reads. The step `validate` counts, for a module it touches, only the problems new against its before case
|
||||
(`causedProblems`); `indexer_validate_before` (pipeline, module) answers the before case's problems it did not count.
|
||||
The validator refuses a delivery module's state, log or objects entry with no cap (§812); a delivery module is one
|
||||
whose manifest claims a seat of the delivery system, which the validator reads from the claims; a foundation part's
|
||||
old-section entry declares its cap in that section (H-A-229, ADR 0595 §10) and is never refused for lacking the new
|
||||
form. Built in H2 in the indexer, the manifest validator and mesh-sdk's catalog. How it is checked: whole (indexer): a
|
||||
run by hand against `seat-list` gives the live validate's verdicts for the builder's and the runner's manifests; unit
|
||||
(validator): a problem the before case holds is not counted; an uncapped entry of a delivery module is refused, a
|
||||
foundation part's capped old-section entry is not.
|
||||
- §819 **Every module H2 touches ends with fewer tests than it starts with.** (ADR 0548; the test budget, 50
|
||||
integration and 500 unit per module; H-A-340 (8); rows 115 and the row of 18:40 on the budget) Each module a pull
|
||||
request of H2 changes carries fewer tests at H2's end than at its start, counted as the build node counts them
|
||||
(subtests included) and reported by each pull request's check. The starting counts: by the build node at H1's end,
|
||||
the indexer 538 integration, the assigner 64 integration, the node-engine 1,716 unit, the NFS server module 51
|
||||
integration and the package manager module 121 integration; by top-level test functions on the trunks of
|
||||
2026-11-21 (subtests not counted), the indexer 6 integration and 170 unit, the assigner 9 and 87, the runner 4 and
|
||||
105, the builder 18 and 167, the node-engine 11 and 1,716. The NFS server and package manager modules shrink to 50
|
||||
integration tests in H2. How it is checked: the check's counts per module in each pull request, read by its review
|
||||
against the starting count.
|
||||
|
||||
### hq, a watched source with no module
|
||||
|
||||
- §815 **A repository with no module registers as a source alone, and merges like any other.** (ADR 0527 §1; ADR 0666
|
||||
§11, §18; ADR 0682 §1, §3; H-A-332, H-A-334 (1), H-A-338 (2), H-A-339 (3); the operator, 2026-11-21 21:48: no merge
|
||||
is put to them; rows 176, 177) A registration of the seat `mesh-catalog` takes a source-only form: `repository`, its
|
||||
watched `branch`, `policy`, and `check`, which names a build seat and a step kind (for hq: `node-build-go`, `unit`,
|
||||
at the repository's root), never a free command; it names no module. The indexer keeps it with the registrations,
|
||||
takes a move of that branch in as a take-in with no movers, and refuses a source-only registration whose repository
|
||||
holds a manifest. The pipeline runner's run on request of a pull request's head (ADR 0666 §18) runs that one step on
|
||||
the named seat, in its sandbox, as a pipeline step; `merge-pull` judges the head by the registration's `policy` from
|
||||
the runner's step events, as it judges a module's (ADR 0666 §11), and merges it. The forge bridge says `head-moved`
|
||||
for the branch and the gate watches it as any watched branch (`head-untaken`, ADR 0682 §3); the gate's record of
|
||||
such a merge ends `nothing to deliver`. This closes a gap: ADR 0527 §1 has hq's checks run by the Go build module as
|
||||
any repository's tests, but with the checker gone (design 47 G) nothing asked that run, and hq's pull requests were
|
||||
merged by the operator at the forge with no mesh run. Fate: those merges at the forge end at H2's delivery; hq is
|
||||
registered so once through the seat `mesh-catalog`'s verb `register`, the operator's channel saying it as a
|
||||
registration change. Built in H2 in the indexer (the registration's source-only form and the seat's definition), the
|
||||
runner, the forge module's `merge-pull` and the gate. How it is checked: whole (indexer, runner and gate): a
|
||||
source-only registration's pull request is run on request, merged by one merge call, raises no `head-untaken` and
|
||||
ends its record `nothing to deliver`; an hq pull request whose Go checks fail is refused by `merge-pull`, naming the
|
||||
failed step.
|
||||
|
||||
### How H2 is proven
|
||||
|
||||
- §818 **H2's own delivery moves every module once, before the proofs.** (ADR 0499 §2; ADR 0682 §6; H-A-338 (9),
|
||||
H-A-340 (5)) H2's merges are delivered by their pipelines; once the indexer and the builder of §802 run, the
|
||||
indexer's recompute at its start (`call-kind` recompute, H-A-217) keeps one catalog revision in which every module's
|
||||
fingerprint moved, and one pipeline carries every module as a mover: about 193 movers (the module graph at trunk
|
||||
revision 512). A build whose content is unchanged is reused, not built again, and a node-engine restarts nothing
|
||||
whose composition is unchanged. Its time is read from its `pipeline-ended` phases and quoted in the milestone's
|
||||
report; a guess, said as one, is about 45 minutes, scaled from row 182's 126 movers in 29 minutes. It is held to no
|
||||
delivery budget (it is not a change's delivery), only to `stalled-bound`. The proofs run after it ends passed. How it
|
||||
is checked: the lead reads the pipeline's movers (`runner_movers`) and the node-engines' restarts during it.
|
||||
- §816 **Proof 1: a one-line change to a delivery part runs everywhere within ten minutes, by its pipeline alone.**
|
||||
(ADR 0282 §1; ADR 0682 §1, §6, §8; plan section 5, step 7; H-A-340 (10)) A one-line change (a comment) in one module
|
||||
of the delivery system with lint, unit and composition steps, merged through one merge call (`merge-pull`), runs at
|
||||
its new version on every present placing machine, reported healthy, within ten minutes of its `merge-called` (a core
|
||||
module's budget). It is read from the gate's ended record (`gate_record`): `class` core, `delivery-time` under ten
|
||||
minutes, no `over-budget` raised for it, quoted with its phases (§785); and from the hand-act log, empty for every
|
||||
delivery part from `merge-called` to the last `running`; no other pipeline held the slot meanwhile. No hand act
|
||||
touches the delivery system during it: no hand pack, no held put, no `runner_cancel`, `runner_end_again`, rerun,
|
||||
`builder_build_again` or `builder_publish_again`, and no start, stop or restart through the seat
|
||||
`node-service-manager`; the only restart is the moved module's own, by its node-engine.
|
||||
- §817 **Proof 2: a package and its importer in two repositories, one merge call, within ten minutes.** (ADR 0282 §1;
|
||||
ADR 0682 §1, §2, §4; ADR 0573 §2; H-A-340 (10)) One merge call names two pull requests: a one-line change to a
|
||||
package of the delivery repository whose importers are at most three, one of them the gate in the catalog repository
|
||||
(read with the indexer's `indexer_package_users`), and a one-line change to the gate. The gate names one source
|
||||
revision for both, one pipeline publishes the package and builds the gate against it, and every mover runs at its
|
||||
new version on every present placing machine within ten minutes of `merge-called`, read and bound as §816, with no
|
||||
hand act and no restart as §816 says. How it is checked for both: the lead reads each with the tools named and
|
||||
quotes the times in the milestone's report; a proof over its ten minutes or with a hand act is not shown, and its
|
||||
cause is fixed in its repository and delivered before it is run again.
|
||||
|
||||
## Design questions
|
||||
|
||||
Found by H2's prepare (`mesh-preparer`, 2026-11-21 22:40 CET), for the lead's answers (playbook 07, step 0b). The code was
|
||||
read at `origin/main`: `mesh-delivery` `7e597a623eb2`, `mesh-catalog` `553bfb0ccf7c`, `mesh-host` `637cfb1fd044`,
|
||||
`mesh-sdk` `bdc5cff0d63d`, `mesh-contracts` `87eab81be134`, `mesh-tools` `02675a43eaf8`, `mesh-networking`
|
||||
`19a04dfc602a` (a sibling for the build). The build maps are in [H2-build-maps](H2-build-maps/). Each recommendation is
|
||||
the preparer's, said as one.
|
||||
|
||||
- **DQ-1** (§777) The line names the accepted kinds `build` on `mesh-builds` and `validate` and `compose` on `mesh-wants`;
|
||||
both seats accept one kind, `step`, today (`mesh-delivery` `seats/mesh-builds/seat.json`, `seats/mesh-wants/seat.json`
|
||||
`accepts`; the runner puts every step on `accept.step`, `cmd/mesh-delivery-pipeline/asks.go:27`). Left to the builder:
|
||||
whether the kinds are renamed and split. Recommendation: keep the one kind `step` on each seat and read the line's
|
||||
kinds as the step the ask names, so no subject and no reader changes.
|
||||
answered: H-A-349 DQ-1.
|
||||
- **DQ-2** (§777) The line rebuilds the `mesh-builds` stream empty through `nats_recreate`; the `mesh-wants` stream
|
||||
`SEAT_MESH_WANTS` holds 1,598 messages and 0 consumers as well (live, `nats.nats_streams`, 22:25 CET), and `mesh-builds`'
|
||||
1,558 now. Left: the fate of `SEAT_MESH_WANTS`' messages. Recommendation: rebuild both empty on the same warrant, before
|
||||
the new builder and the new assigner start.
|
||||
answered: H-A-349 DQ-2.
|
||||
- **DQ-3** (§782) The line names "mesh-sdk's wrappers around one bus handle" without naming them; mesh-sdk holds several
|
||||
(`process.Conn`'s state and stream calls, `stdio`'s `BusState` through the runtime, `views`). Recommendation: name the
|
||||
wrapper row 137 met twice, by package and type, in the line.
|
||||
answered: H-A-349 DQ-3.
|
||||
- **DQ-4** (§777, §778) The runner's second put under `AgainID` with its bound key `ask2.` serves the build seats today
|
||||
(`internal/pipeline/asks.go:27-60`, `:134-160`); the line says the runner puts again only on a transport fault but gives
|
||||
`AgainID` and `ask2.` no fate. Recommendation: both go for every seat, by §777's rule.
|
||||
answered: H-A-349 DQ-4.
|
||||
- **DQ-5** (§783, §820) Which delivery modules are foundation parts (ADR 0619 §1, ADR 0666 §4) that declare their stores
|
||||
in the old section, and which ask in `requires` by template, is not said; today the runner, the builder, the indexer and
|
||||
the assigner use the old sections (`mesh-delivery-pipeline/module.json:205-240`, `mesh-delivery-builder/module.json:120-140`)
|
||||
and the bridge uses `requires` (`mesh-delivery-forge-bridge/module.json:40-45`). Recommendation: the line lists the
|
||||
foundation parts by module.
|
||||
answered: H-A-349 DQ-5.
|
||||
- **DQ-6** (§793) The work queue `publishes` (§820: work queue, 64 MiB, 7 days) names its subject and consumers per
|
||||
holder and class, but not whether the consumers are declared in the builder's `requires` or derived by the broker, and
|
||||
the move's message id `<holder>.<module>.<version>` names no class while `builder_publish_first` puts an item again as
|
||||
`live` within the duplicates window. Recommendation: the builder declares the stream and its consumers in `requires`,
|
||||
and `builder_publish_first` puts under an id carrying the class.
|
||||
answered: H-A-349 DQ-6.
|
||||
- **DQ-7** (§808, H-A-345) The vault's seat serves no write of a module's own secret, and its read `own` answers only the
|
||||
node-engine of a machine, sealed to the machine's key, so a forge module process can neither write nor read its token
|
||||
through `own` (`mesh-contracts` `identity-and-access/seats/mesh-vault/seat.json`, verbs `own`, `get`, `licence-put`;
|
||||
live `mesh-vault.own`'s description, 22:27 CET). The write verb is a gap of this milestone (H-A-345); the read is a gap
|
||||
too. Recommendation: add to the vault's seat a two-step sealed write of a module's own secret modelled on `licence-put`
|
||||
(the module named by the caller's account, its newest generation kept), and read the token through `get`, sealed to the
|
||||
process's key; built in `mesh-catalog` `modules/mesh-vault` and `mesh-contracts`, before the forge module's §808 work.
|
||||
answered: H-A-349 DQ-7.
|
||||
- **DQ-8** (§802) A mesh Go package that no module the indexer holds has published enters the fingerprint by the commit the
|
||||
gate's source names for its repository (`mesh-delivery` `internal/index/form.go:113-125`, design 47 G A-365), and the
|
||||
import form's versions are a holding module's published commit (`form.go:30-33`); the line does not say what such a
|
||||
package enters by under ADR 0499 §2. Recommendation: a package of the module's own repository enters by its directory's
|
||||
tree, as a directory replace does already (`form.go:39-41`); another repository's unpublished package leaves the module
|
||||
without a fingerprint until it is published, said as today's `NoPackageVersion`.
|
||||
answered: H-A-349 DQ-8.
|
||||
- **DQ-9** (§815) The source-only registration has no module, while the state `registrations` is keyed `<module>` and a
|
||||
registration requires `module`, `origin`, `path` and `branches` (`seats/mesh-catalog/seat.json` `defs.Registration`); the
|
||||
line names `repository` and one `branch`. Left: its key, its field names against `origin` and `branches`, and its history
|
||||
key. Recommendation: key `source.<owner>.<name>` in the same states, fields `origin`, `branches` (one), `policy`,
|
||||
`check`, so readers of registrations read one form.
|
||||
answered: H-A-349 DQ-9.
|
||||
- **DQ-10** (§814, §820) The seat list as one object "in the indexer's objects, by digest" is a store §820's table does not
|
||||
hold: its objects entry, cap, key life and deleter. Recommendation: the indexer's objects `seat-lists`, 64 MiB, one object
|
||||
per digest, the indexer deleting every object but the newest two at each new list.
|
||||
answered: H-A-349 DQ-10.
|
||||
- **DQ-11** (§813 (4)) The node-engine marks each rule it writes `mesh-host <id> <digest>` and recognises its own rules and
|
||||
stale ones by that mark (`mesh-host` `internal/firewall/firewall.go:415-427`, `:782`); the line's comment
|
||||
`derived <module> <listen> scope <…>` gives the mark no fate. Recommendation: the scope words follow the mark in the one
|
||||
comment, so the reconciling keeps reading the mark.
|
||||
answered: H-A-349 DQ-11.
|
||||
- **DQ-12** (§813 (1)) "A composition key" is not named: the state and key the holder of `mesh-wants` writes by
|
||||
compare-and-set (its `wants` `want.<node>.<module>`, `compositions` `<group>.<heads>`, or the node-engine's composed
|
||||
bucket), and `run`'s form: the node-engine contract already carries `run` as a string (`mesh-contracts`
|
||||
`go/seats/nodeengine/contract.go:1764`) while the line says a pipeline sequence. Recommendation: name the state and key,
|
||||
and keep the existing field `run` holding the sequence as a decimal string, so no form is raised.
|
||||
answered: H-A-349 DQ-12.
|
||||
- **DQ-12b** (§813 (3)) `engine_composition_diff` is "the node-engine's tool", but the node-engine serves only the seat
|
||||
`node-engine`'s verbs and has no tools bundle (`mesh-host`: no `engine_` tool name in any file; live `ace/node-engine.*`
|
||||
are seat verbs). Recommendation: a read verb `composition-diff` on the seat `node-engine`, beside `composition`.
|
||||
answered: H-A-349 DQ-12b.
|
||||
- **DQ-13** (§821) "The re-pin's" event is not named, and the runner's seat declares none for a re-pin today
|
||||
(`seats/mesh-pipeline-runner/seat.json` events). Recommendation: the line names it (`re-pinned`, carrying the pipeline,
|
||||
the mover and the revision).
|
||||
answered: H-A-349 DQ-13.
|
||||
- **DQ-14** (§819) The starting counts by `go test -list` without and with `-tags integration` (top-level functions, 22:30
|
||||
CET) differ from the line's: the indexer 167 unit and 6 integration (line: 170 and 6), the assigner 86 and 9 (87 and 9),
|
||||
the node-engine 1,715 and 11 (1,716 and 11); the runner 105 and 4 and the builder 167 and 18 agree. By the tag the NFS
|
||||
server module holds 0 integration and 51 unit, the package manager module 3 and 118, where the line's 51 and 121 are the
|
||||
build node's counts, which take untagged tests in. Recommendation: each pull request's check gives the starting count
|
||||
at its base, and the line keeps its figures as a guess said as one.
|
||||
answered: H-A-349 DQ-14.
|
||||
- **DQ-15** (§776) The forge module is TypeScript; the line places `away` in mesh-sdk's seat error answer without saying
|
||||
whether mesh-sdk's TypeScript seat helpers carry it. Recommendation: they do, in the same commit.
|
||||
answered: H-A-349 DQ-15.
|
||||
- **DQ-16** (§810) `class` is `core` "when it moves a core module of ADR 0282 §1"; the gate holds no list or field naming a
|
||||
module's class (`grep -rn -i "core\|class" --include='*.go' mesh-catalog/modules/mesh-delivery-gate/cmd` finds none).
|
||||
Left: where the gate reads it. Recommendation: the gate reads it from a setting `core-modules` (a list, default the
|
||||
delivery system's modules and the node-engine), so the self-check's probe and the gate read one list.
|
||||
answered: H-A-349 DQ-16.
|
||||
|
||||
## Design meets code
|
||||
|
||||
Each entry: the design line, the code (at the commits named above), which of the three it is, and the preparer's
|
||||
recommendation, said as one.
|
||||
|
||||
- **DMC-1** (§777) *A form the code cannot take.* The seat definition's `accepts` carries no `max-age`, `max-msgs`, ack wait,
|
||||
in-progress, max ack pending, max deliveries or duplicates window; the streams and the shared worker are derived by the
|
||||
grants part with their own values (ack wait 60 s, max deliver 5, retain 7 days; `mesh-delivery`
|
||||
`modules/mesh-grants/internal/buscompose/derived.go:86-110`, `:343-358`), and mesh-sdk keeps a second `buscompose`
|
||||
(`mesh-sdk` `go/buscompose/nats.go:96-98`). Live max age is 168 hours. Recommendation: the seat definition's accepts gain
|
||||
these settings, read by the one derivation in mesh-sdk's `buscompose`, which the grants part takes.
|
||||
answered: H-A-350 DMC-1.
|
||||
- **DMC-2** (§776) *A part the line assumes built that is not.* mesh-sdk has no seat error answer: error kinds are each
|
||||
seat's own (`git`'s `ErrorKind`: `refused`, `not-found`, `failed`, `seats/git/seat.json`; `mesh-catalog`
|
||||
`modules/gitea/seat.ts:71`). Recommendation: add `away` to the error kinds of every seat the delivery parts call
|
||||
(`git` first), and mesh-sdk's kept call reads `away` as a transport fault by the answer's `error-kind`.
|
||||
answered: H-A-350 DMC-2.
|
||||
- **DMC-3** (§796) *A form the code cannot take.* The `tags` answer is a list of strings (`seats/git/seat.json` `tags`);
|
||||
`commit` per tag makes each item an object, a form raised (§780) for every reader (`mesh-delivery-builder`
|
||||
`internal/versions/claim.go:213`, `mesh-sdk` `seatlist/bootstrap/git.json`). Recommendation: items become `{tag, commit}`
|
||||
with the seat's `form` 2, read tolerantly by §780.
|
||||
answered: H-A-350 DMC-3.
|
||||
- **DMC-4** (§780) *A part placed where it is not.* The seat generator is `mesh-delivery`'s
|
||||
`modules/mesh-delivery-sdk/seatgen`, not mesh-sdk's; mesh-sdk's `seatdef` reads definitions only. Recommendation: build the
|
||||
tolerant decoders and the `form` check in `seatgen`, and regenerate every seat in `mesh-delivery` and `mesh-contracts`.
|
||||
answered: H-A-350 DMC-4.
|
||||
- **DMC-5** (§802) *A part placed where it is not, and a form already built.* The one fingerprint function is the
|
||||
indexer's (`mesh-delivery-indexer/internal/fingerprint/fingerprint.go:1-5`: "the indexer's own, and nobody else's"; the
|
||||
builder reads what the indexer writes), not mesh-sdk's; and its tree input is already the directory's tree or the named
|
||||
paths (`internal/index/inputs.go:97-118`); the commit enters through DQ-8's packages. Recommendation: build §802 in the
|
||||
indexer's `fingerprint` and `form.go`, the builder taking nothing new but the release in one group.
|
||||
answered: H-A-350 DMC-5.
|
||||
- **DMC-6** (§800) *A rule in code the line breaks.* `check-needs` is a marker file in a package's directory, kept "not a
|
||||
manifest field" on purpose (`mesh-catalog` `modules/mesh-build-go/cmd/mesh-build-go/digest.go:59-66`), read by
|
||||
`mesh-delivery-sdk` `steprun.AskNeeds`; the line makes it a manifest field of a Go artifact. Recommendation: the line
|
||||
holds: the manifest field replaces the marker file, whose fate (it goes, its readers moved) the line states.
|
||||
answered: H-A-350 DMC-6.
|
||||
- **DMC-7** (§799) *A part placed where it is not.* The delay before a run ended `again` is offered again is the tool
|
||||
runner's `WorkBackoff` (5 s doubling to 10 minutes, `mesh-tools` `internal/bus/seat.go:71-79`, `:315`) or a bundle's own
|
||||
`NakWithDelay` (`seat_pull.go:193`); the line says "the tool runner settles the ask with a delay of 15 s ... 60 s", a
|
||||
build module's setting, built in the kit and the build modules. Recommendation: the build module passes its
|
||||
`again-delays` with its `again` (the bundle's delay), so the tool runner changes nothing; mesh-tools' T3 then drops.
|
||||
answered: H-A-350 DMC-7.
|
||||
- **DMC-8** (§786, §789, §816) *Parts assumed built that are not.* The runner has no tools `runner_show`, `runner_cancel`
|
||||
or `runner_movers` (`mesh-delivery-pipeline/module.json`, 14 tools; the verbs `show` and `cancel` exist on the seat).
|
||||
Recommendation: `runner_show` and `runner_movers` are built in R8 as the tools table says; §816's `runner_cancel` reads as
|
||||
the seat verb `cancel`.
|
||||
answered: H-A-350 DMC-8.
|
||||
- **DMC-9** (§814) *A part placed where it is not.* The validate step and `causedProblems` are the assigner's
|
||||
(`mesh-delivery-assigner/cmd/mesh-delivery-assigner/validatestep.go:124`, `:203-230`), which counts every problem of a
|
||||
touched module and only new ones of the rest; the line builds the counting in the indexer and names
|
||||
`indexer_validate_before`. Recommendation: change `causedProblems` in the assigner and name the tool
|
||||
`assigner_validate_before`.
|
||||
answered: H-A-350 DMC-9.
|
||||
- **DMC-10** (§813 (7)) *A part named that is not.* No seat `artifact-store`: the sweep holds `mesh-artifact-sweep`
|
||||
(`artifact-store-tools`), the registry `mesh-artifact-store` and `oci-artifact-registry` (`distribution`); the registry's
|
||||
`list` takes `name`, not `module` (`seats/oci-artifact-registry/seat.json`). Recommendation: read "the seat
|
||||
`mesh-artifact-sweep`'s holder", and `list` takes `module` beside `name`.
|
||||
answered: H-A-350 DMC-10.
|
||||
- **DMC-11** (§813 (5)) *A part assumed built that is not.* No tool `nats_consumers`: the bus module has `nats_consumer` (one)
|
||||
and `nats_backlog` (`mesh-catalog` `modules/nats/module.json`). Recommendation: `nats_consumers` is a new tool listing
|
||||
consumers with the two sorts.
|
||||
answered: H-A-350 DMC-11.
|
||||
- **DMC-12** (§781, §813 (4)) *Parts assumed built that are not.* The node-engine seat has no `converged` and no verb with
|
||||
`timeout` ("built in H1" in the line; `mesh-contracts` `seats/node-engine/seat.json`); the packet filter's holder
|
||||
(`nftables`, TypeScript) serves `rules`, `reload`, `remove` and has no `allow`, asks no `converged` and holds no named
|
||||
10 s (`mesh-catalog` `modules/nftables/client.ts`, `tools/index.ts`). Recommendation: the line says whether H2 builds
|
||||
`converged` with its `timeout` and `allow`, or the clauses about them leave H2.
|
||||
answered: H-A-350 DMC-12.
|
||||
- **DMC-13** (§781) *A part assumed built that is not.* mesh-sdk has no settings reader: each module reads its
|
||||
`${config:<key>}` files by names of its own (`mesh-delivery-pipeline/cmd/mesh-delivery-pipeline/askbounds.go:20-35`).
|
||||
Recommendation: a reader in mesh-sdk takes a setting by its key from the words the node-engine composes, in a process
|
||||
and in a bundle alike, and the runner's own readers move to it.
|
||||
answered: H-A-350 DMC-13.
|
||||
- **DMC-14** (§812) *A part assumed built that is not.* A state write answers its revision only (`mesh-sdk` `go/state.go:177`,
|
||||
`:190`; `mesh-tools` `internal/bus/state.go:425`), and a publish's acknowledgement carries the stream and sequence, no
|
||||
fill. Recommendation: the runtime's write answer carries the entry's `Fill` (`buscalls.Fill` exists), which the prune
|
||||
helper judges.
|
||||
answered: H-A-350 DMC-14.
|
||||
- **DMC-15** (§778) *A part assumed built that is not.* "Drops its ask through the seat's `drop`": `mesh-builds` (verbs
|
||||
`reserved`, `published`) and `mesh-wants` declare no `drop`; only the build-step part has one. Recommendation: D1 adds a
|
||||
`drop` act to both seats, its holder ending the ask as the build seats' `drop` does.
|
||||
answered: H-A-350 DMC-15.
|
||||
- **DMC-16** (§791, §801) *A form the code cannot take as written.* The build-step part already has `output` (the whole
|
||||
answer in chunks by `ask` and `call`) and `current` (the steps, capacity, paused) in other forms
|
||||
(`mesh-delivery-contracts/parts/build-step.json`). Recommendation: the line's forms replace them with the part's `form`
|
||||
raised, the runner's tool their one reader.
|
||||
answered: H-A-350 DMC-16.
|
||||
@@ -22,10 +22,7 @@ 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. 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
|
||||
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
|
||||
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