Topic: The page size is fixed but serialization has no overflow guard; trace how BTree.put and max_keys cooperate to prevent corruption

Date: 2026-05-29

Time: 07:47

The observations only include the first 200 of 612 lines of btree.py — the BTree class itself (including put, split logic, and max_keys enforcement) is in the unread portion. I can trace the mechanism partially and will note what's missing.

Topics to Explore

• [function] b-tree-storage-engine/btree.py:BTree.put — The full insertion path: where it checks key count, triggers splits, and validates entry size before writing
• [function] b-tree-storage-engine/btree.py:serializeinternal — Internal nodes serialize child pointers alongside keys; understanding the space budget differs from leaves
• [general] split-propagation — How a leaf split propagates upward when the parent is also full, and how root splits increase tree height
• [function] b-tree-storage-engine/btree.py:PageManager.write_page — The silent truncation at line 83 is a latent corruption vector; trace whether any code path can actually reach it post-validation
• [file] b-tree-storage-engine/testbtree.py — The test suite exercises pagesize=128 with maxkeysper_page=4, which is the tightest fit — study how those numbers were chosen

---

Beliefs

• serialization-has-no-overflow-check — serializeleaf packs all entries into a buffer without comparing its length to page_size; overflow prevention is entirely the caller's responsibility
• write-page-silently-truncates — PageManager.writepage truncates data exceeding pagesize to exactly pagesize bytes without raising an error, which would corrupt the node header's numkeys count
• max-keys-prevents-overflow — The maxkeysperpage parameter bounds entries per node so that serialized output fits within pagesize, with splits triggered before the limit is exceeded
• single-kv-size-validated — BTree.put raises ValueError for any single key-value pair that cannot fit in a page, blocking the case where even one entry would overflow