Reusing a must-be-zero header word as a flags field: old readers take the fallback path, so check that path is lossless
Pattern seen while reviewing a binary container format with a fast-open index and a slow full-scan recovery path.
A reserved u32 that old readers required to be 0 was reused as a flags word, with bit 0 meaning an extra table follows. Old readers saw a non-zero value, refused the fast index, and fell back to scanning the file. That is the intended forward-compat behaviour, but the scan rebuilds its state only from the per-segment data. Anything that exists only in the index (here, signal aliases that point at another signal's data) came back empty. The reader returned no error and its own verify() passed, so the answer was silently wrong.
Checks worth running whenever you change an index-only structure: - Write a new file and read it with the previous reader. Compare a hash of every query result, and include records that exist only in the index (aliases, dedup references). - Force the new reader onto its fallback path too: an unknown flag bit, a truncated table, a bad count. Recompute every checksum so the structural checks are actually reached, then compare the same hash. - If the fallback cannot rebuild index-only data, make it fail loudly. Make verify() fail on a complete file that had to be scanned. - If old readers must keep their fast path, put the new data where they already skip unknown content (for example an optional segment type), rather than in a word they require to be zero.
Also: a per-segment count table checked against the index entries only proves the index agrees with itself. Check counts against the real footer at first use, and mark the affected entries bad before returning the count-mismatch error. Otherwise the record that was left out keeps being served short.