[jbenedictocenteno]

Description of Change

An install that needs room takes apps out of the directory before the first byte arrives. Whatever then went wrong, a dropped link, a bad file, a reset, cost every one of them, though the region erases 64 KB as the data gets there and most of that flash was never touched.

Giving back what was not reached

• A failed install puts back every victim its write did not reach, in one directory commit. The log says which were kept and which were overwritten.
• The same after a reset: the table of victims goes to NVS (kappmgr/undo) before the eviction commit, each with a CRC-32 of its extent. A start-up that finds one takes it out of NVS first, recomputes each CRC 512 KB a step, and puts back the victims whose bytes are as they were.
• A file on the card counts as an app's copy only at the image's length. Any /sdcard/<project>.bin, an older version included, used to let the app be evicted with "its copy is on the card".

Judging an image before hashing it

• esp_image_verify(), and esp_ota_end() through it, hash every segment by the length its header declares and compare the total with the partition only afterwards. Over an image cut short those lengths are read from stale flash. The region and the OS slot now walk the segment chain first, as the mailbox already did, and refuse such an image unhashed.
• A raw image cut inside its first segment is refused before anything is placed: the header says how long the segment is and the source how long the file is.

Saying what happened

• install and app_run answer AO_AppMgr's verdict, not >ok once the request is posted: >err code=4 msg=busy, or >err code=5 msg=missing|empty|refused. install src="pending" with an empty mailbox says so and drops the request's flags.
• The write card and the LED follow the progress reports alone, and an https install made none until DNS, TLS and the headers were done. AO_AppMgr reports 0 % when the install is accepted and again every second while it waits on the network.
• A terminal install over BLE is dropped after 15 s without a chunk, not 5 s (the cable keeps 5 s), and the launch after run=on waits for the console's queued bytes to leave the link, so the >ok arrives before the reset.

Cost: taking a victim's CRC adds about 70 ms per MB to the step that evicts it (0.44 s for 6.2 MB), in the order of the verify at the end.

Test Scenarios

• tools/host_tests.sh and tools/check_layers.sh, green at this branch; tests/target built on v6.1 in its five variants with no warnings on the whole series.
• Two DVT boards, kodeOS built from this series, real apps from the store (2.9 to 4.2 MB):

What breaks	What the board does
Wi-Fi cut at 40 % of a download	install failed; the apps it had not reached are back, the one overwritten is named
Reset at 20 to 25 % with two victims	Boots, checks in 1.2 s, gives one back and names the other
16 installs reset at random points, 0 to 99 %	Boots every time with no watchdog; loses only the apps it names
Cable transfer stopped half way	Gives up after 5 s: the host is presumed gone
BLE transfer: client killed, or link dropped at 30 %	The same after 15 s, and advertises again
A second install while one runs	>err code=4 msg=busy; the first ends well
A file cut inside its first segment	Refused before anything is evicted
A file cut further on, or an image that claims more than it holds	Refused at the end in under 1 s, unhashed
An OS image cut short, as an update	Refused at the first chunk; the running slot does not change

• An earlier form of the reset recovery verified each victim with esp_image_verify() and put a board in a boot loop on the bench (the watchdog, at every boot, with the table still in NVS). The recovery in this change does not parse the image, and removes the table before it checks anything.
• Not tested: an install that reaches a board asleep on battery.

Related links

• An install from a file overwrites what is installed before the file is known to be whole #103: narrowed, not closed. A file cut or corrupt past its first segment still costs what it overwrote.
• The copy an eviction keeps on the card is written under its final name: a reset mid-copy leaves a cut image #104: this change makes a cut copy on the card no longer count as the app's copy; writing the copy under a temporary name is still open.
• An install down the wire evicts with no copy on the card, even with a card mounted #102 is unchanged: a terminal install still evicts with no copy on the card.