[rntuple] Keep and verify page checksums

[sathabbott]

🤖 AI generated content

Fixes #55. Its tests use rntuple/map.root and rntuple/compressed.root, from #124 (merged).

A page whose fNElements is negative has an XXH3-64 checksum right after it: 8 bytes, little-endian, over the stored (sealed, possibly compressed) bytes. The locator's size excludes it; ROOT's reader adds the 8 bytes back itself (RPageStorage.cxx:297, root-io-spec NOTES 4).

RPageDescription stays the page's locator, as on main, and now covers the checksum:

• fNElements stays as stored. Its sign is the checksum flag, and the stored value is what lets bytes be reproduced.
• New: n_elements (absolute value) and has_checksum (fNElements < 0).
• size is the number of bytes to fetch: locator.size, plus 8 when the page has a checksum (as suggested earlier in [rntuple] Store page checksums #55). The spec's page size, which excludes the checksum, stays in locator.size.
• read_from splits off the trailer, verifies the XXH3-64 and returns an RPage. A buffer of the wrong length raises. get_page goes through it, so every existing path verifies.

The checksum check depends only on the fetched bytes, and the RLocator is kept as is, so nothing here assumes how or from where a page is fetched. That leaves room for the locator types the spec reserves (0x02–0x7f).

RPage gains checksum: int | None. The page bytes are still the stored bytes; nothing is decompressed.

PageListEnvelope.page_locators is unchanged. It returns RPageDescriptions, so test_read.py's walk now verifies every checksum.

Tests (tests/test_page_checksums.py):

• rntuple/anchor.root, the page at 550: fNElements = -3, locator.size 12, size 20, checksum de3ce2c4a5a407be at 562, equal to XXH3-64 of bytes 550–562;
• a flipped byte raises Page checksum mismatch at StandardLocator(size=12, offset=550); a buffer of the wrong length raises; a page without a checksum reads with checksum=None;
• every page of all 11 root-io-spec RNTuple fixtures verifies, including compressed.root's compressed pages and map.root's shared ranges (page descriptions that name the same bytes, which is common: same-page merging is on by default, root-io-spec NOTES 7).

Full suite, on current main (after #130): 471 passed, 61 skipped, 50 xfailed.

Behaviour change: RPageDescription.size includes the 8-byte checksum when there is one, and read_from expects those bytes; use locator.size for the page's own size.

Assisted-by: claude-code:claude-opus-5-5

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.51%. Comparing base (1f9f492) to head (94c6b00).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #128      +/-   ##
==========================================
+ Coverage   92.40%   92.51%   +0.11%     
==========================================
  Files          37       37              
  Lines        2975     2994      +19     
==========================================
+ Hits         2749     2770      +21     
+ Misses        226      224       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sathabbott]

@nsmith- i reviewed this and think it is ready to merge. this looks a lot cleaner than before

[nsmith-]

Ok, and the RPageLocator will follow the Locator protocol (and RPageDescription will gain a page_locator or similar method) once we return to #114 for standard locators. For non-standard, the RPageLocator will have some other shape.