Merge pull request 'Design 47 G: what is owed once G is delivered' (#613) from design/47-G-after-delivery into main

This commit was merged in pull request #613.
This commit is contained in:
2026-11-16 08:46:19 +00:00
@@ -0,0 +1,105 @@
---
layer: to-be
status: in-progress
design: 47
milestone: G
updated: 2026-11-16
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.
## 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.