Merge pull request 'Design 47: ADR 0564 homes health (L4), and milestones L5 to L7 give the controller's other jobs their homes before L3's lease write' (#488) from docs/47-adr-0564 into main

2026-10-28 09:46:31 +00:00
parent 32da464794 3c2d5af436
commit 2ea3368b76
2 changed files with 30 additions and 8 deletions
@@ -565,7 +565,8 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
  artifacts), the **gate** (merges a group and moves the source revision; *gate part* where it could be read
  as another gate, see [Homonyms](#homonyms)), the **teller** (the operator's phone, and the only writer of an
  ask's answer), the **assigner** (writes each node's wants by its seven rules, ADR 0539 §6), the **node
-  agent** (the node-engine's own process, applying its wants), the **watchman** (presence and pulses) and the
+  agent** (the node-engine's own process, applying its wants), the **watchman** (presence and pulses; it also holds the
  Health seat `mesh-watchdogs`, whose watchdogs are pulses, and keeps the dead letters, ADR 0564 §4, §5) and the
  **status view** (`mesh-delivery-cli` and a web view, writing only its answers to asks and saying the events
  `delivered`, `moving`, `settled` and `stuck`, derived from the keys). The reviewer is the review
  agent's session, not a part. Built over releases 1 to 6 of ADR 0429.
@@ -633,7 +634,7 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
 **Purpose.** To notice what is wrong with the mesh, say it once, repair what may be repaired unattended,
 and record what was done by hand. **Recorded by** the controller's condition store.
 **Upstream of** Delivery (the first-node gate) and Operator and conversation (a condition
-becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
+becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283, 0564.
 **Uses:** node, module, node-engine (Core).
 - **health** — a module's or a core component's statement of how it is alive and ready, which the
@@ -647,7 +648,14 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
  reads it as *waits for a person*
  (ADR 0283).
 - **probe** — one look at one thing's health, run by whoever owns the verdict; what a probe returns is a
-  **finding**, before it becomes a condition.
+  **finding**, before it becomes a condition. A finding is kept as a key `<scope>.<id>.<kind>` in its observer's
  bucket `findings` until it is no longer observed (ADR 0564 §2).
 - **observer** — a part that writes findings for the condition keeper: the watchman, the self-check and the
  healers (ADR 0564 §2). An observer never writes a condition.
 - **condition keeper** — the module mesh-conditions, holder of the seat `mesh-conditions`: the one writer of the
  open conditions, raising each from an observer's finding and clearing it when the finding goes, and saying
  `condition-raised`, `condition-changed` and `condition-cleared` (ADR 0564 §2, §3). The controller keeps them
  until the take-over.
 - **signal** and **watchdog** — something that must keep happening (a heartbeat, a report after a send),
  and the watcher that raises a condition when it stops (to-be 45 §3).
 - **condition** — one open fact about something the mesh owns that is wrong, with a key and a severity;
@@ -655,8 +663,8 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
  (ADR 0231).
  What a wrapped dashboard raises is its own; the mesh's notion is a condition.
  *Not:* ~~alert~~ (hq)
- **self-check** — the controller's own examination of the mesh, run on demand and on a schedule
+- **self-check** — the mesh's own examination of itself, run on demand and on a schedule (to-be 45 §4), held
-  (to-be 45 §4). Its verb is `doctor`, an identifier; prose says self-check.
+  by the seat `mesh-self-check` (ADR 0564 §6); the controller runs it until that is delivered. Its verb is `doctor`, an identifier; prose says self-check.
  *Not:* ~~doctor~~ (hq)
 - **healer** — a registered response to one condition kind: its **repair** (the ordinary path again),
  its **budget**, its back-off and its brake. A healer may not withdraw, delete or recreate data.
@@ -667,6 +675,9 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
  operator's decision (ADR 0259).
  Not a drill: nothing is broken.
 - **hand-act** — a repair a person made by hand, recorded so the mesh knows it happened.
 - **take-over** — the operator's approved switch of a job from the controller to the part that replaces it, with a
  way back until the lease write: for the bus's user list, the grants part's list becomes the one loaded (ADR 0547
  §8); for conditions, the condition keeper's events become the ones the router hears (ADR 0564 §9).
 - **witness** — what rolls a core component back when its new build does not become healthy: never the
  component itself (to-be 45 §8).
@@ -1032,7 +1043,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
 | check | a pull request's two statuses, until release 4 of ADR 0429 | **merge check**, **repository check**; from release 4, `mesh/check` | Delivery |
 | | whether the machines a change touches still compose, the assigner's | **composition check** | Delivery |
 | | a delivery group's verdict | **composed check** | Delivery |
-| | the controller's own examination | **self-check** | Health and repair |
+| | the mesh's own examination | **self-check** | Health and repair |
 | | a file in `00-META/checks/` | **hq check** | The record |
 | agent | a coding agent | **agent** | Operator and conversation |
 | | the holder of the seat `node-build-agent` until R4g; from release 4 of ADR 0429 the part `mesh-delivery-builder` | **builder** (the part); **build module** (what builds) | Delivery |
@@ -2,8 +2,9 @@
 layer: to-be
 status: in-progress
 code: [mesh-controller, mesh-catalog modules/mesh-delivery-gate, mesh-delivery, mesh-host, mesh-sdk, mesh-vault, hq 00-META/checks]
-updated: 2026-10-27
+updated: 2026-10-28
 decisions:
  - "ADR 0564"
  - "ADR 0559"
  - "ADR 0555"
  - "ADR 0551"
@@ -1217,6 +1218,10 @@ release reports the controller's code lines against research 063's baseline (acc
 | L2 | Nodes compose: each node agent composes its own modules, and no node applies a composition made elsewhere but the bus's user list (ADR 0547 §11) | — | the node-engine (`mesh-host`), mesh-sdk, mesh-controller | 1126 |
 | L3 | Nothing is left with the controller: the vault mints bus accounts and signs, the grants part writes grants, the try is the checker's own verb, placement is read from the catalogue alone, and the lease passes to a holder that is no controller (ADR 0547 §11, ADR 0549 §5, §6, ADR 0550 §2); the rest of the controller's code lines is the issue of L2 | — | mesh-controller, mesh-catalog (the vault, the grants part), mesh-delivery | 774 |
 | M1 | A milestone is a record of the issue tracker: each row of a design's milestone table is a milestone record its issues are linked to by `issue-tracker.link`, an issue to at most one, and pull requests and commits to issues the same way; the knowledge base's `progress` reads the milestones from the tracker, not from this table (ADR 0493 §1 to §4) | — (ADR 0493 §13 in part) | hq, mesh-catalog (mesh-issues, mesh-knowledge) | 1781 |
 | L4 | Health leaves the controller: the condition keeper holds the seat `mesh-conditions` and keeps every open condition from the observers' findings, saying today's condition events; the watchman holds `mesh-watchdogs`, its watchdogs pulses, and keeps the dead letters from the lease write; `mesh-self-check` runs the probes and says `checked`; `mesh-healers` heals on events and acts only once the lease names no controller; `status` is the view's derivation; built dark, compared, then switched by the operator's take-over; the bus module gains a tool that removes one named consumer, which the lease write uses (ADR 0564, ADR 0547 §11) | — | mesh-sdk, mesh-catalog (mesh-conditions, mesh-self-check, mesh-healers, the router, mesh-watcher, nats), mesh-delivery (watchman, view, the grants part) | 1952 |
 | L5 | Control records leave the controller: mesh-config keeps each module's declared config and the predefined keys in its own buckets and hears a pull request's config declarations from the indexer; each node agent writes its node's declared packages beside its compositions; the upgrade policy and the bus step are answered by their new owner; the hand-act log (`hand-act`, `hand-acts`, `warranted`) is a stream of a seat of its own; `settings`, `move-config` and `move-placement` go (a decision record first, under research 072; ADR 0348 §9, ADR 0502 §2, ADR 0539 §14, §15, ADR 0547 §11) | — | mesh-sdk, mesh-controller, mesh-catalog (mesh-config, pacman), mesh-delivery (indexer, assigner), the node-engine (`mesh-host`) | 1953 |
 | L6 | Provisioning leaves the controller: each node agent writes each handed module's provisioning plan on its own have key, which the vault, the node's provisioner client and every provider read through mesh-sdk instead of the controller's assignments; providers retire and clean up the consumers no plan names by themselves; `rotate` and `issued` are answered by the vault alone (a decision record first for the plan's home; ADR 0349 §10, §12, ADR 0230, ADR 0547 §11) | — | mesh-sdk, the node-engine (`mesh-host`), mesh-tools (the tool runner's provisioner client), mesh-catalog (the vault, the provisioner client, postgres, keycloak, gitea, route-adapter), mesh-controller | 1954 |
 | L7 | History and records leave the controller: builds, artifacts, durations and delivery history are read from the builder's keys and streams; the artifact store's sweep (`collect`, `held`, `mirrors`, `images`) is a seat's own; data readings are node-backup's own state; modules, seats and tools are read from the indexer, placement and the tool runner; no manifest but the controller's reads a controller bucket, so the lease write's check passes (a decision record first, under research 072; ADR 0189, ADR 0547 §11, ADR 0549 §6) | — | mesh-sdk, mesh-controller, mesh-delivery (builder, indexer, view), mesh-catalog (artifact-store-tools, the backup seat's holder, mounts, nfs-server, minio, mesh-watcher), mesh-tools (the tool runner) | 1955 |
 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
@@ -1226,7 +1231,13 @@ reads them, and this table keeps its rows without the Issues column (the operato
 Milestones L1 to L3 are the three of "The controller leaves build and delivery" above (ADR 0547 §11), given rows on
 2026-10-26 so that a reader of this table, the knowledge base's `progress` among them (issue 1947), sees the work that
 runs; 1945 is L1's and 1126 L2's only, as an issue belongs to at most one milestone (ADR 0493 §2); R6, delivered,
-names the parts of 1945 it carried in words. Release 5 (the assigner's wants, compared only) is not a milestone of its own: ADR 0524 §1 folds it into R4g, whose row above holds
+names the parts of 1945 it carried in words. Milestones L4 to L7 are the homes research 072 proposes for the controller's
 other jobs, made milestones after L3 by the operator's yes on 2026-10-28, so their design can start beside L3's work:
 L3's lease write waits until all four are delivered (ADR 0547 §11), while the rest of L3 is delivered before them with
 its switches off. They are ordered health first, since every later part says its faults through the conditions; then the
 control records, provisioning, and the history and records, whose last step is the check that no reader is left. Each
 starts with its decision record (issues 1952 to 1955). Adoption's record is L3's (ADR 0561 §5), and the licences' move
 into the vault is decided by ADR 0550 §3 under issue 1126. Release 5 (the assigner's wants, compared only) is not a milestone of its own: ADR 0524 §1 folds it into R4g, whose row above holds
 it. Release 6 is milestone R6, prepared on 2026-10-24 with ADR 0539. Its prepare step found six repositories where its row first
 named three: the gate's code is in mesh-catalog, mesh-sdk holds the composition's layout and the seat verb tables, and hq the design
 and the glossary.