amyboardweb: verify sketch writes to AMYboard, retry on corruption

[bwhitman]

The bug (field reports: Windows)

"Write to your AMYboard" intermittently pops a SyntaxError at a varying line (6, 11, 22 seen in the field), sometimes a UnicodeDecodeError — yet the file on disk later looks fine, and it only takes one user retry to "fix" it.

Root cause

The zT transfer has no integrity check. The failure cascade:

1. One 188-byte sysex chunk is dropped in transit by the host MIDI stack.
2. The board's transfer_stored_bytes never reaches the promised size, so transfer_flag stays AMY_TRANSFER_TYPE_FILE forever — there is no board-side timeout.
3. While that flag is set, amy_parse_message routes every sysex-originated message to parse_transfer_message before command parsing — so the zP environment_transfer_done, liveness probes, and the retried zT header all get base64-decoded into the open file as binary garbage (b64_decode_ex silently stops at the first non-base64 char).
4. The retry's chunks are valid base64, so the counter finally crosses the threshold mid-retry; the file closes containing original-minus-a-chunk + garbage + partial retry and runs → SyntaxError at wherever the chunk went missing (chunks are ~4–7 sketch lines apart → varying line numbers), or UnicodeDecodeError from the non-UTF-8 garbage.
5. The user's next clean Write overwrites everything — which is why the file "looks fine" by the time anyone inspects it.

Bench findings (Windows 11 + AMYboard on USB, python-rtmidi via the winmm compat layer)

• Outbound (host→board) is robust: paced, burst-4, and fully unpaced transfers up to 20KB / 107 chunks all landed byte-perfect (verified by CRC32 computed on the board). The board's 8-slot sysex ring keeps up even with zero pacing.
• Inbound (board→host) sysex above ~1KB is silently dropped by fixed-size sysex input buffers. The board's zD dump frames (~1030 bytes) are exactly in the kill zone; small frames (ACKs, error reports, CRC replies) always arrive.
• Chromium (Edge) on the new Windows MIDI Services stack (build 26200, SWD\MMDEVAPI\MIDII_* devices) enumerates zero Web MIDI ports — a separate compat gap worth its own FAQ entry.
• macOS/CoreMIDI: clean in both directions at every size and pacing tested.

The fix (web-only — works with firmware users already have)

After sending the chunks, verify with a CRC32 computed on the board (zP exec of binascii.crc32 over the written file) reported back in a ~20-byte 'H' sysex frame, compared against the same CRC computed in JS:

• Mismatch → resend, up to 3 attempts. A best-effort zD read-back locates the first corrupted byte for the [verify] console diagnostic (on hosts that drop the ~1KB zD frames it just times out quietly — the CRC verdict stands regardless).
• CRC report timeout → the wedged-transfer signature (the request itself was eaten as transfer data). Recovery: zB reboot to clear the stuck transfer, then resend. On Windows Chrome — where WebMIDI can't survive a zB in-document — reuse the existing stash-and-reload flow, which resumes and re-verifies in _upload_sketch_post_bootloader; reloads capped at 2.
• environment_transfer_done only fires on a verified write; otherwise the user gets a clear alert instead of a corrupt sketch running.

Also adds /miditest.html — a self-contained field diagnostic (paced write of a scratch file, board-CRC verify, zD read-back measurement) with copyable JSON results. Hosted because Firefox only grants Web MIDI via its site-permission add-on on public https origins.

Testing

• Stubbed-transport tests of the real code paths (synthesized sysex frames through _process_complete_sysex): happy path, corrupted-send (CRC mismatch caught, first-difference diagnostic at the exact corrupted char/line, verified on resend), wedged non-Windows (timeout → zB reboot → verified), wedged Windows Chrome (reload-needed), full Write flow (transfer_done only after verify).
• JS CRC32 parity-tested against MicroPython/CPython binascii.crc32.
• Hardware protocol driver (zt_pacing_test.py) run against a real AMYboard from macOS and Windows 11 — results above.

Follow-ups (not in this PR)

Firmware/amy hardening: board-side transfer inactivity timeout (abort + delete partial + error sysex), chunk sequence numbers/CRC in zT, file size/CRC in the X error payload, and smaller zD dump frames (≤1KB incl. framing) so reads survive winmm-buffer-limited hosts.

🤖 Generated with Claude Code

[github-actions]

🔌 AMYboard PR preview

Editor + flasher: https://amyboard-pr-1220.vercel.app/editor/

This preview bundles this PR's firmware — its flasher only flashes this build (not the release). Rebuilt on every push; removed when the PR closes.

The hardware CI has been kicked off and should return within a few minutes, stand by!

[github-actions]

🎛️ HW CI (physical bench)

AMYboard (USB-MIDI + AMY zP → audio; built-in tones + AMYboard World sketches acid/house/woodpiano over the SysEx control API): ✅ PASS — flashed this PR’s firmware; all checks matched the references.

Tulip (TULIP4_R11; serial-REPL audio + WiFi screenshot): ✅ PASS — flashed this PR’s firmware; all checks matched the references.

⬇️ Artifacts: recordings · screenshot · serial logs · run logs

_{Self-hosted bench. Audio spectral-compared to ref/hwci_basic.wav, the AMYboard World sketch refs (ref/{acid_generator,house_generator,woodpiano}.wav) + ref/tulip_basic.wav; Tulip screenshot pixel-compared to ref/tulip_screenshot.png. Both analog outs share one capture card, so the tests run sequentially.}