feat(bengle): isolated-cell auto-detect load-cell calibration wizard

[ChampionDesigns]

Stacked PR — B-5 of 10. Builds on #462 (feat/bengle-stop-weight-tare). Until that merges this PR's diff includes its commits; please review/merge in order B-1 → B-10.

The story

A Bengle weighs your shot with two load cells under the drip tray, and how much you can trust that
number depends entirely on whether the cells have been calibrated. The firmware knows how to do it:
there is a non-blocking procedure that precision-zeros the empty platform, then latches the
same known mass on each bare cell in turn (the firmware auto-detects which cell is loaded), solves for both per-cell
sensitivities so that a summed mass is position-independent, and persists the result. The app had no
way to drive it. That means per-unit weight accuracy could not be established in the field, and
because stop-at-weight (B-4) is only as good as the scale under it, neither could stop-at-weight. This
PR adds the mixin that drives that state machine and a REST endpoint to run it from.

Summary

• Problem: the firmware's isolated-cell load-cell calibration was unreachable from the app. Per-unit
  weight accuracy, and therefore stop-at-weight, could not be trusted or corrected.
• Why it matters: a scale that has not been calibrated is not a scale, it is a number. Everything
  downstream of it in this stack (bridged weight, gravimetric flow, autonomous stop-at-weight, the
  yield in the shot record) inherits whatever error the cells have.
• What changed: a ScaleCalibrationCapability mixin on UnifiedDe1 that drives the firmware's
  ScaleCalCmd / ScaleCalState / ScaleCalWeight registers with bounded polling, a single-flight
  guard, a cancellable run token and dispose-safety across a disconnect; a
  POST /api/v1/machine/scale/calibrate endpoint taking zero, left, right or abort; and a
  scaleCalibration capability string.
• What did NOT change (scope boundary): the endpoint returns 404 on a plain DE1 and the mixin
  is Bengle-only. Firmware command 3 (its own tare) is deliberately not exposed: reaprime tares
  through the dedicated ScaleTare register from B-4, and two paths to a zero is one too many.
  The cal is driven by firmware command 2 (isolated-cell gain latch: platform OFF, weight on one bare cell, firmware auto-detects which); the old explicit left/right latches (commands 4/5) are retired in firmware.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore / infra
• Plugin (DYE2 or bundled skin)

Scope (select all touched areas)

• BLE transport / device comms
• REST API / handlers
• WebSocket API
• Machine state / shot logic
• Scale / weight / flow
• Profiles / beans / grinders / workflows
• WebUI skins
• Plugins / JS runtime
• UI / Flutter widgets
• Storage / Drift database
• CI / build / infra
• Docs / specs

Linked Issues

• Closes # N/A - no tracking issue
• Related # N/A

Root Cause (if bug fix)

N/A - new capability.

Regression Test Plan (if bug fix or refactor)

N/A as a regression plan, but the new coverage is the substance of this PR, so it is worth stating:

• Target test or file:
  test/unit/models/device/impl/de1/unified_de1/scale_calibration_capability_test.dart (new, 475
  lines) and test/services/webserver/de1handler_scale_calibrate_test.dart (new, 12 tests including
  the no-machine 500 case), plus a MockBengle cal group and new rows in the B-1 MMR contract
  checker.
• Scenario the tests lock in: the stale-terminal race (see below) has its own group; the
  single-point firmware's terminal words are pinned as byte anchors (0x04020000 and 0x05030000);
  the left-latch case is asserted order-free; abort unwinds the poll immediately; and a run whose
  state never observably changes fails on the deadline rather than reporting success.

Documentation Obligations (required)

• API spec updated: assets/api/rest_v1.yml - the new calibrate path, two new schemas, and the
  capabilities enum, example and descriptions.
• API docs updated: doc/Api.md - new rows.
• Plugin docs updated
• Skin docs updated
• Profile docs updated
• Device docs updated - no DeviceManagement.md or websocket_v1.yml delta; this adds no
  transport behaviour and no WebSocket topic.
• Other: a new end-to-end scenario, bengle-scale-calibration.md, and a refreshed capabilities
  array in bengle-integrated-scale.md.

Security Impact (required)

• New or changed REST endpoints? Yes - POST /api/v1/machine/scale/calibrate. It takes a JSON
  object with a command of zero, left, right or abort, and a grams reference mass for the
  two weight commands. Unknown commands and non-object bodies are 400; a plain DE1 is 404. It is
  on the same local, unauthenticated web server as every other machine endpoint, so its exposure is
  the exposure the server already has: anyone who can reach port 8080 can already start a shot. The
  worst a caller can do here is write a bad calibration, which is recoverable by running a good one,
  and cannot damage hardware (the firmware rejects implausible masses, non-positive per-cell deltas,
  ill-conditioned placements, and solved cals outside plus or minus 50 percent of nominal).
• New or changed WebSocket topics? No
• New or changed network calls? No
• BLE/USB surface changed? Yes - three new Bengle-only MMR registers, all registered with the B-1
  contract checker.
• File system access changed? No
• Plugin sandbox boundary changed? No

User-Visible Changes

A Bengle's integrated scale can be calibrated from the app: zero the empty platform, put a known mass
on the left half, put the same mass on the right half. scaleCalibration appears in
/api/v1/machine/capabilities. Nothing on a plain DE1.

Note for anyone building the wizard UI: the firmware reads the reference weight back in whole
grams (it truncates before scaling), so only whole-gram masses round-trip. That is documented in the
spec and in the hardware contract, and the UI should not offer 500.5 g.

Verification

Local gates (run before pushing)

• flutter analyze - clean (No issues found!)
• flutter test - 2150 tests pass at this branch head (B-4 was 2113; +37 from this
  branch's own tests)
• (cd packages/dye2-plugin && npm run build) - plugin builds

Manual verification (if applicable)

• OS / platform tested: Linux (analyzer, full test suite).
• Simulated devices? (simulate=1): No
• Real hardware? (DE1/Bengle/scale): Yes, for the race described below, which was measured on
  silicon: a second calibration POST returned success in 0.316 s while the fresh zero it had just
  triggered was in fact still running, out to 15.7 s. That measurement is the reason the completion
  logic is as careful as it is.
• What you personally verified and how: the local gate set, and every register and state encoding in
  this diff read back against the firmware's calibration engine and the bengle_hw_v1.yml
  contract.
• Edge cases checked (by test): abort during a poll; a disconnect and reconnect mid-run (each poll
  binds its progress subject locally, and init never resets the run token, so a stale poll still sees
  the bump); a run that terminals twice inside one poll interval; the single-point firmware's
  colliding step numbers.
• What you did not verify: I have not run a full calibration to completion on hardware with
  this branch and then checked the scale against a reference mass. The individual firmware
  behaviours it is built on were observed on the machine (including the stale-terminal race), but the
  end-to-end "calibrate, then weigh a known mass, and confirm the reading is right" loop has not been
  run against this slice. That is the test this PR most needs before it is trusted in the field, and
  the calibration wizard run is still owed.

Evidence

• Test output (2150 pass)
• Log snippets (the 0.316 s versus 15.7 s stale-terminal measurement)
• Screenshot / recording (UI changes)
• curl / websocat output (API changes)

Compatibility & Migration

• Backward compatible? Yes - purely additive.
• Config / env changes needed? No
• Database migration needed? No

Deliberate choices worth your review

1. The stale-terminal race, and why the completion logic looks paranoid. The firmware latches the
   previous run's terminal word in ScaleCalState until it picks up a new command, so a poll that
   races the trigger reads a stale done or error from the run before. Measured on silicon: a
   second cal POST returned success in 0.316 s while the fresh zero was still running out to 15.7 s.
   For a zero that is merely wrong; for a left or right latch it is dangerous, because the user would
   see "done" and lift the reference mass while the firmware was still averaging it. So _runCalStep
   snapshots the state word before triggering and accepts a terminal only once the state has been
   observed to leave terminal, or when the terminal word differs bitwise from the snapshot (which is
   the legitimate case of a run that re-terminals inside one poll interval). A run whose state never
   observably changes fails safe on the deadline instead of succeeding instantly on a stale word, and
   stale words are kept off the progress stream so a wizard cannot flash "done" right after the
   trigger. This is the single most important paragraph in the PR and the code hunk I would most like
   a second opinion on.
2. Completion keys off the packed word's SubState, never the Step byte. Field single-point
   firmware numbers Complete = 4 and Error = 5, which collide with two-point taring and
   complete. Step-keyed logic would both miss a real completion and mistake an error for success.
   SubState is set atomically with Step in both firmware generations, so keying on it works on
   field firmware and new firmware alike. The two colliding words are pinned as byte anchors in the
   tests.
3. The reference weight is read back and confirmed before the latch is triggered. 0.1 g is one
   wire LSB at the x10 scaling, and a dropped write would calibrate the machine to the wrong mass, so
   the confirmation is worth the round trip.
4. Bounded polling: 500 ms interval, 30 s deadline. de1plus polls at 1 Hz with no deadline at
   all. I would rather a calibration fail cleanly after 30 seconds than hang a wizard forever, but
   30 s is a judgement call, and the 15.7 s zero measured above is uncomfortably close to half of it.
   If real hardware ever takes longer than 30 s to zero, this number is wrong and should be raised.
5. A failed calibration returns 200 with success: false, not a 4xx. The outcome of the
   procedure is data; the transport succeeded. An abort returns 202. If the house style prefers a
   failed cal to be a 422, this is a one-line change.

Risks & Mitigations

• Risk: the 30-second deadline is too tight for a slow zero on a cold or noisy machine, and a
  legitimate calibration reports a timeout.
  • Mitigation: the failure is clean and safe (the firmware run is stopped with cmd = 0 and the
    user simply re-runs), and it is one constant. But I want to be explicit that the closest measured
    real zero was 15.7 s, so the margin is about 2x and not more.
• Risk: a wizard UI shows a done that belongs to a previous run.
  • Mitigation: exactly the case the run-token and snapshot logic above exists to prevent, and it
    has its own test group. It is the reason I did not implement this the obvious way.
• Risk: a user calibrates with a non-whole-gram mass and gets a silently wrong calibration.
  • Mitigation: documented in the spec, in the hardware contract, and in this PR. It is not
    currently rejected by the app, and it is not enforced in code. If you want a client-side guard
    that rejects a fractional grams, say so and I will add it - it is a good idea and I left it out
    only to keep the app from second-guessing the firmware.