docs: SWMR reader (range-read M5) in CHANGELOG, README, known issues and designs

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

docs/known-issues.md

@@ -7,6 +7,29 @@ deleting it.
 
 ---
 
+## Files a SWMR writer had open could not be read past a stale end of file
+
+**Status:** fixed 2026-09-27 (branch `feat/p3-m5-swmr-reader`), before any
+release: reads have been bounded by the recorded end of file since
+`7d7a7e7` (2026-09-26), which no release contains.
+
+A libhdf5 writer in SWMR mode (h5py `f.swmr_mode = True`) sets the
+superblock's SWMR-write flag and does not keep its end-of-file address up to
+date: a copy h5py made of its own file mid-write records 715 in a
+6 030-byte file (h5py 3.16 / HDF5 2.0, tank). `Superblock::data_end` only
+ignored the recorded end when it lay *past* the end of the file, so every
+reader bounded such a file at 715 bytes: it listed, but every chunked read
+failed ("unexpected EOF: need 787 bytes, have 715") and `h5rs check`
+reported the chunk indexes past the end of the file. Never wrong data.
+
+**Fix:** for a v3 superblock with the SWMR-write flag, the data ends at the
+end of the file, as libhdf5's SWMR reader reads it. **Test:**
+`crates/clawhdf5/tests/swmr_interop.rs` (the mid-write copy,
+`tests/fixtures/swmr_mid_write.h5`, through every open path and against
+h5py's SWMR reader). A file still being written is read with
+`File::open_swmr` (see `docs/design/swmr.md`); `File::open` maps the file
+at its length at open and is not meant for files that change while open.
+
 ## Fletcher-32 checksums disagreed with libhdf5 on about 1 chunk in 32768
 
 **Status:** fixed 2026-09-26, after v2.7.0. **Every release (v2.1.0 to