refactor(api): shrink public surface to the supported crate root

Make every internal module (btree, catalog, crypto, pager, realm,
recovery, segment, snapshot, txn) `pub(crate)` instead of `pub`, so
embedders can only reach the curated set of re-exports at the crate
root plus `options` and `vfs`. Update every dependent test, benchmark,
and doc link to go through the new re-export paths, drop the unused
`rekey_into_writer` stub that the narrower surface no longer needs,
and mark the deep-walk report structs `#[non_exhaustive]` now that
they're the only public window into recovery findings.

Integration tests that relied on internal access no longer compile
as a separate crate, so they move into `#[cfg(test)] mod tests`
submodules alongside the code they exercise; the remaining
`tests/` files are updated to use the public API only.

Author: farhan-syah

.config/nextest.toml

@@ -15,17 +15,16 @@ test-threads = "num-cpus"
 filter = """
     binary(crash_basic)
     | binary(recovery_basic)
-    | binary(rekey_basic)
     | binary(fsck_deep)
     | binary(durability)
-    | binary(snapshot_basic)
     | binary(compaction_basic)
     | binary(compaction_incremental)
     | binary(deferred_free_reclaim)
     | binary(reader_stall_policy)
     | (binary(pagedb) & (
         test(/crash/) | test(/recover/) | test(/rekey/)
         | test(/anchor/) | test(/torn/) | test(/journal/) | test(/replay/)
+        | test(/snapshot/) | test(/metadata_errors/)
     ))
 """
 test-group = "serial"

benchmarks/engine-comparison/btree.rs

@@ -21,12 +21,10 @@ use fluxbench::prelude::*;
 use fluxbench::{bench, compare, synthetic, verify};
 use tokio::sync::Mutex as AsyncMutex;
 
-use pagedb::crypto::CipherId;
-use pagedb::options::{OpenOptions, RetainPolicy};
 use pagedb::vfs::Vfs;
 use pagedb::vfs::memory::MemVfs;
 use pagedb::vfs::tokio_backend::TokioVfs;
-use pagedb::{Db, RealmId};
+use pagedb::{CipherId, Db, OpenOptions, RealmId, RetainPolicy};
 
 const PAGE: usize = 4096;
 /// Working-set size: number of keys preloaded for read benches and the

src/btree/internal.rs

@@ -125,19 +125,6 @@ impl Internal {
         Ok(())
     }
 
-    /// Descend selection: returns the child `page_id` covering `key`.
-    #[must_use]
-    pub fn child_for(&self, key: &[u8]) -> u64 {
-        // Binary search for the rightmost entry where entry.key <= key.
-        // Using partition_point: find the first index where entry.key > key.
-        let pos = self.entries.partition_point(|e| e.key.as_slice() <= key);
-        if pos == 0 {
-            self.leftmost_child
-        } else {
-            self.entries[pos - 1].right_child
-        }
-    }
-
     #[must_use]
     pub fn fits(&self, page_size: usize) -> bool {
         let cap = body_capacity(page_size);
@@ -222,8 +209,9 @@ impl<'a> InternalAccessor<'a> {
         read_u64_le(self.body, off + 2 + key_len)
     }
 
-    /// Descend selection: returns the child `page_id` covering `query`. Matches
-    /// the semantics of [`Internal::child_for`] but operates on borrowed bytes.
+    /// Descend selection: returns the child `page_id` covering `query`. Reads
+    /// the slot directory in place, so descending a spine never materializes
+    /// the node's keys.
     #[must_use]
     pub fn child_for(&self, query: &[u8]) -> u64 {
         // Rightmost index where entry.key <= query. Use partition_point logic

src/btree/leaf.rs

@@ -301,11 +301,6 @@ impl<'a> LeafAccessor<'a> {
         })
     }
 
-    #[must_use]
-    pub fn slot_count(&self) -> usize {
-        self.slot_count
-    }
-
     fn prefix(&self) -> &'a [u8] {
         &self.body[HEADER_LEN..HEADER_LEN + self.prefix_len]
     }
@@ -361,23 +356,22 @@ impl<'a> LeafAccessor<'a> {
 
     /// Decode the value at slot `idx`. Inline values borrow from the page body;
     /// overflow values return only the chain root + total length.
-    pub fn value_at(&self, idx: usize) -> Result<LeafValueRef<'a>> {
+    #[must_use]
+    pub fn value_at(&self, idx: usize) -> LeafValueRef<'a> {
         let off = slot_offset(self.body, self.prefix_len, idx);
         let suffix_len = read_u16_le(self.body, off) as usize;
         let after_key = off + 2 + suffix_len;
         let value_len_raw = read_u16_le(self.body, after_key);
         if value_len_raw == OVERFLOW_SENTINEL {
             let total_len = read_u64_le(self.body, after_key + 2);
             let root_page_id = read_u64_le(self.body, after_key + 2 + 8);
-            Ok(LeafValueRef::Overflow {
+            LeafValueRef::Overflow {
                 total_len,
                 root_page_id,
-            })
+            }
         } else {
             let vlen = value_len_raw as usize;
-            Ok(LeafValueRef::Inline(
-                &self.body[after_key + 2..after_key + 2 + vlen],
-            ))
+            LeafValueRef::Inline(&self.body[after_key + 2..after_key + 2 + vlen])
         }
     }
 }

src/btree/mod.rs

@@ -1,11 +1,15 @@
 //! `CoW` B+ tree (Layer 3a): sorted `bytes→bytes` table over the Pager.
 
-pub mod internal;
-pub mod leaf;
-pub mod node;
-pub mod overflow;
-pub mod scan;
-pub mod split;
-pub mod tree;
+pub(crate) mod internal;
+pub(crate) mod leaf;
+pub(crate) mod node;
+pub(crate) mod overflow;
+pub(crate) mod scan;
+pub(crate) mod split;
+#[cfg(test)]
+mod tests;
+pub(crate) mod tree;
 
+// `pub` here is crate-scoped in effect: the `btree` module itself is
+// `pub(crate)`, so this does not escape the crate.
 pub use tree::BTree;

src/btree/overflow.rs

@@ -4,9 +4,12 @@
 //! `next` pointer (page id, 0 = end of chain) followed by raw data bytes.
 //!
 //! - Root page (`PageKind::OverflowRoot`): `refcount[4] || next[8] || data_len[4] || data`.
-//!   The `refcount: u32` enables shared chains — `increment_ref` CoW-copies the
-//!   root with `refcount + 1`; `release` CoW-copies it with `refcount - 1` and,
-//!   when it reaches 0, frees the entire chain.
+//!   `release` CoW-copies the root with `refcount - 1` and, when it reaches 0,
+//!   frees the entire chain. Snapshot lifetime does not rely on the count:
+//!   copy-on-write leaves that still name a chain are protected because commit
+//!   tags every freed page and reclamation waits until no retained root or live
+//!   reader can reach it. Nothing in this crate raises a count above 1, so the
+//!   decrement branch only fires for a root written by some other producer.
 //! - Chain page (`PageKind::Overflow`): `next[8] || data_len[4] || data`.
 //!
 //! The two layouts differ only in the root's 4-byte `refcount` prefix, so the
@@ -218,37 +221,11 @@ pub async fn write_chain<V: Vfs>(
     Ok(page_ids[0])
 }
 
-/// Increment the reference count of an overflow root page. Writes a new `CoW`
-/// copy of the root at `new_page_id` with `refcount + 1`. The caller is
-/// responsible for allocating `new_page_id` and freeing the old root page when
-/// appropriate.
-///
-/// Returns the new root page id (`new_page_id`).
-pub async fn increment_ref<V: Vfs>(
-    pager: &Pager<V>,
-    realm_id: RealmId,
-    root_page_id: u64,
-    new_page_id: u64,
-) -> Result<u64> {
-    let page_size = pager.page_size();
-    let info = read_root_page(pager, realm_id, root_page_id).await?;
-    let new_refcount = info
-        .refcount
-        .checked_add(1)
-        .ok_or_else(|| PagedbError::Io(std::io::Error::other("overflow refcount overflow")))?;
-    let mut body = vec![0u8; page_size - ENVELOPE_OVERHEAD];
-    encode_overflow_root(&mut body, new_refcount, info.next, &info.root_data)?;
-    pager
-        .write_main_page(new_page_id, realm_id, PageKind::OverflowRoot, &body)
-        .await?;
-    Ok(new_page_id)
-}
-
 /// The result of a `release` call.
 pub enum ReleaseResult {
-    /// Refcount decremented; new root page written at `new_root_page_id`.
-    /// The caller must free `old_root_page_id`.
-    Decremented { new_root_page_id: u64 },
+    /// Refcount decremented; the decremented root was written to the caller's
+    /// `new_page_id`. The caller must free the old root page.
+    Decremented,
     /// Refcount reached 0; all chain pages are listed in `freed_pages`
     /// (including the original root). The caller must free them all.
     Freed { freed_pages: Vec<u64> },
@@ -297,9 +274,7 @@ pub async fn release<V: Vfs>(
     pager
         .write_main_page(new_page_id, realm_id, PageKind::OverflowRoot, &body)
         .await?;
-    Ok(ReleaseResult::Decremented {
-        new_root_page_id: new_page_id,
-    })
+    Ok(ReleaseResult::Decremented)
 }
 
 /// Read a value's overflow chain via the Pager. Follows `next` pointers until 0.

tests/btree_basic.rs src/btree/tests/basic.rstests/btree_basic.rs renamed to src/btree/tests/basic.rs

@@ -2,17 +2,17 @@ use std::sync::Arc;
 use std::sync::mpsc;
 use std::time::Duration;
 
-use pagedb::btree::BTree;
-use pagedb::btree::internal::{Internal, InternalEntry};
-use pagedb::btree::leaf::{Leaf, LeafValue};
-use pagedb::btree::node::body_capacity;
-use pagedb::btree::overflow::encode_overflow;
-use pagedb::crypto::CipherId;
-use pagedb::crypto::kdf::derive_mk;
-use pagedb::errors::CorruptionDetail;
-use pagedb::pager::{PageKind, Pager, PagerConfig};
-use pagedb::vfs::memory::MemVfs;
-use pagedb::{PagedbError, RealmId};
+use crate::btree::BTree;
+use crate::btree::internal::{Internal, InternalEntry};
+use crate::btree::leaf::{Leaf, LeafValue};
+use crate::btree::node::body_capacity;
+use crate::btree::overflow::encode_overflow;
+use crate::crypto::CipherId;
+use crate::crypto::kdf::derive_mk;
+use crate::errors::CorruptionDetail;
+use crate::pager::{PageKind, Pager, PagerConfig};
+use crate::vfs::memory::MemVfs;
+use crate::{PagedbError, RealmId};
 
 const PAGE: usize = 4096;
 
@@ -377,7 +377,7 @@ async fn read_node_rejects_authenticated_envelope_body_kind_mismatch() {
 /// the body was structurally validated at parse time.
 #[tokio::test(flavor = "current_thread")]
 async fn malformed_node_body_reports_corruption_instead_of_panicking() {
-    use pagedb::btree::node::{HEADER_LEN, NodeKind, write_header, write_slot_offset};
+    use crate::btree::node::{HEADER_LEN, NodeKind, write_header, write_slot_offset};
 
     let capacity = body_capacity(PAGE);
 

tests/generated_btree_nodes.rs src/btree/tests/generated_nodes.rstests/generated_btree_nodes.rs renamed to src/btree/tests/generated_nodes.rs

@@ -14,9 +14,9 @@
 //! out-of-bounds index. A `proptest` failure here is the panic being reported
 //! with the smallest input that still triggers it.
 
-use pagedb::btree::internal::{Internal, InternalEntry};
-use pagedb::btree::leaf::{Leaf, LeafValue};
-use pagedb::btree::node::{
+use crate::btree::internal::{Internal, InternalEntry};
+use crate::btree::leaf::{Leaf, LeafValue};
+use crate::btree::node::{
     HEADER_LEN, NodeKind, OFF_PREFIX_LEN, OFF_SLOT_COUNT, body_capacity, validate_node_body,
 };
 use proptest::prelude::*;

tests/generated_overflow_chains.rs …btree/tests/generated_overflow_chains.rstests/generated_overflow_chains.rs renamed to src/btree/tests/generated_overflow_chains.rs tests/generated_overflow_chains.rs renamed to src/btree/tests/generated_overflow_chains.rs

@@ -16,16 +16,16 @@ use std::sync::mpsc;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
-use pagedb::RealmId;
-use pagedb::btree::overflow::{
+use crate::RealmId;
+use crate::btree::overflow::{
     OVERFLOW_ROOT_HEADER_LEN, collect_chain, decode_overflow, encode_overflow,
     overflow_page_capacity, overflow_root_capacity, read_chain, read_root_page,
 };
-use pagedb::crypto::CipherId;
-use pagedb::crypto::kdf::derive_mk;
-use pagedb::pager::format::data_page::ENVELOPE_OVERHEAD;
-use pagedb::pager::{PageKind, Pager, PagerConfig};
-use pagedb::vfs::memory::MemVfs;
+use crate::crypto::CipherId;
+use crate::crypto::kdf::derive_mk;
+use crate::pager::format::data_page::ENVELOPE_OVERHEAD;
+use crate::pager::{PageKind, Pager, PagerConfig};
+use crate::vfs::memory::MemVfs;
 use proptest::prelude::*;
 use proptest::test_runner::{TestCaseResult, TestRunner};
 

tests/generated_structural_walks.rs …tree/tests/generated_structural_walks.rstests/generated_structural_walks.rs renamed to src/btree/tests/generated_structural_walks.rs tests/generated_structural_walks.rs renamed to src/btree/tests/generated_structural_walks.rs

@@ -17,15 +17,15 @@ use std::sync::mpsc;
 use std::sync::{Arc, Mutex};
 use std::time::Duration;
 
-use pagedb::RealmId;
-use pagedb::btree::BTree;
-use pagedb::btree::internal::{Internal, InternalEntry};
-use pagedb::btree::leaf::{Leaf, LeafValue};
-use pagedb::btree::node::body_capacity;
-use pagedb::crypto::CipherId;
-use pagedb::crypto::kdf::derive_mk;
-use pagedb::pager::{PageKind, Pager, PagerConfig};
-use pagedb::vfs::memory::MemVfs;
+use crate::RealmId;
+use crate::btree::BTree;
+use crate::btree::internal::{Internal, InternalEntry};
+use crate::btree::leaf::{Leaf, LeafValue};
+use crate::btree::node::body_capacity;
+use crate::crypto::CipherId;
+use crate::crypto::kdf::derive_mk;
+use crate::pager::{PageKind, Pager, PagerConfig};
+use crate::vfs::memory::MemVfs;
 use proptest::prelude::*;
 use proptest::test_runner::{TestCaseResult, TestRunner};