docs(persistence): document module and refine FAT recovery to two cases

Record that persistence is now implemented and hardware-verified, and correct
the crash-recovery rule everywhere it appeared as "just promote the tmp": a
crash during the tmp write leaves a partial tmp, so recovery keeps the
committed target when both files are present and only promotes the tmp when
the target was already unlinked. Also fix the stale README heading that still
said the SD was on shared SPI2.
This commit is contained in:
Julien Calixte
2026-07-11 12:02:30 +02:00
parent 1e3220a95f
commit 7a1f25f5d1
4 changed files with 46 additions and 19 deletions

View File

@@ -163,11 +163,18 @@ in [qfd.md §3](qfd.md#3-house-of-quality--whats--hows).
Storage split rationale:
[ADR-007](adr.md#adr-007-storage-split--fat-on-sd-for-working-copy-littlefs-on-flash-for-config).
- Atomic save: write to `notes.md.tmp`, fsync, rename. We accept FAT's
weakness here; on power loss between rename and dir flush, the user gets
the previous version, which is the documented behavior.
Implemented in [`firmware::persistence`](../firmware/src/persistence.rs)
(`Storage::{mount, load, save, recover}`), graduated from Spike 3 and
hardware-verified 2026-07-11.
- Atomic save: write to `notes.md.tmp`, fsync, unlink the target (FatFS
`f_rename` won't overwrite — ADR-007), rename. On power loss the user gets
the previous version, the documented behavior. Boot recovery reconciles a
leftover `*.tmp`: kept-target-if-both-present, promote-if-target-gone (see
ADR-007 for why "just promote" is unsafe).
- The file is read fully into the rope at boot. v0.1 caps file size at
256 KB; larger files refuse to open with a clear message.
256 KB; larger files refuse to open with a clear message. Saving is not
capped — the buffer is always persistable.
### `wifi` — on-demand station