feat: native pure-Rust u64 FastPFOR codec

Adds a 64-bit (`u64`) FastPFOR codec to the pure-Rust side, which was
previously 32-bit only. `FastPForWide128`/`FastPForWide256` compress `u64`
values via the (now un-gated) `BlockCodec64` trait: FastPFOR-packed aligned
blocks plus a variable-byte tail for the sub-block remainder.

The wire format is byte-identical to the C++ `CppFastPFor128`/`CppFastPFor256`
`encode64`/`decode64` paths, verified by parity unit tests and a 30-minute
differential fuzz run (13.8M executions, no crashes).

- bitpacking_wide: generic scalar packer for `u64` at widths 0..=64, whose
  bit-ordering is cross-checked against the proven u32 kernels.
- fastpfor64: `FastPForWide<N>` with 65-entry exception tables, a 2-word
  exception bitmap, and u64 exception values.
- Un-gate `BlockCodec64` so pure-Rust builds get 64-bit support.
- Add the `fastpfor_u64` differential fuzz target and a README example.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: CommanderStorm

README.md

@@ -58,6 +58,27 @@ codec.decode_blocks(&encoded, Some(u32::try_from(blocks.len() * 256).expect("blo
 assert_eq!(decoded, input);
 ```
 
+### 64-bit integers (`u64`)
+
+`FastPForWide128` / `FastPForWide256` compress `u64` values via the `BlockCodec64`
+trait. The wire format is byte-compatible with the C++ `CppFastPFor128` /
+`CppFastPFor256` `encode64` / `decode64` paths.
+
+```rust
+use fastpfor::{BlockCodec64, FastPForWide256};
+
+let mut codec = FastPForWide256::default();
+let input: Vec<u64> = (0..600).map(|i| i * 1_000_000_000).collect();
+
+let mut encoded = Vec::new();
+codec.encode64(&input, &mut encoded).unwrap();
+
+let mut decoded = Vec::new();
+codec.decode64(&encoded, &mut decoded).unwrap();
+
+assert_eq!(decoded, input);
+```
+
 ### C++ Wrapper (`cpp` feature)
 
 Enable the `cpp` feature in `Cargo.toml`:

fuzz/Cargo.toml

@@ -62,3 +62,9 @@ name = "compare_fastpfor_128"
 path = "fuzz_targets/compare_fastpfor_128.rs"
 test = false
 doc = false
+
+[[bin]]
+name = "fastpfor_u64"
+path = "fuzz_targets/fastpfor_u64.rs"
+test = false
+doc = false

fuzz/fuzz_targets/fastpfor_u64.rs

@@ -0,0 +1,61 @@
+#![no_main]
+
+//! Differential fuzz of the 64-bit FastPFOR codec.
+//!
+//! For arbitrary `u64` input, the pure-Rust `FastPForWide` and the C++
+//! `CppFastPFor128` / `CppFastPFor256` must produce bit-identical compressed
+//! output, and every decoder must reproduce the original input — including
+//! decoding the other implementation's bytes.
+
+use fastpfor::cpp::{CppFastPFor128, CppFastPFor256};
+use fastpfor::{BlockCodec64, FastPForWide128, FastPForWide256};
+use libfuzzer_sys::fuzz_target;
+
+#[derive(arbitrary::Arbitrary, Debug)]
+struct Input {
+    data: Vec<u64>,
+    use_256: bool,
+}
+
+fn check(rust: &mut impl BlockCodec64, cpp: &mut impl BlockCodec64, data: &[u64], name: &str) {
+    let mut rust_enc = Vec::new();
+    rust.encode64(data, &mut rust_enc).expect("Rust encode64 failed");
+
+    let mut cpp_enc = Vec::new();
+    cpp.encode64(data, &mut cpp_enc).expect("C++ encode64 failed");
+
+    assert_eq!(rust_enc, cpp_enc, "{name}: Rust and C++ encode64 bytes differ");
+
+    let mut rust_dec = Vec::new();
+    rust.decode64(&rust_enc, &mut rust_dec)
+        .expect("Rust decode64 of own output failed");
+    assert_eq!(rust_dec, data, "{name}: Rust roundtrip mismatch");
+
+    let mut cross = Vec::new();
+    rust.decode64(&cpp_enc, &mut cross)
+        .expect("Rust decode64 of C++ output failed");
+    assert_eq!(cross, data, "{name}: Rust could not decode C++ output");
+
+    let mut cpp_dec = Vec::new();
+    cpp.decode64(&rust_enc, &mut cpp_dec)
+        .expect("C++ decode64 of Rust output failed");
+    assert_eq!(cpp_dec, data, "{name}: C++ could not decode Rust output");
+}
+
+fuzz_target!(|input: Input| {
+    if input.use_256 {
+        check(
+            &mut FastPForWide256::default(),
+            &mut CppFastPFor256::default(),
+            &input.data,
+            "FastPForWide256",
+        );
+    } else {
+        check(
+            &mut FastPForWide128::default(),
+            &mut CppFastPFor128::default(),
+            &input.data,
+            "FastPForWide128",
+        );
+    }
+});

src/codec.rs

@@ -93,13 +93,13 @@ pub trait BlockCodec: Default {
 
 /// Codec that supports compressing 64-bit integers into a 32-bit word stream.
 ///
-/// Only three C++ codecs implement this trait: `CppFastPFor128`,
-/// `CppFastPFor256`, and `CppVarInt`. For simple use, call
-/// `encode64` / `decode64` directly on the struct — no trait import required.
+/// Implemented by the pure-Rust [`FastPForWide`](crate::FastPForWide) codecs and,
+/// with the `cpp` feature, by `CppFastPFor128`, `CppFastPFor256`, and `CppVarInt`.
+/// For simple use, call `encode64` / `decode64` directly on the struct — no trait
+/// import required.
 ///
 /// Import `BlockCodec64` only when writing generic code over multiple codecs
 /// that support 64-bit compression.
-#[cfg(feature = "cpp")]
 pub trait BlockCodec64 {
     /// Compress 64-bit integers into a 32-bit word stream.
     fn encode64(&mut self, input: &[u64], out: &mut Vec<u32>) -> FastPForResult<()>;

src/lib.rs

@@ -18,7 +18,6 @@ pub mod cpp;
 pub(crate) mod rust;
 
 mod codec;
-#[cfg(feature = "cpp")]
 pub use codec::BlockCodec64;
 pub use codec::{AnyLenCodec, BlockCodec, slice_to_blocks};
 
@@ -31,7 +30,7 @@ pub use bytemuck::Pod;
 #[cfg(feature = "rust")]
 pub use rust::{
     CompositeCodec, FastPFor, FastPFor128, FastPFor256, FastPForBlock128, FastPForBlock256,
-    JustCopy, VariableByte,
+    FastPForWide, FastPForWide128, FastPForWide256, JustCopy, VariableByte,
 };
 
 // `src/test_utils.rs` uses `fastpfor::...`; alias this crate for unit tests only.

src/rust/integer_compression/bitpacking_wide.rs

@@ -0,0 +1,106 @@
+//! Generic scalar bit-packing for 64-bit values.
+//!
+//! Packs and unpacks groups of 32 values at any bit width `0..=64` using the same
+//! little-endian bitstream layout as the hand-unrolled 32-bit kernels in
+//! [`bitpacking`](super::bitpacking): value `j` occupies bits `[j*bit, (j+1)*bit)`
+//! of the concatenated stream. Each call moves exactly `bit` `u32` words.
+
+const fn low_mask(bit: u8) -> u64 {
+    if bit >= 64 { u64::MAX } else { (1u64 << bit) - 1 }
+}
+
+/// Packs 32 values from `input[inpos..]` into `output[outpos..]` at `bit` bits each.
+pub fn pack_wide(input: &[u64], inpos: usize, output: &mut [u32], outpos: usize, bit: u8) {
+    if bit == 0 {
+        return;
+    }
+    let mask = u128::from(low_mask(bit));
+    let mut acc: u128 = 0;
+    let mut filled: u32 = 0;
+    let mut out = outpos;
+    for j in 0..32 {
+        acc |= (u128::from(input[inpos + j]) & mask) << filled;
+        filled += u32::from(bit);
+        while filled >= 32 {
+            output[out] = acc as u32;
+            out += 1;
+            acc >>= 32;
+            filled -= 32;
+        }
+    }
+}
+
+/// Unpacks 32 values from `input[inpos..]` into `output[outpos..]` at `bit` bits each.
+pub fn unpack_wide(input: &[u32], inpos: usize, output: &mut [u64], outpos: usize, bit: u8) {
+    if bit == 0 {
+        output[outpos..outpos + 32].fill(0);
+        return;
+    }
+    let mask = u128::from(low_mask(bit));
+    let mut acc: u128 = 0;
+    let mut avail: u32 = 0;
+    let mut inp = inpos;
+    for j in 0..32 {
+        while avail < u32::from(bit) {
+            acc |= u128::from(input[inp]) << avail;
+            inp += 1;
+            avail += 32;
+        }
+        output[outpos + j] = (acc & mask) as u64;
+        acc >>= u32::from(bit);
+        avail -= u32::from(bit);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::rust::integer_compression::{bitpacking, bitunpacking};
+
+    /// The wide packer must produce byte-identical output to the proven u32 kernels
+    /// for every width `1..=32`, validating its bit ordering without needing C++.
+    #[test]
+    fn wide_matches_u32_kernels() {
+        let values32: [u32; 32] = std::array::from_fn(|i| (i as u32).wrapping_mul(2_654_435_761));
+
+        for bit in 1..=32u8 {
+            let mask = if bit == 32 { u32::MAX } else { (1u32 << bit) - 1 };
+            let masked32: [u32; 32] = std::array::from_fn(|i| values32[i] & mask);
+            let masked64: [u64; 32] = std::array::from_fn(|i| u64::from(masked32[i]));
+
+            let mut out_ref = vec![0u32; bit as usize];
+            bitpacking::fast_pack(&masked32, 0, &mut out_ref, 0, bit);
+
+            let mut out_wide = vec![0u32; bit as usize];
+            pack_wide(&masked64, 0, &mut out_wide, 0, bit);
+
+            assert_eq!(out_ref, out_wide, "pack mismatch at bit={bit}");
+
+            let mut back_ref = vec![0u32; 32];
+            bitunpacking::fast_unpack(&out_ref, 0, &mut back_ref, 0, bit);
+            let mut back_wide = vec![0u64; 32];
+            unpack_wide(&out_wide, 0, &mut back_wide, 0, bit);
+
+            for i in 0..32 {
+                assert_eq!(u64::from(back_ref[i]), back_wide[i], "unpack mismatch at bit={bit}");
+            }
+        }
+    }
+
+    #[test]
+    fn wide_roundtrip_all_widths() {
+        for bit in 0..=64u8 {
+            let mask = low_mask(bit);
+            let values: [u64; 32] =
+                std::array::from_fn(|i| (i as u64).wrapping_mul(0x9E37_79B9_7F4A_7C15) & mask);
+
+            let mut packed = vec![0u32; bit as usize];
+            pack_wide(&values, 0, &mut packed, 0, bit);
+
+            let mut back = vec![0u64; 32];
+            unpack_wide(&packed, 0, &mut back, 0, bit);
+
+            assert_eq!(values.to_vec(), back, "roundtrip mismatch at bit={bit}");
+        }
+    }
+}