Merge pull request 'ADR 0256: one module reads a machine's hardware condition, and a fault is said through its health' (#206) from decision/hardware-sensors into main

03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md

@@ -10,6 +10,7 @@ decisions:
   - 02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md
   - 02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md
   - 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
+  - 02-DECISIONS/0256-a-machines-hardware-condition-is-read-by-one-module-on-every-machine-and-a-fault-is-said-through-its-health.md
 ---
 
 # 48 — A module says how it is healthy
@@ -292,6 +293,43 @@ the machine itself, beside its liveness looks, and says it in the same statement
   [ADR 0246](../../02-DECISIONS/0246-a-seats-new-verb-is-promised-before-it-is-required.md), from
   [issue 298](../../04-ISSUES/298-a-new-seat-verb-deadlocks-across-two-repositories/00-report.md)).
 
+## 11. The machine under the modules: its hardware
+
+([ADR 0256](../../02-DECISIONS/0256-a-machines-hardware-condition-is-read-by-one-module-on-every-machine-and-a-fault-is-said-through-its-health.md).)
+Every module on a machine runs on its hardware, and none of them owns it. The `sensors` module reads its
+condition on every machine it is assigned to. It holds no seat, and states a fault through the module
+health of this design, not yet through the machine's own judgement as §10 does for the network.
+
+```
+  sensors on one machine                                   node-engine            controller
+  ┌──────────────────────────────────────────────┐
+  │ drive reader (root) each drive's health,     │ unit ──► liveness + readiness
+  │                     never one asleep; each   │
+  │                     read bounded, or said    │
+  │ fan watch           fans that ran since boot │ tool ──► asks sensors_health ──► module.sensors.<m>.unhealthy
+  │                                              │          every 60 s, 2 looks     (the why is its evidence)
+  │ tools (operator)    /sys and the two files;  │
+  │                     read-only                │
+  └──────────────────────────────────────────────┘
+```
+
+- **Unhealthy means the hardware is failing, measured against its own thresholds:** a CPU, GPU, drive or
+  zone temperature at or above its own critical value (a board chip's is shown, never judged); a drive that
+  says it is failing (a SATA drive's verdict, a pre-failure attribute failing now, an NVMe critical warning
+  bit other than temperature); a fan that ran since boot and reads 0 while a CPU sensor, a thermal zone or a
+  sensor on its own non-board chip is at or above its own maximum; memory that reports an uncorrectable
+  error. **Or that the module's own processes are stale:** a file five minutes old, a drive's read stuck
+  past its bound, a drive not looked at for twice its cadence. HIGH readings, fan notes and a drive asleep
+  for a day are said by the tools and raise nothing.
+- **One reader, never waking a drive that can say it sleeps:** the module's drive reader alone reads the
+  drives (no `smartd`), a spinning drive hourly, because a read can restart a standby timer the mesh cannot
+  yet see.
+- **A class the machine lacks is not present**, never a failure: a virtual machine with no sensor and no
+  SMART drive is healthy.
+- **The cost of using module health for the machine's fault** is that the condition names the module, and a
+  standing fault holds the module's own builds at their gate. The machine judging its own hardware, as it
+  judges its network in §10, is the follow-up that removes both.
+
 ## Phases
 
 | Phase | Repository | Delivers | Done when |
@@ -304,6 +342,7 @@ the machine itself, beside its liveness looks, and says it in the same statement
 | D — the proof | mesh-lab, mesh-catalog | the bed; the catalogue's check starting every changed resource on it; adopted image checks proved | the replay of the studio's false *unhealthy* fails the bed, not a machine |
 | E — the migration | mesh-catalog, mesh-controller | the declarations of §9 steps 2–5; the count kept in the catalogue and its test; `module check` refusing after the date | the count is zero, or the date has passed and `module check` refuses |
 | F — the machine's network | `mesh-host` (node-engine), `mesh-controller`, `mesh-catalog` | §10: the five parts judged on two looks and stated; the three conditions said once; the gate waiting on another's; `node show` | the tests of ADR 0241 pass; the drill's replay raises and clears; a VPN connect on the laptop is raised naming its writer and cleared by the reconcile |
+| G — the machine's hardware | `mesh-catalog` | §11: the `sensors` module, its tools, the drive reader and the fan watch, both checks declared | its tests pass; `module check` accepts its health; on the first machine both checks are stated healthy |
 
 Phases A and B may be built together; A is live first, because it judges without a single declaration.