fix(recovery): make page reachability walks authoritative against reserved pages

Introduce a canonical page_space module defining the reserved page-id
range (headers + apply-journal) and use it everywhere a raw `< 4`
comparison stood in for it. collect_all_page_ids and its overflow-chain
walk now fail closed on any reference into reserved space or a chain
cycle instead of silently truncating, and deep-walk's diagnostic pass
gains the same structural coverage (leaf overflow chains, decode
failures) it was previously missing. Commit now panics rather than
proceeding if the post-commit reachability walk itself errors, since a
short reachable set would otherwise pass the freed-page check
vacuously.

Author: farhan-syah

src/btree/leaf.rs

@@ -2,6 +2,7 @@
 
 use crate::Result;
 use crate::errors::PagedbError;
+use crate::pager::page_space::is_reserved;
 
 use super::node::{
     HEADER_LEN, NodeHeader, NodeKind, OVERFLOW_SENTINEL, body_capacity, read_u16_le, read_u64_le,
@@ -157,7 +158,7 @@ impl Leaf {
                     root_page_id,
                 } => {
                     assert!(
-                        *root_page_id >= 4,
+                        !is_reserved(*root_page_id),
                         "encoding leaf record with wild overflow root_page_id={root_page_id} \
                          (reserved page — use-after-free / stale value)"
                     );

src/btree/tree/maintenance.rs

@@ -3,6 +3,7 @@
 use crate::Result;
 use crate::errors::PagedbError;
 use crate::pager::format::page_kind::PageKind;
+use crate::pager::page_space::is_reserved;
 use crate::vfs::Vfs;
 
 use crate::btree::leaf::{Leaf, LeafValue};
@@ -106,21 +107,39 @@ impl<V: Vfs> BTree<V> {
     /// Collect all page IDs reachable from this tree's root (internal nodes,
     /// leaves, overflow chains) into `out`. Used by the deep-walk integrity
     /// checker to identify orphan pages.
-    #[allow(clippy::too_many_lines)]
+    ///
+    /// Authoritative, not best-effort: `Ok(())` means every reachable node and
+    /// overflow page authenticated as its own kind, decoded structurally, and
+    /// pointed only at allocatable pages. Anything else is a corruption error,
+    /// because a partial set that its caller cannot distinguish from a complete
+    /// one turns every live page into a false orphan report — and, worse, reads
+    /// as a clean bill of health.
     pub async fn collect_all_page_ids(
         &self,
         out: &mut std::collections::BTreeSet<u64>,
     ) -> Result<()> {
         if self.root_page_id == 0 {
             return Ok(());
         }
-        let mut stack: Vec<u64> = vec![self.root_page_id];
+        // Track traversal separately from `out`. `out` is the caller's
+        // accumulator across every tree in the database and arrives pre-seeded
+        // with the reserved pages, so doubling it as the visited set would let
+        // whatever the caller happened to put in it silently truncate this
+        // walk — the walk's own progress must not depend on that.
+        let mut visited = std::collections::BTreeSet::new();
+        let mut stack: Vec<(u64, u64)> = vec![(0, self.root_page_id)];
 
-        while let Some(page_id) = stack.pop() {
-            if !out.insert(page_id) {
-                // Already visited.
+        while let Some((parent_page_id, page_id)) = stack.pop() {
+            if is_reserved(page_id) {
+                return Err(PagedbError::reserved_page_referenced(
+                    parent_page_id,
+                    page_id,
+                ));
+            }
+            if !visited.insert(page_id) {
                 continue;
             }
+            out.insert(page_id);
 
             let (guard, kind) = self.read_node_guard(page_id).await?;
             match kind {
@@ -137,19 +156,21 @@ impl<V: Vfs> BTree<V> {
                     drop(guard);
 
                     for overflow_root in overflow_roots {
-                        self.collect_overflow_chain(overflow_root, out).await?;
+                        self.collect_overflow_chain(page_id, overflow_root, &mut visited, out)
+                            .await?;
                     }
                 }
                 NodeKind::Internal => {
                     let internal = internal::Internal::decode(guard.body_ref())?;
                     drop(guard);
 
+                    // A zero child id is an absent slot, not a pointer.
                     if internal.leftmost_child != 0 {
-                        stack.push(internal.leftmost_child);
+                        stack.push((page_id, internal.leftmost_child));
                     }
                     for entry in &internal.entries {
                         if entry.right_child != 0 {
-                            stack.push(entry.right_child);
+                            stack.push((page_id, entry.right_child));
                         }
                     }
                 }
@@ -158,37 +179,55 @@ impl<V: Vfs> BTree<V> {
         Ok(())
     }
 
-    /// Walk an overflow chain starting at `root` and insert all page IDs into
-    /// `out`. This is authoritative for reachability collection, so malformed
-    /// pages or missing links propagate as corruption instead of being omitted.
+    /// Walk the overflow chain rooted at `root` — referenced by leaf
+    /// `leaf_page_id` — and insert every page ID into `out`.
+    ///
+    /// Authoritative on the same terms as [`Self::collect_all_page_ids`]. A
+    /// repeated page is reported as a cycle rather than treated as the end of
+    /// the chain: the two are indistinguishable to a caller that just stops
+    /// walking, and only one of them is a healthy tree.
+    ///
+    /// `visited` is the traversal's tree-wide page set. Overflow pages and node
+    /// pages draw from the same id space, so one set both deduplicates a chain
+    /// shared by several refcounting leaves and catches a chain that loops back
+    /// into the node graph.
     async fn collect_overflow_chain(
         &self,
+        leaf_page_id: u64,
         root: u64,
+        visited: &mut std::collections::BTreeSet<u64>,
         out: &mut std::collections::BTreeSet<u64>,
     ) -> Result<()> {
-        if root == 0 || !out.insert(root) {
+        // Unlike an internal child slot or a chain terminator, zero is not a
+        // valid overflow root: an `Overflow` leaf value always owns at least
+        // its root page.
+        if is_reserved(root) {
+            return Err(PagedbError::reserved_page_referenced(leaf_page_id, root));
+        }
+        if !visited.insert(root) {
+            // Already walked — a value whose chain is shared by refcount.
             return Ok(());
         }
+        out.insert(root);
 
-        let mut seen = std::collections::BTreeSet::new();
-        seen.insert(root);
         let info = overflow::read_root_page(&self.pager, self.realm_id, root).await?;
         let mut chain_id = info.next;
 
         while chain_id != 0 {
-            if !seen.insert(chain_id) {
-                return Err(PagedbError::corruption(
-                    crate::errors::CorruptionDetail::HeaderUnverifiable,
-                ));
+            if is_reserved(chain_id) {
+                return Err(PagedbError::reserved_page_referenced(root, chain_id));
+            }
+            if !visited.insert(chain_id) {
+                return Err(PagedbError::overflow_chain_cycle(root, chain_id));
             }
+            out.insert(chain_id);
 
             let guard = self
                 .pager
                 .read_main_page(chain_id, self.realm_id, PageKind::Overflow)
                 .await?;
             let body = guard.body();
             let (next, _) = overflow::decode_overflow(&body)?;
-            out.insert(chain_id);
             chain_id = next;
         }
 
@@ -208,7 +247,7 @@ impl<V: Vfs> BTree<V> {
         let mut stack: Vec<(u64, u64)> = vec![(0, self.root_page_id)];
         let mut seen = std::collections::BTreeSet::new();
         while let Some((parent, page_id)) = stack.pop() {
-            if page_id < 4 {
+            if is_reserved(page_id) {
                 return Some(format!(
                     "internal {parent} -> RESERVED child page {page_id}"
                 ));
@@ -234,56 +273,12 @@ impl<V: Vfs> BTree<V> {
                     return Some(format!("leaf {page_id} (parent {parent}) decode failed"));
                 };
                 for (k, v) in &leaf.records {
-                    if let LeafValue::Overflow { root_page_id, .. } = v {
-                        // Walk the FULL overflow chain: every page and every
-                        // next-pointer must be a real page (>= 4). A reserved or
-                        // unreadable link means a chain page was freed/reused
-                        // while still linked (use-after-free).
-                        let mut chain = *root_page_id;
-                        let mut first = true;
-                        let mut chain_seen = std::collections::BTreeSet::new();
-                        while chain != 0 {
-                            if chain < 4 {
-                                return Some(format!(
-                                    "leaf {page_id} (parent {parent}) key {:02x?} overflow chain \
-                                     -> RESERVED page {chain} (use-after-free)",
-                                    &k[..k.len().min(8)]
-                                ));
-                            }
-                            if !chain_seen.insert(chain) {
-                                return Some(format!(
-                                    "leaf {page_id} (parent {parent}) overflow chain CYCLE at {chain}"
-                                ));
-                            }
-                            // root (`OverflowRoot`): next after refcount[4];
-                            // chain page (`Overflow`): next at byte 0.
-                            let (kind, next_off, what) = if first {
-                                (PageKind::OverflowRoot, 4usize, "root")
-                            } else {
-                                (PageKind::Overflow, 0usize, "chain page")
-                            };
-                            first = false;
-                            let cg = match self
-                                .pager
-                                .read_main_page(chain, self.realm_id, kind)
-                                .await
-                            {
-                                Ok(cg) => cg,
-                                Err(e) => {
-                                    return Some(format!(
-                                        "leaf {page_id} (parent {parent}) overflow {what} {chain} \
-                                         UNREADABLE ({e:?}) — freed/reused"
-                                    ));
-                                }
-                            };
-                            let cbody = cg.body();
-                            if cbody.len() < next_off + 8 {
-                                break;
-                            }
-                            let mut b = [0u8; 8];
-                            b.copy_from_slice(&cbody[next_off..next_off + 8]);
-                            chain = u64::from_le_bytes(b);
-                        }
+                    if let LeafValue::Overflow { root_page_id, .. } = v
+                        && let Some(desc) = self
+                            .find_dangling_in_overflow(page_id, parent, k, *root_page_id)
+                            .await
+                    {
+                        return Some(desc);
                     }
                 }
             } else {
@@ -305,4 +300,69 @@ impl<V: Vfs> BTree<V> {
         }
         None
     }
+
+    /// Walk the full overflow chain rooted at `root` — held by key `key` in
+    /// leaf `page_id` — and describe the first anomaly, if any.
+    ///
+    /// Every page and every next-pointer must be allocatable. A reserved or
+    /// unreadable link means a chain page was freed and reused while still
+    /// linked. Zero terminates a chain but can never *be* one: an `Overflow`
+    /// value owns at least its root page.
+    async fn find_dangling_in_overflow(
+        &self,
+        page_id: u64,
+        parent: u64,
+        key: &[u8],
+        root: u64,
+    ) -> Option<String> {
+        let key_prefix = &key[..key.len().min(8)];
+        if root == 0 {
+            return Some(format!(
+                "leaf {page_id} (parent {parent}) key {key_prefix:02x?} overflow value has no \
+                 root page"
+            ));
+        }
+
+        let mut chain = root;
+        let mut first = true;
+        let mut chain_seen = std::collections::BTreeSet::new();
+        while chain != 0 {
+            if is_reserved(chain) {
+                return Some(format!(
+                    "leaf {page_id} (parent {parent}) key {key_prefix:02x?} overflow chain -> \
+                     RESERVED page {chain} (use-after-free)"
+                ));
+            }
+            if !chain_seen.insert(chain) {
+                return Some(format!(
+                    "leaf {page_id} (parent {parent}) overflow chain CYCLE at {chain}"
+                ));
+            }
+            // root (`OverflowRoot`): next after refcount[4];
+            // chain page (`Overflow`): next at byte 0.
+            let (kind, next_off, what) = if first {
+                (PageKind::OverflowRoot, 4usize, "root")
+            } else {
+                (PageKind::Overflow, 0usize, "chain page")
+            };
+            first = false;
+            let guard = match self.pager.read_main_page(chain, self.realm_id, kind).await {
+                Ok(guard) => guard,
+                Err(e) => {
+                    return Some(format!(
+                        "leaf {page_id} (parent {parent}) overflow {what} {chain} UNREADABLE \
+                         ({e:?}) — freed/reused"
+                    ));
+                }
+            };
+            let body = guard.body();
+            if body.len() < next_off + 8 {
+                break;
+            }
+            let mut next = [0u8; 8];
+            next.copy_from_slice(&body[next_off..next_off + 8]);
+            chain = u64::from_le_bytes(next);
+        }
+        None
+    }
 }

src/errors.rs

@@ -221,6 +221,18 @@ pub enum CorruptionDetail {
     },
     /// main.db A/B header HK-MAC failed on both copies.
     HeaderUnverifiable,
+    /// A live B+ tree or overflow pointer targets a reserved page (0..=3).
+    /// Pages 0 and 1 are the A/B structural headers and 2..=3 the apply-journal;
+    /// no live tree pointer may reach them, so this is a wild pointer or a
+    /// use-after-free that handed a reserved page back to an allocation.
+    ReservedPageReferenced {
+        parent_page_id: u64,
+        child_page_id: u64,
+    },
+    /// An overflow chain revisited a page it had already walked, so the chain
+    /// has no terminator. Distinct from a truncated chain: the links
+    /// authenticate, they just form a loop.
+    OverflowChainCycle { root_page_id: u64, page_id: u64 },
 }
 
 /// Quota failure reason, distinguishing which resource was exhausted.
@@ -267,6 +279,24 @@ impl PagedbError {
         Self::Corruption(CorruptionDetail::CatalogRowInvalid { field })
     }
 
+    /// Canonical constructor for a live tree pointer into a reserved page.
+    #[must_use]
+    pub const fn reserved_page_referenced(parent_page_id: u64, child_page_id: u64) -> Self {
+        Self::Corruption(CorruptionDetail::ReservedPageReferenced {
+            parent_page_id,
+            child_page_id,
+        })
+    }
+
+    /// Canonical constructor for a cyclic overflow chain.
+    #[must_use]
+    pub const fn overflow_chain_cycle(root_page_id: u64, page_id: u64) -> Self {
+        Self::Corruption(CorruptionDetail::OverflowChainCycle {
+            root_page_id,
+            page_id,
+        })
+    }
+
     /// Canonical constructor for an incremental snapshot that cannot be
     /// applied to this handle's current identity or reader-visible state.
     #[must_use]

src/pager/mod.rs

@@ -5,7 +5,9 @@ pub mod core;
 pub mod format;
 pub mod freelist;
 pub mod header;
+pub mod page_space;
 
 pub use cache::PageCache;
 pub use core::{FileKey, PageGuard, Pager, PagerConfig};
 pub use format::{data_page, page_kind::PageKind, segment_footer, structural_header};
+pub use page_space::{FIRST_ALLOCATABLE_PAGE_ID, is_reserved};

src/pager/page_space.rs

@@ -0,0 +1,26 @@
+//! Layout of main.db's page-id space.
+//!
+//! Page ids 0..=3 are reserved and never handed out by the allocator:
+//!
+//! | id | owner |
+//! | -- | ----- |
+//! | 0  | structural header, copy A |
+//! | 1  | structural header, copy B |
+//! | 2  | apply-journal root |
+//! | 3  | apply-journal spare |
+//!
+//! Everything from [`FIRST_ALLOCATABLE_PAGE_ID`] up is tree, overflow, or
+//! free-list territory. The distinction matters beyond bookkeeping: the
+//! structural headers use a different envelope (HK-MAC, cleartext) than data
+//! pages, so a live tree pointer that reaches one is a wild pointer or a
+//! use-after-free that recycled a reserved id — never a benign condition.
+
+/// First page id the allocator may hand out. Ids below this are reserved.
+pub const FIRST_ALLOCATABLE_PAGE_ID: u64 = 4;
+
+/// Whether `page_id` names a reserved page that no live tree pointer,
+/// overflow link, or free-list entry may reference.
+#[must_use]
+pub const fn is_reserved(page_id: u64) -> bool {
+    page_id < FIRST_ALLOCATABLE_PAGE_ID
+}