feat: Device recovery via ROM bootloader mode

Cargo.toml

@@ -4,6 +4,7 @@ members = [
     "lp-base/lp-perf",
     "lp-base/lp-collection",
     "lp-base/lp-recovery",
+    "lp-base/lp-bootctl",
     "lp-base/lpfs",
     # lp-app workspace members
     "lp-core/lpc-history",
@@ -97,6 +98,7 @@ resolver = "2"
 default-members = [
     # lp-base workspace members
     "lp-base/lp-recovery",
+    "lp-base/lp-bootctl",
     "lp-base/lpfs",
     # lp-app workspace members
     "lp-core/lpc-history",
@@ -204,6 +206,7 @@ cranelift-interpreter = { git = "https://github.com/light-player/lp-cranelift",
 regalloc2 = { git = "https://github.com/light-player/lp-regalloc2", branch = "lightplayer", default-features = false, features = ["std"] }
 lp-collection = { path = "lp-base/lp-collection", default-features = false }
 lp-recovery = { path = "lp-base/lp-recovery", default-features = false }
+lp-bootctl = { path = "lp-base/lp-bootctl", default-features = false }
 
 # Common dependencies
 

docs/adr/2026-07-30-boot-control-sector.md

@@ -0,0 +1,167 @@
+# ADR: Boot-control sector
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+- **Deciders:** Photomancer
+- **Supersedes:** None
+- **Superseded by:** None
+
+## Context
+
+A project can make its own device unrecoverable. The originating case: a
+project bright enough to brown the board out at power-up. The LEDs come on,
+the rail collapses, the board resets, auto-loads the same project, and loops —
+never staying up long enough for Studio to connect and fix it.
+
+`lp-recovery` already has a boot-loop ladder that skips project auto-load
+after repeated incomplete boots, but it does not fire here, for **two
+independent reasons** (both left for a follow-up plan):
+
+1. `mark_boot_complete()` fires on the **first rendered frame**, so a board
+   that renders one bright frame and then dies looks like a successful boot
+   and resets the counter every time.
+2. `ResetCause::Brownout` is excluded from `blames_code()`, so brownouts never
+   increment the counter even when the counter is reached.
+
+And a third problem that no amount of ladder tuning fixes: **the recovery
+region lives in RTC fast RAM, which is wiped on `PowerOn`.** The instinctive
+human response to a misbehaving board is to unplug it — which erases the
+evidence that it was looping at all. A latch a user destroys by doing the
+obvious thing is not a latch.
+
+Separately, recovery tooling needs to tell a device "come up without loading a
+project" while the device is in ROM download mode — i.e. while no firmware is
+running to receive a message. The only channel available there is flash
+itself.
+
+These are the same requirement seen from two directions.
+
+## Decision
+
+Add a dedicated **4 KB `bootctl` flash partition** carrying a small record
+that the firmware reads before it auto-loads a project. The format lives in a
+new `no_std`, zero-alloc crate, `lp-base/lp-bootctl`, shared by every writer
+and reader so they cannot disagree.
+
+**Placement: the 4 KB comes out of `nvs`,** which shrinks from `0x6000` to
+`0x5000`, putting `bootctl` at `0xe000`. Nothing reads NVS — no LightPlayer
+code references it, and `esp-radio`'s `NVS` is a 15-word **RAM** array
+(`common_adapter.rs`) plus stubbed ESP-IDF shims, not this partition. This
+placement moves **no other offset**, so `lpfs` stays at `0x310000` and
+existing devices' filesystem images remain valid. Both boards keep
+byte-identical layouts so the offset can be a constant rather than a
+partition-table lookup.
+
+**Two writers, one format.** The host writes the record over esptool while
+the device sits in ROM download mode — the path that works on a board that
+cannot boot. The firmware will later write it too, to latch its own degraded
+state across a power cycle (follow-up plan; today the firmware only reads and
+consumes).
+
+**Blank is safe.** A device that has never seen this feature reads `0xFF`
+bytes. That, a bad magic, a bad CRC, a future format version, a short read,
+and a torn write all decode to "boot normally". There is exactly one way to
+get a non-default boot: a fully valid record that asks for one. A corrupt
+sector can never *cause* a degraded boot — only fail to prevent one.
+
+**Torn writes: one write, integrity by checksum.** The record is written to
+an erased sector in a single operation, and its integrity rests on the magic
+and CRC rather than on write ordering.
+
+This is deliberately *not* the discipline `lp-recovery` uses. That crate
+publishes RTC-RAM structures by flipping one visibility word last, and the
+flash-native mirror — write the payload, then the magic — was the original
+design here. **It does not work.** Every flash-write API that can reach this
+sector issues the ESP ROM/stub `FLASH_BEGIN`, which *erases the sectors it is
+about to write*; that is true of `espflash::write_bin_to_flash` and of
+`esptool-js`'s `writeFlash` alike. A second write publishing a first would
+erase it instead, leaving a valid magic over an erased payload — which fails
+the CRC, boots normally, and makes the feature silently inoperative.
+
+The CRC covers the magic, so every prefix of a partial write fails one of the
+two checks. `no_partial_write_is_ever_honored` asserts that for all 16
+truncation points.
+
+**Consume on read, not on use.** The firmware erases a valid record the
+moment it reads it, before anything acts on it. That makes the instruction
+one-shot — the user asked for one recovery boot, not a permanent mode — and
+means a crash *during* the recovery boot cannot make it sticky. The failure
+mode traded for is an erase that fails, which strands the device reachable
+with no project loaded: the safe direction, and itself recoverable.
+
+**Unknown flag bits are ignored, not rejected.** A newer host asking for
+something this firmware cannot apply still gets the instructions it does
+understand.
+
+**Amendment 2026-07-31 — the safe-mode clamp bits are assigned.** Bits
+`8..16` now carry a safe-mode output clamp level (`0` = none, else a
+brightness ceiling out of 255), with a precedence rule defined in the
+format: *a firmware that implements the clamp loads the project dimmed and
+ignores the skip bit* — a dim, visible board is a strictly better
+degradation than a dark one. Studio's "Start in safe mode" writes BOTH the
+skip and a dim clamp, so the same record means "nothing loaded" on firmware
+that predates the clamp and upgrades to "project running dim" when the
+clamp lands, with no format bump and no Studio change. Firmware consumption
+of the clamp remains with the follow-up plan (it shares the output path
+with the fixture mA limiter).
+
+## Consequences
+
+- **This is a breaking flash-layout change.** A device flashed with the old
+  table has no `bootctl` partition; the region at `0xe000` is inside its
+  `nvs`. Reading it yields whatever NVS had there — which decodes as `Blank`
+  or `Invalid`, so an un-reflashed device simply never takes a boot-control
+  instruction. Deployed boards must be reflashed with the new table to gain
+  the feature, and that is safe because nothing reads NVS.
+- `lpfs` is untouched, so reflashing does **not** cost the user their files.
+- The firmware gains a flash read (and conditionally a 4 KB erase) on the boot
+  path, before the filesystem mounts. Measured cost: image grew well within
+  budget — 2 866 928 B of 3 145 728 B, 278 800 B headroom against a 65 536 B
+  CI margin.
+- `lp-bootctl` hardcodes the offset, so the two boards' partition tables must
+  stay identical. `lp-base/lp-bootctl/tests/partition_layout.rs` enforces
+  that, along with no-overlap, the 4 MB bound, and that no pre-existing
+  partition moved. Those guards live in `lp-bootctl` rather than `fw-esp32c6`
+  because the latter is RV32-only and excluded from host builds, so tests
+  there would never run.
+- Two skip-auto-load reasons now exist (boot-control record, and the
+  RTC-resident incomplete-boot ladder). The boot log always names which one
+  applied.
+
+## Alternatives Considered
+
+- **Shrink `lpfs` instead of `nvs`.** Rejected: changing the partition size
+  changes littlefs's block count, invalidating every existing filesystem
+  image. Recovery tooling that costs users their files is self-defeating.
+- **Append after `lpfs`.** Impossible: the layout ends at exactly `0x400000`
+  on a 4 MB part.
+- **Store the flag in NVS proper.** Rejected: writing ESP-IDF's NVS format
+  from a host over esptool means implementing that format host-side, which is
+  far more work than a 16-byte record in a raw sector, for no benefit.
+- **Store the flag in `lpfs`.** Rejected on two counts: the host would have
+  to build and rewrite a littlefs image just to set one flag, and the flag
+  would live in the same structure whose corruption is one of the things it
+  needs to survive.
+- **Keep the latch in the RTC recovery region.** Rejected: wiped on
+  `PowerOn`, and unplugging the board is the single most likely user action
+  in the scenario this exists for.
+- **A `consumed` marker word instead of erasing.** Bit-clearing a word is
+  cheaper than a 4 KB erase and avoids an erase cycle per recovery boot.
+  Rejected for simplicity: it doubles the states to reason about in a
+  safety-critical primitive, and the erase happens at most once per recovery
+  boot, where tens of milliseconds are irrelevant.
+- **Numeric partition subtype `0x40`.** Rejected because it does not work:
+  espflash's `esp-idf-part` panics on any `data` subtype outside its enum.
+  Used `undefined` (`0x06`), ESP-IDF's designated user-data subtype.
+
+## Follow-ups
+
+- The firmware as a *writer*: latch degraded state across a power cycle after
+  repeated failures. Needs the boot-complete redefinition and the brownout
+  blame policy fixed first — both deferred to the follow-up plan.
+- The graduated output clamp that reserved flag bits `8..16` exist for.
+- Mirroring a last-crash summary into the sector, so post-mortem is readable
+  from a board that never boots (the RTC crash record is not).
+- `lpfs` is declared with subtype `spiffs` but is littlefs; `esp-idf-part`
+  does support a `littlefs` subtype. Left alone deliberately — cosmetic, and
+  changing it would alter the partition-table binary for no functional gain.

docs/adr/2026-07-30-bootloader-mode-detection.md

@@ -0,0 +1,101 @@
+# ADR: Bootloader-mode detection is handshake-authoritative
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+- **Deciders:** Photomancer
+- **Supersedes:** None
+- **Superseded by:** None
+
+## Context
+
+Recovery tooling has to know what is on the other end of the wire: LightPlayer
+firmware running the app protocol, a ROM/stub bootloader waiting to be
+flashed, or nothing useful at all. "Flash firmware", "erase", and "write a
+boot-control record" only work against a bootloader; the app protocol only
+works against the app.
+
+Studio has never had to answer this directly. Readiness is granted by exactly
+one thing — a proto-matching `ServerHello` — and everything else was
+*diagnosis*: `BootLineClassifier` watches non-protocol serial lines and
+explains why a device is not ready. That is enough to render an error, but
+not to decide which operations to offer.
+
+## Decision
+
+**Enumeration data cannot answer this, and the code says so.** ESP32-C6 and
+ESP32-S3 use the chip's native USB-Serial-JTAG peripheral, and the ROM
+bootloader uses *that same peripheral*: the device enumerates as
+`303A:1001` whether it is running our firmware or sitting in download mode.
+Boards behind a CP2102/CH340 bridge are worse — they always report the
+bridge's identifiers, never the chip's state. VID/PID matching is not merely
+a weaker signal here; it is structurally incapable of distinguishing the two
+states. It is recorded as rejected so it is not re-proposed.
+
+Mode is therefore established by **talking to the device**, in three tiers of
+evidence:
+
+1. **A proto-matching `ServerHello` ⇒ `App`.** Readiness is untouched:
+   `DeviceLinkMode` classifies, it does not promote. The hello remains the
+   only thing that grants readiness.
+2. **ROM download-mode boot lines ⇒ `Bootloader`, corroborating.** Strong
+   when present, meaningless when absent — a board *already* in download mode
+   printed its banner before Studio attached, so silence proves nothing. This
+   is why absence of the signature classifies as `Unknown`, never as "not a
+   bootloader".
+3. **An esptool SYNC handshake ⇒ `Bootloader`, authoritative**, plus the chip
+   identity for free.
+
+Anything else is `Unknown`, which means "no evidence", not "nothing is there".
+
+**The probe is mode-exclusive because it reboots the device.** The handshake
+drives DTR/RTS to enter download mode, and on USB-Serial-JTAG that reset
+drops USB enumeration and invalidates the port handle. So
+`DeviceSession::probe_link_mode` takes `DeviceMode::Management`, releases the
+link, probes, and rebuilds — the same discipline as `manage`. It is never
+part of the routine connect ladder. `DeviceLinkMode::probe_would_help()`
+returns `false` for `App` for exactly this reason: probing a healthy board
+costs a reboot and buys nothing.
+
+**An unanswered probe is not proof of `Unknown`.** A device happily running
+the app ignores SYNC too. On probe failure the session reports the *passive*
+classification of the rebuilt link rather than asserting `Unknown` — the
+honest answer instead of a guess.
+
+## Consequences
+
+- Studio can offer bootloader-only operations on evidence rather than hope,
+  and can say *which* of the three states it sees.
+- Chip identity arrives free with an authoritative probe, which M8 needs to
+  refuse cross-chip whole-flash restores.
+- The probe costs a device reboot, so it must stay behind an explicit user
+  action or an explicit escalation. Any future caller that runs it
+  speculatively will reboot healthy boards; `probe_would_help()` exists to
+  make the right thing easy.
+- `BootLineClassifier` remains the single boot-line classifier in the app
+  layer. A previous duplicate in `lpa-studio-core` was demoted and deleted
+  (see `2026-07-15-device-session-model`); this ADR does not reintroduce one.
+- Providers without a bootloader concept (host process, browser worker sim)
+  report the probe as unsupported rather than fabricating an answer.
+
+## Alternatives Considered
+
+- **Match USB VID/PID.** Rejected as impossible, not merely unreliable — see
+  above. This is the alternative most likely to be re-proposed by someone who
+  has not hit the USB-Serial-JTAG detail, which is why it is stated first.
+- **Trust boot-line classification alone.** Rejected: its absence carries no
+  information, so it can never distinguish "bootloader" from "silent". Kept
+  as corroboration, where its presence is genuinely strong.
+- **Probe on every connect** and cache the answer. Rejected: it reboots every
+  healthy device on every connect, and on USB-Serial-JTAG it also drops the
+  port handle mid-ladder.
+- **Treat an unanswered probe as `Unknown`.** Rejected: an app-mode device
+  ignores SYNC, so this would report a working board as broken.
+
+## Follow-ups
+
+- Surfacing the mode in the UI, and the "waiting for a device in bootloader
+  mode" confirmation that makes the BOOT-button ritual learnable, is M5 of
+  the device-recovery plan.
+- A flapping-device heuristic (enumeration-drop counting) is M9 and is
+  deliberately offer-only: it must never trigger a probe on its own, since
+  that would reboot a device that may just have a loose cable.