store_item can acknowledge an item that disappears after reboot

[enomado]

Summary

After two interrupted initial stores, a later uninterrupted MapStorage::store_item can return Ok(()), but a freshly reconstructed MapStorage cannot fetch the item and returns None.

I reproduced this directly on master at d10f0d517926c9b2303a1375f0da653443dec56a with the crate's own MockFlashBase; no external adapter is involved.

Minimal sequence

The flash geometry is two 128-byte pages with one-byte words, an uncached MapStorage<u8, ...>, key 0, and an eight-byte value.

1. Set bytes_until_shutoff = Some(7) and attempt the initial store. It returns EarlyShutoff.
2. Destroy and reconstruct MapStorage; fetching key 0 returns None.
3. Repeat steps 1–2 once.
4. Restore power and store a different value. store_item returns Ok(()).
5. Destroy and reconstruct MapStorage again.
6. Fetching key 0 returns None, despite the successful clean store.

Cause

ItemHeaderIter advances one flash word when it encounters a corrupted/torn header. find_next_free_item_spot then appends at the first erased byte following that header. Bytes from the new header can complete a valid-looking phantom header that starts inside the torn header and overlaps the new item. Traversal follows the phantom record and skips the actual item.

Expected behavior

An uninterrupted store_item that returns Ok(()) must remain visible after reconstructing the storage. If the flash state cannot be recovered safely, the store should return an error instead of acknowledging a non-durable item.

The regression test, a fix that rotates away from a page when the append scan encountered a corrupted header, and a new repeated power-cut/reboot fuzz target are submitted in #137.

[enomado]

and thanks for this library!

[enomado]

Follow-up with two measurements in case they're useful. AI-written, same as the original report — flagging it so you can apply your policy as you see fit.

1. Jumping a whole header instead of a word does fix it. Measured cost of the trade: with a 4-byte word and 12-byte items, one flipped bit in a header now also costs the item right after it (word-stepping recovered items 1..7, header-stepping recovers 2..7). The scan realigns within lcm(header_len, item_stride) bytes, so the loss is bounded rather than "the rest of the page".

2. More important, about the fuzz targets: teaching map.rs to do multiple shutoffs isn't enough on its own, because WORD_SIZE is hardcoded to 4 there. An 8-byte header on a 4-byte word can only ever be torn in the middle, so completing a phantom needs a 2^-16 coincidence; on a 1-byte word it can be torn at 7 offsets, and the byte the torn header is missing is one whose low half already matches, so it's 2^-8. Measured against the unfixed code: a reboot op (drop the cache, rebuild from flash, verify against the model, arm the next shutoff) at WORD_SIZE=4 with a u16 shutoff budget found nothing in 134k runs / 300s. The same target over word sizes 1/2/4 with a u8 budget reproduces it inside 300s — it surfaces as NotWritable, since the misplaced append lands on already-written words.