From 8598b813bd4c21a95e25e737ad0668580620beba Mon Sep 17 00:00:00 2001 From: GitHub Copilot Date: Mon, 31 Aug 2026 10:35:02 +0000 Subject: [PATCH] Add issue #459 note --- ISSUE_459.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 ISSUE_459.md diff --git a/ISSUE_459.md b/ISSUE_459.md new file mode 100644 index 00000000..671a7f43 --- /dev/null +++ b/ISSUE_459.md @@ -0,0 +1,33 @@ +# Issue #459 + +## Title +Factory paged-index offset math is easy to get subtly wrong. + +## Summary +The factory paged index mixes legacy cursor metadata with logical offsets and page-size boundaries. A small arithmetic mistake can silently move reads or appends to the wrong page or offset, especially when a legacy cursor is non-zero and the logical index has crossed into the newly appended pages. + +## Risk +This is subtle because the code appears correct at a glance, but the combination of: +- legacy_count +- legacy cursor +- logical offset +- page size (100) + +can produce off-by-one or page-boundary errors when the index spans legacy and paged storage. + +## Desired invariant +For any valid triple of `(legacy_count, cursor, logical)`: +- the computed physical offset must be monotonic as `logical` increases +- the physical offset must remain in range for the current index layout +- when `logical` is still in the legacy portion, the offset should remain the logical offset +- when `logical` crosses into appended pages, the offset should advance by the legacy-page alignment offset + +## Suggested validation +Add property-based tests over `(legacy_count, cursor, logical)` triples checking that the physical offset: +- is monotonic for increasing logical values +- stays within the range of the migrated/paged index +- never moves backward when the cursor advances +- remains consistent with the page-size boundary math + +## Notes +This issue is specifically about the subtle arithmetic around the legacy cursor plus page-size migration math, and should be protected by proptest coverage to prevent regressions.