fbuild-deploy: pre-deploy artifact size validation against board flash region #690

TL;DR

fbuild deploy currently does not validate the firmware artifact's size against the target board's flash region before invoking the deployer. esptool does this on its side for ESP, so the gap is invisible there. For LPC8xx (64 KB flash on LPC845, 32 KB on LPC804), Teensy, STM32, and RP2040 the silent path is "build a too-large binary → pyocd flash succeeds at writing the bytes that fit → device boots into garbage." This is a class of "the device looks dead" bug that the FastLED #3300 / #3325 / #3339 LPC bring-up incident sat next to but never tripped (firmware was 53.85 KB / 64 KB, well under the ceiling).

Now that we're up against the LPC845 ceiling (84% flash used per #3339's verification table), every future PR can push it over. Worth catching at fbuild time, not flash time.

Proposed shape

Pre-deploy check inside whatever orchestrator runs the deploy. Board JSON already carries upload.maximum_size (and ESP-side variants); fbuild reads it. The check is one line + one error:

let max_flash = board.upload.maximum_size;
let actual_size = std::fs::metadata(&firmware_bin)?.len();
if actual_size > max_flash {
    return Err(FbuildError::FirmwareTooLarge {
        actual: actual_size,
        max: max_flash,
        board: board.name.clone(),
    });
}

Two refinements worth folding in:

• Warn at >90% of maximum_size so the user sees the ceiling approaching before it bites.
• Per-region check for boards with split flash regions (LPC845 has CRP region carved out by the linker; RP2040 has XIP boot region). Read the linker map (firmware.elf.map) or the board JSON region table, whichever fbuild already parses.

Acceptance criteria

• Pre-deploy size check lives in fbuild-deploy's top-level orchestrator, runs before every deploy backend is invoked.
• Error type carries actual, max, board so a bash autoresearch <board> failure shows the user exactly what overflowed.
• Boards without a maximum_size (esp32 catch-all) skip the check with a debug log.
• One unit test per board family in tests/.

Refs

• FastLED/fbuild#686 — BOARD_FINGERPRINTS. Same data path.
• FastLED/fbuild#687 — BoardFamily. Different concern (DTR/RTS), but lives in the same pre-deploy hook surface.
• FastLED/FastLED#3339 — last firmware was at 84.1% flash. We are one PR away from this issue biting.

Filed from the audit fan-out on FastLED/FastLED#3339.