test: add property-based coverage for on-disk decoders and pointer walks

Add proptest as a dev-dependency and generate adversarial input for the
decoders that turn already-authenticated bytes into structural claims
(B+ tree nodes, extent index entries, catalog rows, commit-history rows,
journal records, snapshot artifacts, page envelopes, native path
resolution) plus the pointer graphs fed to the B+ tree and free-list
walks. Hand-written regressions only cover shapes someone already
imagined; these properties assert every case returns a typed error or a
value, never a panic, and cover the rest of the space.

Author: farhan-syah

Cargo.toml

@@ -142,6 +142,11 @@ tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
 tempfile = "3"
 aes-gcm = "0.10"
 fluxbench = "0.1"
+# Generated adversarial input for the decoders and the structural walks. Runs
+# inside the normal `cargo nextest` suite on every Tier-1 target, which is why
+# it is proptest and not a nightly-only libFuzzer harness. Dev-only: it must
+# never reach the published surface or the default feature set.
+proptest = "1.11"
 
 [[bin]]
 name = "pagedb-fsck"

src/segment/authenticated_metadata/tests.rs

@@ -471,3 +471,123 @@ async fn missing_persisted_epoch_key_has_deterministic_error() {
         })
     ));
 }
+
+/// Generated adversarial input for the extent-index page decoder.
+///
+/// An index page body is a run of fixed-width entries whose `start_page_id`,
+/// `page_count`, ordering, reserved bytes, and zero-tail placement are all
+/// structural claims made by authenticated bytes. The validator is reached only
+/// through a `pub(crate)` path that needs a real pager and a real segment file,
+/// so it has no integration surface — and widening its visibility to give it
+/// one would enlarge the published API to serve a test. The property lives
+/// beside the code instead.
+mod generated {
+    use proptest::prelude::*;
+
+    use super::super::validate_index_entries;
+    use crate::segment::types::{EXTENT_INDEX_ENTRY_LEN, ExtentIndexEntry};
+
+    fn cases() -> u32 {
+        std::env::var("PAGEDB_PROPTEST_CASES")
+            .ok()
+            .and_then(|raw| raw.parse().ok())
+            .unwrap_or(32)
+    }
+
+    fn config() -> ProptestConfig {
+        ProptestConfig {
+            cases: cases(),
+            failure_persistence: None,
+            ..ProptestConfig::default()
+        }
+    }
+
+    /// Drive one generated page body through the validator the way
+    /// `decode_extent_index` does, carrying the same cross-page state.
+    fn validate(page_body: &[u8], index_start_page: u64) -> crate::Result<Vec<ExtentIndexEntry>> {
+        let mut previous_end = 0u64;
+        let mut unused_tail = false;
+        let mut entries = Vec::new();
+        validate_index_entries(
+            page_body,
+            index_start_page,
+            &mut previous_end,
+            &mut unused_tail,
+            &mut entries,
+        )?;
+        Ok(entries)
+    }
+
+    proptest! {
+        #![proptest_config(config())]
+
+        /// Wholly random bodies, at lengths that straddle the entry stride so
+        /// the ragged-remainder path is reached from both sides.
+        #[test]
+        fn random_index_page_bodies_never_panic(
+            body in prop::collection::vec(any::<u8>(), 0..=(EXTENT_INDEX_ENTRY_LEN * 4 + 7)),
+            index_start_page in any::<u64>(),
+        ) {
+            let _ = validate(&body, index_start_page);
+        }
+
+        /// Structurally plausible entries: correct stride and zero reserved
+        /// bytes, with the two fields that bound a page range left hostile.
+        #[test]
+        fn plausible_entries_are_accepted_only_when_every_claim_holds(
+            entries in prop::collection::vec(
+                (any::<u64>(), any::<u32>(), any::<u64>()),
+                0..=4,
+            ),
+            trailing_zero_entries in 0usize..=2,
+            index_start_page in prop_oneof![Just(0u64), Just(1u64), 1u64..64, any::<u64>()],
+        ) {
+            let mut body = Vec::new();
+            for &(start_page_id, page_count, logical_bytes) in &entries {
+                body.extend_from_slice(&ExtentIndexEntry {
+                    start_page_id,
+                    page_count,
+                    logical_bytes,
+                }.encode());
+            }
+            for _ in 0..trailing_zero_entries {
+                body.extend_from_slice(&[0u8; EXTENT_INDEX_ENTRY_LEN]);
+            }
+
+            let Ok(decoded) = validate(&body, index_start_page) else {
+                return Ok(());
+            };
+            // Acceptance is a promise about the whole run, not one entry:
+            // extents are non-empty, in range, and non-overlapping in order.
+            let mut previous_end = 0u64;
+            for entry in &decoded {
+                prop_assert!(entry.start_page_id != 0);
+                prop_assert!(entry.page_count != 0);
+                prop_assert!(entry.start_page_id >= previous_end);
+                let end = entry
+                    .start_page_id
+                    .checked_add(u64::from(entry.page_count))
+                    .expect("an accepted extent cannot overflow its own end");
+                prop_assert!(end <= index_start_page);
+                previous_end = end;
+            }
+        }
+
+        /// A zero entry marks the unused tail. Anything after it is a page that
+        /// two different writers could have produced, so it must be refused.
+        #[test]
+        fn a_live_entry_after_the_zero_tail_is_refused(
+            leading_zero_entries in 1usize..=3,
+            start_page_id in 1u64..64,
+            page_count in 1u32..8,
+        ) {
+            let mut body = vec![0u8; leading_zero_entries * EXTENT_INDEX_ENTRY_LEN];
+            body.extend_from_slice(&ExtentIndexEntry {
+                start_page_id,
+                page_count,
+                logical_bytes: 0,
+            }.encode());
+            prop_assert!(validate(&body, u64::MAX).is_err());
+        }
+    }
+}

src/txn/db/core.rs

@@ -503,3 +503,78 @@ pub(crate) fn decode_commit_meta(bytes: &[u8]) -> Result<CommitHistoryMeta> {
         unix_seconds: read_u64(bytes, 32),
     })
 }
+
+/// Generated adversarial input for the commit-history row decoder.
+///
+/// The row is reached through a `pub(crate)` path, so it has no integration
+/// surface to test from — widening its visibility to make it reachable would
+/// enlarge the published API to serve a test, which is the wrong trade. The
+/// property lives beside the code instead.
+#[cfg(test)]
+mod tests {
+    use proptest::prelude::*;
+
+    use super::{CommitHistoryMeta, decode_commit_meta, encode_commit_meta};
+
+    const META_LEN: usize = 40;
+
+    fn cases() -> u32 {
+        std::env::var("PAGEDB_PROPTEST_CASES")
+            .ok()
+            .and_then(|raw| raw.parse().ok())
+            .unwrap_or(32)
+    }
+
+    fn config() -> ProptestConfig {
+        ProptestConfig {
+            cases: cases(),
+            failure_persistence: None,
+            ..ProptestConfig::default()
+        }
+    }
+
+    proptest! {
+        #![proptest_config(config())]
+
+        /// A short row must be declined, never sliced. Trailing bytes are
+        /// tolerated by design (the row is a fixed prefix), so acceptance is
+        /// exactly "at least the fixed width".
+        #[test]
+        fn random_bytes_are_accepted_only_at_or_above_the_fixed_width(
+            bytes in prop::collection::vec(any::<u8>(), 0..=(META_LEN + 16)),
+        ) {
+            match decode_commit_meta(&bytes) {
+                Ok(_) => prop_assert!(bytes.len() >= META_LEN),
+                Err(_) => prop_assert!(bytes.len() < META_LEN),
+            }
+        }
+
+        #[test]
+        fn encoded_rows_round_trip_for_every_field_value(
+            active_root_page_id in any::<u64>(),
+            catalog_root_page_id in any::<u64>(),
+            free_list_root_page_id in any::<u64>(),
+            next_page_id in any::<u64>(),
+            unix_seconds in any::<u64>(),
+            trailing in prop::collection::vec(any::<u8>(), 0..=16),
+        ) {
+            let meta = CommitHistoryMeta {
+                active_root_page_id,
+                catalog_root_page_id,
+                free_list_root_page_id,
+                next_page_id,
+                unix_seconds,
+            };
+            let mut encoded = encode_commit_meta(&meta);
+            // A longer row is what a future format revision looks like from
+            // here; the fixed prefix must still decode unchanged.
+            encoded.extend_from_slice(&trailing);
+            let decoded = decode_commit_meta(&encoded).unwrap();
+            prop_assert_eq!(decoded.active_root_page_id, active_root_page_id);
+            prop_assert_eq!(decoded.catalog_root_page_id, catalog_root_page_id);
+            prop_assert_eq!(decoded.free_list_root_page_id, free_list_root_page_id);
+            prop_assert_eq!(decoded.next_page_id, next_page_id);
+            prop_assert_eq!(decoded.unix_seconds, unix_seconds);
+        }
+    }
+}

src/vfs/traits.rs

@@ -875,4 +875,89 @@ mod tests {
         write_all_at(&mut file, 11, b"page").await.unwrap();
         assert_eq!(file.calls(), vec![(11, 4), (13, 2)]);
     }
+
+    /// Generated logical paths. A logical path is embedder-supplied and is the
+    /// only thing standing between a segment name and the filesystem, so the
+    /// interesting inputs are the ones that *look* like ordinary names on one
+    /// platform and re-root the path on another. Enumerating those by hand is
+    /// how a platform gets missed; generating them is not.
+    mod generated {
+        use proptest::prelude::*;
+
+        use super::super::{canonical_native_path, resolve_native_path};
+
+        fn cases() -> u32 {
+            std::env::var("PAGEDB_PROPTEST_CASES")
+                .ok()
+                .and_then(|raw| raw.parse().ok())
+                .unwrap_or(32)
+        }
+
+        fn config() -> ProptestConfig {
+            ProptestConfig {
+                cases: cases(),
+                failure_persistence: None,
+                ..ProptestConfig::default()
+            }
+        }
+
+        /// Characters chosen so separators, traversal, drive letters, UNC
+        /// prefixes and NUL are all common draws rather than lottery wins.
+        fn path_char() -> impl Strategy<Value = char> {
+            prop_oneof![
+                4 => prop::sample::select(vec![
+                    '/', '\\', '.', ':', 'a', 'b', 'C', '0', ' ', '\0',
+                ]),
+                1 => any::<char>(),
+            ]
+        }
+
+        proptest! {
+            #![proptest_config(config())]
+
+            #[test]
+            fn canonical_native_path_never_panics_and_never_re_roots(
+                path in prop::collection::vec(path_char(), 0..=24)
+                    .prop_map(|chars| chars.into_iter().collect::<String>()),
+            ) {
+                let Ok(canonical) = canonical_native_path(&path) else {
+                    return Ok(());
+                };
+                prop_assert!(canonical.starts_with('/'), "{canonical:?} is not rooted");
+                prop_assert!(
+                    !canonical.contains(':'),
+                    "{canonical:?} kept a drive-letter separator"
+                );
+                prop_assert!(
+                    !canonical.contains('\\'),
+                    "{canonical:?} kept a platform separator"
+                );
+                for component in canonical.trim_start_matches('/').split('/') {
+                    if component.is_empty() {
+                        continue;
+                    }
+                    prop_assert_ne!(component, ".");
+                    prop_assert_ne!(component, "..");
+                }
+            }
+
+            /// Accepting a path must also mean it resolves beneath the root:
+            /// canonicalisation is only useful if the resolved path cannot
+            /// escape.
+            #[test]
+            fn accepted_paths_resolve_beneath_the_root(
+                path in prop::collection::vec(path_char(), 0..=24)
+                    .prop_map(|chars| chars.into_iter().collect::<String>()),
+            ) {
+                let root = std::path::Path::new("/pagedb-root");
+                let Ok(resolved) = resolve_native_path(root, &path) else {
+                    return Ok(());
+                };
+                prop_assert!(
+                    resolved.starts_with(root),
+                    "{resolved:?} escaped {root:?} (from {path:?})"
+                );
+            }
+        }
+    }
 }