Decisions › D17
Proposed: the expected setup grows into the rig's acceptance spec
Context
Zach's oldest diagnostics idea is that a diagnostic is the interface's contract test: run once at the bench to accept a part, then kept running in deployment to prove it still meets the contract. Two things were never settled: who judges a group, and how “not run yet” reads. The rollups report put five proposals against his criteria.
The decision
Proposed: grow the file that is being built now (expected.toml) from “what should be here” into “what must be true, and when it is checked”: at startup (read-only checks at boot, plug and replug), continuously (judged on the reports the drivers already send), and on initiation (a person's click runs a check that touches or moves hardware). The same file runs at the bench and on site. It lands after the caused_by fix.
Not yet accepted. The report listed five questions for Zach, each with a default taken if he says nothing; the first, composites explaining upward, was built as the barrier. The remaining four are open, with these defaults: a wrong gear ratio stays the board's own warning until the checks land; validity windows of 24 hours for a communication sweep and 7 days for motion checks, reset on restart, replug or firmware change; keep the as-built record and the manifest as two files for now; and no “6 of 7 is fine” tolerance yet.
Why
“you can do them during deployment for monitoring”
Zach Yamaoka, notes
“have one ground truth of success and health”
Zach Yamaoka, notes
“Yes the roll up view I think important perhaps right..”
Zach Yamaoka, notes, 22 Oct 2026
Options considered
Weighted score out of 5 against seven criteria taken from his notes (black boxes keep their word, one check with two lives, honest status, declared and minimal, off the shelf, calm first screen, a tracer bullet this week). No single weight moved by 10 or by 20 points changes the winner.
| Proposal | Idea | Score |
|---|---|---|
| P3 Manifest as the rig's acceptance spec | The expected setup becomes what must be true and when it is checked. | 4.45 |
| P5 Capabilities | The top line says what you can do now, not how the rack is. | 4.00 |
| P4 Tests | A test per expectation, with its last result. | 3.65 |
| P2 Rollup groups as data | One file declares groups and how members combine, like ROS's aggregator. | 3.40 |
| P1 Wrapper plugins | Every composite is a driver with its own verdict code. | 3.20 |
Consequences
- If accepted: the rig row would read something like “6/7 boards · accepted 2/4 · comms sweep not run (26 h ago)”, with a click into the check table.
- Left out on purpose: none of this is a safety path, and fleet streaming and error budgets belong to fleet KPIs later.
Evidence
- Diagnostics rollups: five proposalsReport, 2026-10-23. Evidence for this decision.
- The expected setup (a rig manifest)Contract doc, 2026-10-23. A small file that says what this PC should see, so the page can say 6 of 7 boards and name the missing one.
- Diagnostics record v0Contract doc, 2026-10-22. ROS DiagnosticStatus kept whole, plus Entity, Event, Fault and Action. Eight lessons from the field, the rules, and the evidence re-checked.
Commits in the app's repository (private):
ebf382a2026-10-23 Report: five ways to reconcile black boxes with top-level checks (P3 recommended)