From b40975f7e25f96f969620731c218e7ff84be6764 Mon Sep 17 00:00:00 2001
From: Prateek Gaur <prateek.gaur@snowflake.com>
Date: Sat, 3 Oct 2026 03:11:38 +0000
Subject: [PATCH 1/6] Fold frame bias into bit unpacking

Add an optional bias to the scalar and SIMD unpack paths so frame-of-reference decoders can apply it before each store. Preserve the full-width memcpy path and cover biased decoding across widths, offsets, epilogues, and dispatched instruction sets.
---
 cpp/src/arrow/util/bpacking.cc                |  32 +
 .../arrow/util/bpacking_dispatch_internal.h   | 602 ++++++++++--------
 cpp/src/arrow/util/bpacking_internal.h        |  25 +
 cpp/src/arrow/util/bpacking_scalar.cc         |  15 +
 cpp/src/arrow/util/bpacking_scalar_internal.h |  16 +
 cpp/src/arrow/util/bpacking_simd_128.cc       |  18 +
 cpp/src/arrow/util/bpacking_simd_128_alt.cc   |  17 +
 cpp/src/arrow/util/bpacking_simd_256.cc       |  18 +
 cpp/src/arrow/util/bpacking_simd_avx512.cc    |  15 +
 cpp/src/arrow/util/bpacking_simd_internal.h   |  72 +++
 .../util/bpacking_simd_kernel_internal.h      |  94 ++-
 cpp/src/arrow/util/bpacking_test.cc           | 157 +++++
 12 files changed, 790 insertions(+), 291 deletions(-)

diff --git a/cpp/src/arrow/util/bpacking.cc b/cpp/src/arrow/util/bpacking.cc
index 1bf81df4f28f..4a2ec0f9c059 100644
--- a/cpp/src/arrow/util/bpacking.cc
+++ b/cpp/src/arrow/util/bpacking.cc
@@ -43,6 +43,23 @@ struct UnpackDynamicFunction {
   }
 };
 
+template <typename Uint>
+struct UnpackBiasDynamicFunction {
+  using FunctionType = decltype(&bpacking::unpack_bias_scalar<Uint>);
+
+  static constexpr auto targets() {
+    return std::array{
+        ARROW_DISPATCH_TARGET_NONE(&bpacking::unpack_bias_scalar<Uint>)    //
+        ARROW_DISPATCH_TARGET_NEON(&bpacking::unpack_bias_neon<Uint>)      //
+        ARROW_DISPATCH_TARGET_SVE128(&bpacking::unpack_bias_sve128<Uint>)  //
+        ARROW_DISPATCH_TARGET_SVE256(&bpacking::unpack_bias_sve256<Uint>)  //
+        ARROW_DISPATCH_TARGET_SSE4_2(&bpacking::unpack_bias_sse4_2<Uint>)  //
+        ARROW_DISPATCH_TARGET_AVX2(&bpacking::unpack_bias_avx2<Uint>)      //
+        ARROW_DISPATCH_TARGET_AVX512(&bpacking::unpack_bias_avx512<Uint>)  //
+    };
+  }
+};
+
 }  // namespace
 
 template <typename Uint>
@@ -57,4 +74,19 @@ template void unpack<uint16_t>(const uint8_t*, uint16_t*, const UnpackOptions&);
 template void unpack<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&);
 template void unpack<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&);
 
+template <typename Uint>
+void unpack_bias(const uint8_t* in, Uint* out, const UnpackOptions& opts, Uint bias) {
+  static const DynamicDispatch<UnpackBiasDynamicFunction<Uint>> dispatch;
+  return dispatch(in, out, opts, bias);
+}
+
+template void unpack_bias<uint8_t>(const uint8_t*, uint8_t*, const UnpackOptions&,
+                                   uint8_t);
+template void unpack_bias<uint16_t>(const uint8_t*, uint16_t*, const UnpackOptions&,
+                                    uint16_t);
+template void unpack_bias<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&,
+                                    uint32_t);
+template void unpack_bias<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&,
+                                    uint64_t);
+
 }  // namespace arrow::internal
diff --git a/cpp/src/arrow/util/bpacking_dispatch_internal.h b/cpp/src/arrow/util/bpacking_dispatch_internal.h
index 6ea6adee1800..e89ccc9e8083 100644
--- a/cpp/src/arrow/util/bpacking_dispatch_internal.h
+++ b/cpp/src/arrow/util/bpacking_dispatch_internal.h
@@ -31,23 +31,52 @@
 namespace arrow::internal::bpacking {
 
 /// Unpack a zero bit packed array.
-template <typename Uint>
-ARROW_FORCE_INLINE void unpack_null(const uint8_t* in, Uint* out, int batch_size) {
-  std::memset(out, 0, batch_size * sizeof(Uint));
+template <bool kHasBias = false, typename Uint>
+ARROW_FORCE_INLINE void unpack_null(const uint8_t* in, Uint* out, int batch_size,
+                                    Uint bias = Uint{}) {
+  if constexpr (kHasBias) {
+    // Every unpacked value is zero, so every output value is the bias.
+    std::fill(out, out + batch_size, bias);
+  } else {
+    std::memset(out, 0, batch_size * sizeof(Uint));
+  }
 }
 
 /// Unpack a packed array where packed and unpacked values have exactly the same number of
 /// bits.
-template <typename Uint>
-ARROW_FORCE_INLINE void unpack_full(const uint8_t* in, Uint* out, int batch_size) {
+template <bool kHasBias = false, typename Uint>
+ARROW_FORCE_INLINE void unpack_full(const uint8_t* in, Uint* out, int batch_size,
+                                    Uint bias = Uint{}) {
   if constexpr (ARROW_LITTLE_ENDIAN == 1) {
-    std::memcpy(out, in, batch_size * sizeof(Uint));
+    if constexpr (kHasBias) {
+      // Two details let this loop approach memcpy speed:
+      //   1. A constant-size memcpy for the load, not SafeLoadAs: SafeLoadAs
+      //      builds an AlignedStorage per element and the vectorizer refuses it,
+      //      while a fixed-size memcpy is just an unaligned load.
+      //   2. A restrict qualifier: `in` is a uint8_t*, so it may alias
+      //      anything, including `out`. Without restating that they are
+      //      distinct the compiler has to assume overlap and emits a scalar
+      //      loop.
+      const uint8_t* ARROW_RESTRICT src = in;
+      Uint* ARROW_RESTRICT dst = out;
+      for (int k = 0; k < batch_size; k += 1) {
+        Uint val;
+        std::memcpy(&val, src + (k * sizeof(Uint)), sizeof(Uint));
+        dst[k] = static_cast<Uint>(val + bias);
+      }
+    } else {
+      std::memcpy(out, in, batch_size * sizeof(Uint));
+    }
   } else {
     using bit_util::FromLittleEndian;
     using util::SafeLoadAs;
 
     for (int k = 0; k < batch_size; k += 1) {
-      out[k] = FromLittleEndian(SafeLoadAs<Uint>(in + (k * sizeof(Uint))));
+      Uint val = FromLittleEndian(SafeLoadAs<Uint>(in + (k * sizeof(Uint))));
+      if constexpr (kHasBias) {
+        val = static_cast<Uint>(val + bias);
+      }
+      out[k] = val;
     }
   }
 }
@@ -96,9 +125,9 @@ using SpreadBufferUint = std::conditional_t<
 /// This function works for all input batch sizes but is not the fastest.
 /// In prolog mode, instead of unpacking all required element, the function will
 /// stop if it finds a byte aligned value start.
-template <int kPackedBitWidth, bool kIsProlog, typename Uint>
+template <int kPackedBitWidth, bool kIsProlog, bool kHasBias = false, typename Uint>
 ARROW_FORCE_INLINE int unpack_exact(const uint8_t* in, const uint8_t* in_end, Uint* out,
-                                    int batch_size, int bit_offset) {
+                                    int batch_size, int bit_offset, Uint bias = Uint{}) {
   static_assert(kPackedBitWidth > 0);
 
   // For the epilog we adapt the max spread since better alignment give shorter spreads
@@ -168,6 +197,9 @@ ARROW_FORCE_INLINE int unpack_exact(const uint8_t* in, const uint8_t* in_end, Ui
       }
     }
 
+    if constexpr (kHasBias) {
+      val = static_cast<Uint>(val + bias);
+    }
     *out = val;
     out++;
     start_bit += kPackedBitWidth;
@@ -190,12 +222,12 @@ ARROW_FORCE_INLINE int unpack_exact(const uint8_t* in, const uint8_t* in_end, Ui
 ///                       This is used to safely overread.
 ///                       Negative value to deduce from batch_size.
 template <int kPackedBitWidth, template <typename, int> typename Unpacker,
-          typename UnpackedUInt>
+          bool kHasBias = false, typename UnpackedUInt>
 void unpack_width(const uint8_t* in, UnpackedUInt* out, int batch_size, int bit_offset,
-                  int max_read_bytes) {
+                  int max_read_bytes, UnpackedUInt bias = UnpackedUInt{}) {
   if constexpr (kPackedBitWidth == 0) {
     // Easy case to handle, simply setting memory to zero.
-    return unpack_null(in, out, batch_size);
+    return unpack_null<kHasBias>(in, out, batch_size, bias);
   } else {
     // Number of bytes to read according to batch_size.
     const int bytes_batch = static_cast<int>(
@@ -206,8 +238,8 @@ void unpack_width(const uint8_t* in, UnpackedUInt* out, int batch_size, int bit_
     const uint8_t* in_end = in + (max_read_bytes >= 0 ? max_read_bytes : bytes_batch);
 
     // In case of misalignment, we need to run the prolog until aligned.
-    int extracted =
-        unpack_exact<kPackedBitWidth, true>(in, in_end, out, batch_size, bit_offset);
+    int extracted = unpack_exact<kPackedBitWidth, true, kHasBias>(
+        in, in_end, out, batch_size, bit_offset, bias);
     // We either extracted everything or found a alignment
     const int start_bit = extracted * kPackedBitWidth + bit_offset;
     ARROW_DCHECK((extracted == batch_size) || ((start_bit) % 8 == 0));
@@ -218,7 +250,7 @@ void unpack_width(const uint8_t* in, UnpackedUInt* out, int batch_size, int bit_
 
     if constexpr (kPackedBitWidth == 8 * sizeof(UnpackedUInt)) {
       // Only memcpy / static_cast
-      return unpack_full(in, out, batch_size);
+      return unpack_full<kHasBias>(in, out, batch_size, bias);
     } else {
       using UnpackerForWidth = Unpacker<UnpackedUInt, kPackedBitWidth>;
       // Number of values extracted by one iteration of the kernel
@@ -229,9 +261,29 @@ void unpack_width(const uint8_t* in, UnpackedUInt* out, int batch_size, int bit_
 
       if constexpr (kValuesUnpacked > 0) {
         const uint8_t* in_last = in_end - kBytesRead;
+        // Whether this unpacker family folds the bias into its own stores. The
+        // xsimd kernels do; the generated scalar and AVX-512 families do not, so
+        // they get a second pass over the values the kernel just wrote. That
+        // pass is over kValuesUnpacked elements still in L1, not over the whole
+        // Some generated kernels do not accept a bias. Apply it in a fallback
+        // pass for correctness on those targets.
+        constexpr bool kUnpackerTakesBias =
+            requires(const uint8_t* i, UnpackedUInt* o, UnpackedUInt b) {
+              UnpackerForWidth::unpack(i, o, b);
+            };  // NOLINT(readability/braces)
+
         // Running the optimized kernel for batch extraction
         while ((batch_size >= kValuesUnpacked) && (in <= in_last)) {
-          in = UnpackerForWidth::unpack(in, out);
+          if constexpr (kHasBias && kUnpackerTakesBias) {
+            in = UnpackerForWidth::unpack(in, out, bias);
+          } else {
+            in = UnpackerForWidth::unpack(in, out);
+            if constexpr (kHasBias) {
+              for (int k = 0; k < kValuesUnpacked; ++k) {
+                out[k] = static_cast<UnpackedUInt>(out[k] + bias);
+              }
+            }
+          }
           out += kValuesUnpacked;
           batch_size -= kValuesUnpacked;
         }
@@ -245,406 +297,412 @@ void unpack_width(const uint8_t* in, UnpackedUInt* out, int batch_size, int bit_
       // Running the epilog for the remaining values that don't fit in a kernel
       ARROW_DCHECK_GE(batch_size, 0);
       ARROW_COMPILER_ASSUME(batch_size >= 0);
-      unpack_exact<kPackedBitWidth, false>(in, in_end, out, batch_size,
-                                           /* bit_offset= */ 0);
+      unpack_exact<kPackedBitWidth, false, kHasBias>(in, in_end, out, batch_size,
+                                                     /* bit_offset= */ 0, bias);
     }
   }
 }
 
-template <template <typename, int> typename Unpacker, typename UnpackedUint>
-static void unpack_jump(const uint8_t* in, UnpackedUint* out, const UnpackOptions& opt) {
+template <template <typename, int> typename Unpacker, bool kHasBias = false,
+          typename UnpackedUint>
+static void unpack_jump(const uint8_t* in, UnpackedUint* out, const UnpackOptions& opt,
+                        UnpackedUint bias = UnpackedUint{}) {
+  // A bias on a bool output would have to saturate rather than add, which is not
+  // what any caller means by it.
+  static_assert(!(kHasBias && std::is_same_v<UnpackedUint, bool>),
+                "unpack with a bias is not defined for bool output");
   if constexpr (std::is_same_v<UnpackedUint, bool>) {
     switch (opt.bit_width) {
       case 0:
-        return unpack_width<0, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<0, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 1:
-        return unpack_width<1, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<1, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
     }
   } else if constexpr (sizeof(UnpackedUint) == 1) {
     switch (opt.bit_width) {
       case 0:
-        return unpack_width<0, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<0, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 1:
-        return unpack_width<1, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<1, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 2:
-        return unpack_width<2, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<2, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 3:
-        return unpack_width<3, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<3, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 4:
-        return unpack_width<4, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<4, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 5:
-        return unpack_width<5, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<5, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 6:
-        return unpack_width<6, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<6, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 7:
-        return unpack_width<7, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<7, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 8:
-        return unpack_width<8, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<8, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
     }
   } else if constexpr (sizeof(UnpackedUint) == 2) {
     switch (opt.bit_width) {
       case 0:
-        return unpack_width<0, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<0, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 1:
-        return unpack_width<1, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<1, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 2:
-        return unpack_width<2, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<2, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 3:
-        return unpack_width<3, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<3, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 4:
-        return unpack_width<4, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<4, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 5:
-        return unpack_width<5, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<5, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 6:
-        return unpack_width<6, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<6, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 7:
-        return unpack_width<7, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<7, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 8:
-        return unpack_width<8, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<8, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 9:
-        return unpack_width<9, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<9, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 10:
-        return unpack_width<10, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<10, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 11:
-        return unpack_width<11, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<11, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 12:
-        return unpack_width<12, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<12, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 13:
-        return unpack_width<13, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<13, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 14:
-        return unpack_width<14, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<14, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 15:
-        return unpack_width<15, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<15, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 16:
-        return unpack_width<16, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<16, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
     }
   } else if constexpr (sizeof(UnpackedUint) == 4) {
     switch (opt.bit_width) {
       case 0:
-        return unpack_width<0, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<0, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 1:
-        return unpack_width<1, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<1, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 2:
-        return unpack_width<2, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<2, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 3:
-        return unpack_width<3, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<3, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 4:
-        return unpack_width<4, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<4, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 5:
-        return unpack_width<5, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<5, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 6:
-        return unpack_width<6, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<6, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 7:
-        return unpack_width<7, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<7, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 8:
-        return unpack_width<8, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<8, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 9:
-        return unpack_width<9, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<9, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 10:
-        return unpack_width<10, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<10, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 11:
-        return unpack_width<11, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<11, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 12:
-        return unpack_width<12, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<12, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 13:
-        return unpack_width<13, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<13, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 14:
-        return unpack_width<14, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<14, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 15:
-        return unpack_width<15, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<15, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 16:
-        return unpack_width<16, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<16, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 17:
-        return unpack_width<17, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<17, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 18:
-        return unpack_width<18, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<18, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 19:
-        return unpack_width<19, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<19, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 20:
-        return unpack_width<20, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<20, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 21:
-        return unpack_width<21, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<21, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 22:
-        return unpack_width<22, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<22, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 23:
-        return unpack_width<23, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<23, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 24:
-        return unpack_width<24, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<24, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 25:
-        return unpack_width<25, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<25, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 26:
-        return unpack_width<26, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<26, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 27:
-        return unpack_width<27, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<27, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 28:
-        return unpack_width<28, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<28, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 29:
-        return unpack_width<29, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<29, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 30:
-        return unpack_width<30, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<30, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 31:
-        return unpack_width<31, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<31, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 32:
-        return unpack_width<32, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<32, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
     }
   } else if constexpr (sizeof(UnpackedUint) == 8) {
     switch (opt.bit_width) {
       case 0:
-        return unpack_width<0, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<0, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 1:
-        return unpack_width<1, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<1, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 2:
-        return unpack_width<2, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<2, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 3:
-        return unpack_width<3, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<3, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 4:
-        return unpack_width<4, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<4, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 5:
-        return unpack_width<5, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<5, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 6:
-        return unpack_width<6, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<6, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 7:
-        return unpack_width<7, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<7, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 8:
-        return unpack_width<8, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<8, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 9:
-        return unpack_width<9, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                         opt.max_read_bytes);
+        return unpack_width<9, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 10:
-        return unpack_width<10, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<10, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 11:
-        return unpack_width<11, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<11, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 12:
-        return unpack_width<12, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<12, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 13:
-        return unpack_width<13, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<13, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 14:
-        return unpack_width<14, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<14, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 15:
-        return unpack_width<15, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<15, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 16:
-        return unpack_width<16, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<16, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 17:
-        return unpack_width<17, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<17, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 18:
-        return unpack_width<18, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<18, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 19:
-        return unpack_width<19, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<19, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 20:
-        return unpack_width<20, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<20, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 21:
-        return unpack_width<21, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<21, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 22:
-        return unpack_width<22, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<22, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 23:
-        return unpack_width<23, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<23, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 24:
-        return unpack_width<24, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<24, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 25:
-        return unpack_width<25, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<25, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 26:
-        return unpack_width<26, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<26, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 27:
-        return unpack_width<27, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<27, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 28:
-        return unpack_width<28, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<28, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 29:
-        return unpack_width<29, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<29, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 30:
-        return unpack_width<30, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<30, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 31:
-        return unpack_width<31, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<31, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 32:
-        return unpack_width<32, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<32, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 33:
-        return unpack_width<33, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<33, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 34:
-        return unpack_width<34, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<34, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 35:
-        return unpack_width<35, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<35, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 36:
-        return unpack_width<36, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<36, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 37:
-        return unpack_width<37, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<37, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 38:
-        return unpack_width<38, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<38, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 39:
-        return unpack_width<39, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<39, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 40:
-        return unpack_width<40, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<40, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 41:
-        return unpack_width<41, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<41, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 42:
-        return unpack_width<42, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<42, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 43:
-        return unpack_width<43, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<43, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 44:
-        return unpack_width<44, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<44, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 45:
-        return unpack_width<45, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<45, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 46:
-        return unpack_width<46, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<46, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 47:
-        return unpack_width<47, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<47, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 48:
-        return unpack_width<48, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<48, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 49:
-        return unpack_width<49, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<49, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 50:
-        return unpack_width<50, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<50, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 51:
-        return unpack_width<51, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<51, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 52:
-        return unpack_width<52, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<52, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 53:
-        return unpack_width<53, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<53, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 54:
-        return unpack_width<54, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<54, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 55:
-        return unpack_width<55, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<55, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 56:
-        return unpack_width<56, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<56, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 57:
-        return unpack_width<57, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<57, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 58:
-        return unpack_width<58, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<58, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 59:
-        return unpack_width<59, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<59, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 60:
-        return unpack_width<60, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<60, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 61:
-        return unpack_width<61, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<61, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 62:
-        return unpack_width<62, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<62, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 63:
-        return unpack_width<63, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<63, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
       case 64:
-        return unpack_width<64, Unpacker>(in, out, opt.batch_size, opt.bit_offset,
-                                          opt.max_read_bytes);
+        return unpack_width<64, Unpacker, kHasBias>(
+            in, out, opt.batch_size, opt.bit_offset, opt.max_read_bytes, bias);
     }
   }
   ARROW_DCHECK(false) << "Unsupported num_bits " << opt.bit_width;
diff --git a/cpp/src/arrow/util/bpacking_internal.h b/cpp/src/arrow/util/bpacking_internal.h
index 329a1ae959b5..dbdad2082c6b 100644
--- a/cpp/src/arrow/util/bpacking_internal.h
+++ b/cpp/src/arrow/util/bpacking_internal.h
@@ -48,4 +48,29 @@ extern template ARROW_TEMPLATE_EXPORT void unpack<uint32_t>(  //
 extern template ARROW_TEMPLATE_EXPORT void unpack<uint64_t>(  //
     const uint8_t* in, uint64_t* out, const UnpackOptions& opts);
 
+/// \brief Unpack, adding `bias` to every value.
+///
+/// Equivalent to `unpack()` followed by a loop adding `bias`, but the addition
+/// happens inside the unpacker before its store, so the output is traversed
+/// once instead of twice. Frame-of-reference decoders are the motivating
+/// caller: the separate add pass costs as much as the unpack it follows.
+///
+/// `bias + value` is computed in `Uint`, so it wraps rather than saturating.
+/// Not defined for `bool` output, where an add has no meaning.
+template <typename Uint>
+ARROW_EXPORT void unpack_bias(const uint8_t* in, Uint* out, const UnpackOptions& opts,
+                              Uint bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias<uint8_t>(  //
+    const uint8_t* in, uint8_t* out, const UnpackOptions& opts, uint8_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias<uint16_t>(  //
+    const uint8_t* in, uint16_t* out, const UnpackOptions& opts, uint16_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias<uint32_t>(  //
+    const uint8_t* in, uint32_t* out, const UnpackOptions& opts, uint32_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias<uint64_t>(  //
+    const uint8_t* in, uint64_t* out, const UnpackOptions& opts, uint64_t bias);
+
 }  // namespace arrow::internal
diff --git a/cpp/src/arrow/util/bpacking_scalar.cc b/cpp/src/arrow/util/bpacking_scalar.cc
index 5226ad55cd3e..be3c9ded3462 100644
--- a/cpp/src/arrow/util/bpacking_scalar.cc
+++ b/cpp/src/arrow/util/bpacking_scalar.cc
@@ -33,4 +33,19 @@ template void unpack_scalar<uint16_t>(const uint8_t*, uint16_t*, const UnpackOpt
 template void unpack_scalar<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&);
 template void unpack_scalar<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&);
 
+template <typename Uint>
+void unpack_bias_scalar(const uint8_t* in, Uint* out, const UnpackOptions& opts,
+                        Uint bias) {
+  return unpack_jump<ScalarUnpackerForWidth, /*kHasBias=*/true>(in, out, opts, bias);
+}
+
+template void unpack_bias_scalar<uint8_t>(const uint8_t*, uint8_t*, const UnpackOptions&,
+                                          uint8_t);
+template void unpack_bias_scalar<uint16_t>(const uint8_t*, uint16_t*,
+                                           const UnpackOptions&, uint16_t);
+template void unpack_bias_scalar<uint32_t>(const uint8_t*, uint32_t*,
+                                           const UnpackOptions&, uint32_t);
+template void unpack_bias_scalar<uint64_t>(const uint8_t*, uint64_t*,
+                                           const UnpackOptions&, uint64_t);
+
 }  // namespace arrow::internal::bpacking
diff --git a/cpp/src/arrow/util/bpacking_scalar_internal.h b/cpp/src/arrow/util/bpacking_scalar_internal.h
index 2f62174f5f3f..c6a52a82e3b7 100644
--- a/cpp/src/arrow/util/bpacking_scalar_internal.h
+++ b/cpp/src/arrow/util/bpacking_scalar_internal.h
@@ -42,4 +42,20 @@ extern template ARROW_TEMPLATE_EXPORT void unpack_scalar<uint32_t>(
 extern template ARROW_TEMPLATE_EXPORT void unpack_scalar<uint64_t>(
     const uint8_t* in, uint64_t* out, const UnpackOptions& opts);
 
+template <typename Uint>
+ARROW_EXPORT void unpack_bias_scalar(const uint8_t* in, Uint* out,
+                                     const UnpackOptions& opts, Uint bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_scalar<uint8_t>(
+    const uint8_t* in, uint8_t* out, const UnpackOptions& opts, uint8_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_scalar<uint16_t>(
+    const uint8_t* in, uint16_t* out, const UnpackOptions& opts, uint16_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_scalar<uint32_t>(
+    const uint8_t* in, uint32_t* out, const UnpackOptions& opts, uint32_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_scalar<uint64_t>(
+    const uint8_t* in, uint64_t* out, const UnpackOptions& opts, uint64_t bias);
+
 }  // namespace arrow::internal::bpacking
diff --git a/cpp/src/arrow/util/bpacking_simd_128.cc b/cpp/src/arrow/util/bpacking_simd_128.cc
index 1bc756b2aa7d..ee90d22a37f5 100644
--- a/cpp/src/arrow/util/bpacking_simd_128.cc
+++ b/cpp/src/arrow/util/bpacking_simd_128.cc
@@ -17,9 +17,11 @@
 
 #if defined(ARROW_HAVE_NEON)
 #  define UNPACK_PLATFORM unpack_neon
+#  define UNPACK_BIAS_PLATFORM unpack_bias_neon
 #  define KERNEL_PLATFORM KernelNeon
 #elif defined(ARROW_HAVE_SSE4_2)
 #  define UNPACK_PLATFORM unpack_sse4_2
+#  define UNPACK_BIAS_PLATFORM unpack_bias_sse4_2
 #  define KERNEL_PLATFORM KernelSse42
 #endif
 
@@ -45,7 +47,23 @@ template void UNPACK_PLATFORM<uint16_t>(const uint8_t*, uint16_t*, const UnpackO
 template void UNPACK_PLATFORM<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&);
 template void UNPACK_PLATFORM<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&);
 
+template <typename Uint>
+void UNPACK_BIAS_PLATFORM(const uint8_t* in, Uint* out, const UnpackOptions& opts,
+                          Uint bias) {
+  return unpack_jump<KERNEL_PLATFORM, /*kHasBias=*/true>(in, out, opts, bias);
+}
+
+template void UNPACK_BIAS_PLATFORM<uint8_t>(const uint8_t*, uint8_t*,
+                                            const UnpackOptions&, uint8_t);
+template void UNPACK_BIAS_PLATFORM<uint16_t>(const uint8_t*, uint16_t*,
+                                             const UnpackOptions&, uint16_t);
+template void UNPACK_BIAS_PLATFORM<uint32_t>(const uint8_t*, uint32_t*,
+                                             const UnpackOptions&, uint32_t);
+template void UNPACK_BIAS_PLATFORM<uint64_t>(const uint8_t*, uint64_t*,
+                                             const UnpackOptions&, uint64_t);
+
 }  // namespace arrow::internal::bpacking
 
 #  undef UNPACK_PLATFORM
+#  undef UNPACK_BIAS_PLATFORM
 #endif  // UNPACK_PLATFORM
diff --git a/cpp/src/arrow/util/bpacking_simd_128_alt.cc b/cpp/src/arrow/util/bpacking_simd_128_alt.cc
index bd4799d3cd31..9ffaec4899b5 100644
--- a/cpp/src/arrow/util/bpacking_simd_128_alt.cc
+++ b/cpp/src/arrow/util/bpacking_simd_128_alt.cc
@@ -17,6 +17,7 @@
 
 #if defined(ARROW_HAVE_RUNTIME_SVE128)
 #  define UNPACK_PLATFORM unpack_sve128
+#  define UNPACK_BIAS_PLATFORM unpack_bias_sve128
 #  define KERNEL_PLATFORM KernelSve128
 #endif
 
@@ -46,6 +47,22 @@ template void UNPACK_PLATFORM<uint16_t>(const uint8_t*, uint16_t*, const UnpackO
 template void UNPACK_PLATFORM<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&);
 template void UNPACK_PLATFORM<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&);
 
+template <typename Uint>
+void UNPACK_BIAS_PLATFORM(const uint8_t* in, Uint* out, const UnpackOptions& opts,
+                          Uint bias) {
+  return unpack_jump<KERNEL_PLATFORM, /*kHasBias=*/true>(in, out, opts, bias);
+}
+
+template void UNPACK_BIAS_PLATFORM<uint8_t>(const uint8_t*, uint8_t*,
+                                            const UnpackOptions&, uint8_t);
+template void UNPACK_BIAS_PLATFORM<uint16_t>(const uint8_t*, uint16_t*,
+                                             const UnpackOptions&, uint16_t);
+template void UNPACK_BIAS_PLATFORM<uint32_t>(const uint8_t*, uint32_t*,
+                                             const UnpackOptions&, uint32_t);
+template void UNPACK_BIAS_PLATFORM<uint64_t>(const uint8_t*, uint64_t*,
+                                             const UnpackOptions&, uint64_t);
+
 }  // namespace arrow::internal::bpacking
 
 #undef UNPACK_PLATFORM
+#undef UNPACK_BIAS_PLATFORM
diff --git a/cpp/src/arrow/util/bpacking_simd_256.cc b/cpp/src/arrow/util/bpacking_simd_256.cc
index 8c5ce4dc7d06..98f7d210fb94 100644
--- a/cpp/src/arrow/util/bpacking_simd_256.cc
+++ b/cpp/src/arrow/util/bpacking_simd_256.cc
@@ -17,9 +17,11 @@
 
 #if defined(ARROW_HAVE_SVE256) || defined(ARROW_HAVE_RUNTIME_SVE256)
 #  define UNPACK_PLATFORM unpack_sve256
+#  define UNPACK_BIAS_PLATFORM unpack_bias_sve256
 #  define KERNEL_PLATFORM KernelSve256
 #elif defined(ARROW_HAVE_RUNTIME_AVX2)
 #  define UNPACK_PLATFORM unpack_avx2
+#  define UNPACK_BIAS_PLATFORM unpack_bias_avx2
 #  define KERNEL_PLATFORM KernelAvx2
 #endif
 
@@ -48,6 +50,22 @@ template void UNPACK_PLATFORM<uint16_t>(const uint8_t*, uint16_t*, const UnpackO
 template void UNPACK_PLATFORM<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&);
 template void UNPACK_PLATFORM<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&);
 
+template <typename Uint>
+void UNPACK_BIAS_PLATFORM(const uint8_t* in, Uint* out, const UnpackOptions& opts,
+                          Uint bias) {
+  return unpack_jump<KERNEL_PLATFORM, /*kHasBias=*/true>(in, out, opts, bias);
+}
+
+template void UNPACK_BIAS_PLATFORM<uint8_t>(const uint8_t*, uint8_t*,
+                                            const UnpackOptions&, uint8_t);
+template void UNPACK_BIAS_PLATFORM<uint16_t>(const uint8_t*, uint16_t*,
+                                             const UnpackOptions&, uint16_t);
+template void UNPACK_BIAS_PLATFORM<uint32_t>(const uint8_t*, uint32_t*,
+                                             const UnpackOptions&, uint32_t);
+template void UNPACK_BIAS_PLATFORM<uint64_t>(const uint8_t*, uint64_t*,
+                                             const UnpackOptions&, uint64_t);
+
 }  // namespace arrow::internal::bpacking
 
 #undef UNPACK_PLATFORM
+#undef UNPACK_BIAS_PLATFORM
diff --git a/cpp/src/arrow/util/bpacking_simd_avx512.cc b/cpp/src/arrow/util/bpacking_simd_avx512.cc
index bef7aebe175e..408ee5f3df19 100644
--- a/cpp/src/arrow/util/bpacking_simd_avx512.cc
+++ b/cpp/src/arrow/util/bpacking_simd_avx512.cc
@@ -33,4 +33,19 @@ template void unpack_avx512<uint16_t>(const uint8_t*, uint16_t*, const UnpackOpt
 template void unpack_avx512<uint32_t>(const uint8_t*, uint32_t*, const UnpackOptions&);
 template void unpack_avx512<uint64_t>(const uint8_t*, uint64_t*, const UnpackOptions&);
 
+template <typename Uint>
+void unpack_bias_avx512(const uint8_t* in, Uint* out, const UnpackOptions& opts,
+                        Uint bias) {
+  return unpack_jump<Simd512UnpackerForWidth, /*kHasBias=*/true>(in, out, opts, bias);
+}
+
+template void unpack_bias_avx512<uint8_t>(const uint8_t*, uint8_t*, const UnpackOptions&,
+                                          uint8_t);
+template void unpack_bias_avx512<uint16_t>(const uint8_t*, uint16_t*,
+                                           const UnpackOptions&, uint16_t);
+template void unpack_bias_avx512<uint32_t>(const uint8_t*, uint32_t*,
+                                           const UnpackOptions&, uint32_t);
+template void unpack_bias_avx512<uint64_t>(const uint8_t*, uint64_t*,
+                                           const UnpackOptions&, uint64_t);
+
 }  // namespace arrow::internal::bpacking
diff --git a/cpp/src/arrow/util/bpacking_simd_internal.h b/cpp/src/arrow/util/bpacking_simd_internal.h
index d5a81baaec09..3fbdaa8a237a 100644
--- a/cpp/src/arrow/util/bpacking_simd_internal.h
+++ b/cpp/src/arrow/util/bpacking_simd_internal.h
@@ -26,8 +26,10 @@ namespace arrow::internal::bpacking {
 
 #if defined(ARROW_HAVE_NEON)
 #  define UNPACK_ARCH128 unpack_neon
+#  define UNPACK_BIAS_ARCH128 unpack_bias_neon
 #elif defined(ARROW_HAVE_SSE4_2)
 #  define UNPACK_ARCH128 unpack_sse4_2
+#  define UNPACK_BIAS_ARCH128 unpack_bias_sse4_2
 #endif
 
 #if defined(UNPACK_ARCH128)
@@ -50,11 +52,29 @@ extern template ARROW_TEMPLATE_EXPORT void UNPACK_ARCH128<uint32_t>(
 extern template ARROW_TEMPLATE_EXPORT void UNPACK_ARCH128<uint64_t>(
     const uint8_t* in, uint64_t* out, const UnpackOptions& opts);
 
+template <typename Uint>
+ARROW_EXPORT void UNPACK_BIAS_ARCH128(const uint8_t* in, Uint* out,
+                                      const UnpackOptions& opts, Uint bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128<uint8_t>(
+    const uint8_t* in, uint8_t* out, const UnpackOptions& opts, uint8_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128<uint16_t>(
+    const uint8_t* in, uint16_t* out, const UnpackOptions& opts, uint16_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128<uint32_t>(
+    const uint8_t* in, uint32_t* out, const UnpackOptions& opts, uint32_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128<uint64_t>(
+    const uint8_t* in, uint64_t* out, const UnpackOptions& opts, uint64_t bias);
+
 #endif  // UNPACK_ARCH128
 #undef UNPACK_ARCH128
+#undef UNPACK_BIAS_ARCH128
 
 #if defined(ARROW_HAVE_RUNTIME_SVE128)
 #  define UNPACK_ARCH128_ALT unpack_sve128
+#  define UNPACK_BIAS_ARCH128_ALT unpack_bias_sve128
 #endif
 
 #if defined(UNPACK_ARCH128_ALT)
@@ -78,13 +98,32 @@ extern template ARROW_TEMPLATE_EXPORT void UNPACK_ARCH128_ALT<uint32_t>(
 extern template ARROW_TEMPLATE_EXPORT void UNPACK_ARCH128_ALT<uint64_t>(
     const uint8_t* in, uint64_t* out, const UnpackOptions& opts);
 
+template <typename Uint>
+ARROW_EXPORT void UNPACK_BIAS_ARCH128_ALT(const uint8_t* in, Uint* out,
+                                          const UnpackOptions& opts, Uint bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128_ALT<uint8_t>(
+    const uint8_t* in, uint8_t* out, const UnpackOptions& opts, uint8_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128_ALT<uint16_t>(
+    const uint8_t* in, uint16_t* out, const UnpackOptions& opts, uint16_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128_ALT<uint32_t>(
+    const uint8_t* in, uint32_t* out, const UnpackOptions& opts, uint32_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH128_ALT<uint64_t>(
+    const uint8_t* in, uint64_t* out, const UnpackOptions& opts, uint64_t bias);
+
 #endif  // UNPACK_ARCH128_ALT
 #undef UNPACK_ARCH128_ALT
+#undef UNPACK_BIAS_ARCH128_ALT
 
 #if defined(ARROW_HAVE_SVE256) || defined(ARROW_HAVE_RUNTIME_SVE256)
 #  define UNPACK_ARCH256 unpack_sve256
+#  define UNPACK_BIAS_ARCH256 unpack_bias_sve256
 #elif defined(UNPACK_ARCH256) || defined(ARROW_HAVE_RUNTIME_AVX2)
 #  define UNPACK_ARCH256 unpack_avx2
+#  define UNPACK_BIAS_ARCH256 unpack_bias_avx2
 #endif
 
 #if defined(UNPACK_ARCH256)
@@ -107,8 +146,25 @@ extern template ARROW_TEMPLATE_EXPORT void UNPACK_ARCH256<uint32_t>(
 extern template ARROW_TEMPLATE_EXPORT void UNPACK_ARCH256<uint64_t>(
     const uint8_t* in, uint64_t* out, const UnpackOptions& opts);
 
+template <typename Uint>
+ARROW_EXPORT void UNPACK_BIAS_ARCH256(const uint8_t* in, Uint* out,
+                                      const UnpackOptions& opts, Uint bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH256<uint8_t>(
+    const uint8_t* in, uint8_t* out, const UnpackOptions& opts, uint8_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH256<uint16_t>(
+    const uint8_t* in, uint16_t* out, const UnpackOptions& opts, uint16_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH256<uint32_t>(
+    const uint8_t* in, uint32_t* out, const UnpackOptions& opts, uint32_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void UNPACK_BIAS_ARCH256<uint64_t>(
+    const uint8_t* in, uint64_t* out, const UnpackOptions& opts, uint64_t bias);
+
 #endif  // UNPACK_ARCH256
 #undef UNPACK_ARCH256
+#undef UNPACK_BIAS_ARCH256
 
 #if defined(ARROW_HAVE_AVX512) || defined(ARROW_HAVE_RUNTIME_AVX512)
 
@@ -130,6 +186,22 @@ extern template ARROW_TEMPLATE_EXPORT void unpack_avx512<uint32_t>(
 extern template ARROW_TEMPLATE_EXPORT void unpack_avx512<uint64_t>(
     const uint8_t* in, uint64_t* out, const UnpackOptions& opts);
 
+template <typename Uint>
+ARROW_EXPORT void unpack_bias_avx512(const uint8_t* in, Uint* out,
+                                     const UnpackOptions& opts, Uint bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_avx512<uint8_t>(
+    const uint8_t* in, uint8_t* out, const UnpackOptions& opts, uint8_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_avx512<uint16_t>(
+    const uint8_t* in, uint16_t* out, const UnpackOptions& opts, uint16_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_avx512<uint32_t>(
+    const uint8_t* in, uint32_t* out, const UnpackOptions& opts, uint32_t bias);
+
+extern template ARROW_TEMPLATE_EXPORT void unpack_bias_avx512<uint64_t>(
+    const uint8_t* in, uint64_t* out, const UnpackOptions& opts, uint64_t bias);
+
 #endif
 
 }  // namespace arrow::internal::bpacking
diff --git a/cpp/src/arrow/util/bpacking_simd_kernel_internal.h b/cpp/src/arrow/util/bpacking_simd_kernel_internal.h
index 83a969cca643..33cddfe0ef79 100644
--- a/cpp/src/arrow/util/bpacking_simd_kernel_internal.h
+++ b/cpp/src/arrow/util/bpacking_simd_kernel_internal.h
@@ -645,9 +645,10 @@ struct MediumKernel {
   static constexpr int kValuesUnpacked = kPlan.unpacked_per_kernel();
   static constexpr int kBytesRead = kPlan.total_bytes_read();
 
-  template <int kReadIdx, int kSwizzleIdx, int kShiftIdx>
+  template <bool kHasBias, int kReadIdx, int kSwizzleIdx, int kShiftIdx>
   ARROW_FORCE_INLINE static void unpack_one_shift_impl(const simd_batch& words,
-                                                       unpacked_type* out) {
+                                                       unpacked_type* out,
+                                                       const simd_batch& bias) {
     constexpr auto kRightShiftsArr =
         kPlan.shifts.at(kReadIdx).at(kSwizzleIdx).at(kShiftIdx);
     constexpr auto kRightShifts = array_to_batch_constant<kRightShiftsArr, arch_type>();
@@ -662,44 +663,62 @@ struct MediumKernel {
     const auto shifted = right_shift_by_excess(words, kRightShifts);
     const auto vals = shifted & kMask;
     if constexpr (std::is_same_v<unpacked_type, bool>) {
+      static_assert(!kHasBias, "no bias on bool output");
       const xsimd::batch_bool<uint_type, arch_type> bools = vals != 0;
       bools.store_unaligned(out + kOutOffset);
+    } else if constexpr (kHasBias) {
+      // The bias is added before the store, so the output needs no second
+      // pass to add it.
+      (vals + bias).store_unaligned(out + kOutOffset);
     } else {
       vals.store_unaligned(out + kOutOffset);
     }
   }
 
-  template <int kReadIdx, int kSwizzleIdx, int... kShiftIds>
+  template <bool kHasBias, int kReadIdx, int kSwizzleIdx, int... kShiftIds>
   ARROW_FORCE_INLINE static void unpack_one_swizzle_impl(
-      const simd_bytes& bytes, unpacked_type* out,
+      const simd_bytes& bytes, unpacked_type* out, const simd_batch& bias,
       std::integer_sequence<int, kShiftIds...>) {
     constexpr auto kSwizzlesArr = kPlan.swizzles.at(kReadIdx).at(kSwizzleIdx);
     constexpr auto kSwizzles = array_to_batch_constant<kSwizzlesArr, arch_type>();
 
     const auto swizzled = xsimd::swizzle(bytes, kSwizzles);
     const auto words = xsimd::bitwise_cast<uint_type>(swizzled);
-    (unpack_one_shift_impl<kReadIdx, kSwizzleIdx, kShiftIds>(words, out), ...);
+    (unpack_one_shift_impl<kHasBias, kReadIdx, kSwizzleIdx, kShiftIds>(words, out, bias),
+     ...);
   }
 
-  template <int kReadIdx, int... kSwizzleIds>
+  template <bool kHasBias, int kReadIdx, int... kSwizzleIds>
   ARROW_FORCE_INLINE static void unpack_one_read_impl(
-      const uint8_t* in, unpacked_type* out, std::integer_sequence<int, kSwizzleIds...>) {
+      const uint8_t* in, unpacked_type* out, const simd_batch& bias,
+      std::integer_sequence<int, kSwizzleIds...>) {
     using ShiftSeq = std::make_integer_sequence<int, kPlanSize.shifts_per_swizzle()>;
     const auto bytes =
         safe_load_bytes<kPlan.bytes_per_read(), arch_type>(in + kPlan.reads.at(kReadIdx));
-    (unpack_one_swizzle_impl<kReadIdx, kSwizzleIds>(bytes, out, ShiftSeq{}), ...);
+    (unpack_one_swizzle_impl<kHasBias, kReadIdx, kSwizzleIds>(bytes, out, bias,
+                                                              ShiftSeq{}),
+     ...);
   }
 
-  template <int... kReadIds>
+  template <bool kHasBias, int... kReadIds>
   ARROW_FORCE_INLINE static void unpack_all_impl(
-      const uint8_t* in, unpacked_type* out, std::integer_sequence<int, kReadIds...>) {
+      const uint8_t* in, unpacked_type* out, const simd_batch& bias,
+      std::integer_sequence<int, kReadIds...>) {
     using SwizzleSeq = std::make_integer_sequence<int, kPlanSize.swizzles_per_read()>;
-    (unpack_one_read_impl<kReadIds>(in, out, SwizzleSeq{}), ...);
+    (unpack_one_read_impl<kHasBias, kReadIds>(in, out, bias, SwizzleSeq{}), ...);
   }
 
   ARROW_FORCE_INLINE static const uint8_t* unpack(const uint8_t* in, unpacked_type* out) {
     using ReadSeq = std::make_integer_sequence<int, kPlanSize.reads_per_kernel()>;
-    unpack_all_impl(in, out, ReadSeq{});
+    unpack_all_impl<false>(in, out, simd_batch{}, ReadSeq{});
+    return in + (kPlan.unpacked_per_kernel() * kShape.packed_bit_size()) / 8;
+  }
+
+  /// Same, with `bias` added to every value before it is stored.
+  ARROW_FORCE_INLINE static const uint8_t* unpack(const uint8_t* in, unpacked_type* out,
+                                                  unpacked_type bias) {
+    using ReadSeq = std::make_integer_sequence<int, kPlanSize.reads_per_kernel()>;
+    unpack_all_impl<true>(in, out, simd_batch(static_cast<uint_type>(bias)), ReadSeq{});
     return in + (kPlan.unpacked_per_kernel() * kShape.packed_bit_size()) / 8;
   }
 };
@@ -934,9 +953,10 @@ struct LargeKernel {
   static constexpr int kValuesUnpacked = kPlanSize.unpacked_per_kernel();
   static constexpr int kBytesRead = kPlan.total_bytes_read();
 
-  template <int kReadIdx>
+  template <bool kHasBias, int kReadIdx>
   ARROW_FORCE_INLINE static void unpack_one_read_impl(const uint8_t* in,
-                                                      unpacked_type* out) {
+                                                      unpacked_type* out,
+                                                      const simd_batch& bias) {
     constexpr auto kLowSwizzles =
         array_to_batch_constant<kPlan.low_swizzles.at(kReadIdx), arch_type>();
     constexpr auto kLowRShifts =
@@ -967,18 +987,34 @@ struct LargeKernel {
     // We can have a single mask and apply it after OR because the shifts will ensure that
     // there are zeros where the high/low values are incomplete.
     const auto vals = (low_shifted | high_shifted) & kPlan.mask;
-    xsimd::store_unaligned(out + kReadIdx * kShape.unpacked_per_simd(), vals);
+    if constexpr (kHasBias) {
+      // As in MediumKernel: fold the bias into this store rather than sweeping
+      // the output again afterwards.
+      xsimd::store_unaligned(out + kReadIdx * kShape.unpacked_per_simd(), vals + bias);
+    } else {
+      xsimd::store_unaligned(out + kReadIdx * kShape.unpacked_per_simd(), vals);
+    }
   }
 
-  template <int... kReadIds>
+  template <bool kHasBias, int... kReadIds>
   ARROW_FORCE_INLINE static void unpack_all_impl(
-      const uint8_t* in, unpacked_type* out, std::integer_sequence<int, kReadIds...>) {
-    (unpack_one_read_impl<kReadIds>(in, out), ...);
+      const uint8_t* in, unpacked_type* out, const simd_batch& bias,
+      std::integer_sequence<int, kReadIds...>) {
+    (unpack_one_read_impl<kHasBias, kReadIds>(in, out, bias), ...);
   }
 
   ARROW_FORCE_INLINE static const uint8_t* unpack(const uint8_t* in, unpacked_type* out) {
     using ReadSeq = std::make_integer_sequence<int, kPlanSize.reads_per_kernel()>;
-    unpack_all_impl(in, out, ReadSeq{});
+    unpack_all_impl<false>(in, out, simd_batch{}, ReadSeq{});
+    return in + (kPlan.kPlanSize.unpacked_per_kernel() * kShape.packed_bit_size()) / 8;
+  }
+
+  /// Same, with `bias` added to every value before it is stored.
+  ARROW_FORCE_INLINE static const uint8_t* unpack(const uint8_t* in, unpacked_type* out,
+                                                  unpacked_type bias) {
+    using ReadSeq = std::make_integer_sequence<int, kPlanSize.reads_per_kernel()>;
+    unpack_all_impl<true>(
+        in, out, simd_batch(static_cast<typename Traits::uint_type>(bias)), ReadSeq{});
     return in + (kPlan.kPlanSize.unpacked_per_kernel() * kShape.packed_bit_size()) / 8;
   }
 };
@@ -1016,6 +1052,26 @@ struct CastingKernel : WorkingKernel {
     }
     return in;
   }
+
+  /// Same, with `bias` added to every value.
+  ///
+  /// The add goes in the cast loop, not in the working kernel's stores. The
+  /// working kernel can be *narrower* than `unpacked_type` (uint32 working /
+  /// uint64 unpacked on SSE4.2), and adding there would compute the bias modulo
+  /// the working width before widening -- wrong for any bias that does not fit.
+  /// Adding after the widening is correct for both directions, and the cast loop
+  /// was going to run anyway.
+  ARROW_FORCE_INLINE static const uint8_t* unpack(const uint8_t* in, unpacked_type* out,
+                                                  unpacked_type bias) {
+    using working_type = typename WorkingKernel::unpacked_type;
+
+    working_type buffer[kValuesUnpacked] = {};
+    in = WorkingKernel::unpack(in, buffer);
+    for (int k = 0; k < kValuesUnpacked; ++k) {
+      out[k] = static_cast<unpacked_type>(static_cast<unpacked_type>(buffer[k]) + bias);
+    }
+    return in;
+  }
 };
 
 /*******************************
diff --git a/cpp/src/arrow/util/bpacking_test.cc b/cpp/src/arrow/util/bpacking_test.cc
index d4d588228e7e..87e4570f4de8 100644
--- a/cpp/src/arrow/util/bpacking_test.cc
+++ b/cpp/src/arrow/util/bpacking_test.cc
@@ -321,4 +321,161 @@ TYPED_TEST(TestUnpack, UnpackSve256) {
 
 TYPED_TEST(TestUnpack, Unpack) { this->TestAll(&unpack<TypeParam>); }
 
+// ----------------------------------------------------------------------
+// unpack_bias
+
+template <typename Uint>
+using UnpackBiasFunc = void (*)(const uint8_t*, Uint*, const UnpackOptions&, Uint);
+
+template <typename Uint>
+class TestUnpackBias : public ::testing::Test {
+ protected:
+  /// `unpack_bias` must agree with `unpack` followed by an add, elementwise.
+  ///
+  /// This is a differential test against the plain unpacker on the same target,
+  /// which TestUnpack already covers, so it needs no second reference
+  /// implementation -- and it catches the failure mode that matters most here: a
+  /// kernel that folds the bias into some of its stores but not all of them.
+  void TestOne(UnpackBiasFunc<Uint> unpack_bias, UnpackFunc<Uint> unpack,
+               const UnpackOptions& opts, Uint bias) {
+    SCOPED_TRACE(::testing::Message() << "Testing bias=" << static_cast<uint64_t>(bias));
+
+    const auto original =
+        GenerateRandomValuesForPacking<Uint>(opts.batch_size, opts.bit_width);
+    const auto packed =
+        PackValues(original, opts.batch_size, opts.bit_width, opts.bit_offset);
+
+    std::vector<Uint> expected(opts.batch_size);
+    unpack(packed.data(), expected.data(), opts);
+    for (auto& v : expected) {
+      v = static_cast<Uint>(v + bias);
+    }
+
+    // Prefilled with a value the unpacker should never leave behind, so a store
+    // the kernel skips shows up as a mismatch rather than a lucky zero.
+    std::vector<Uint> actual(opts.batch_size, static_cast<Uint>(~Uint{0}));
+    unpack_bias(packed.data(), actual.data(), opts, bias);
+
+    ASSERT_EQ(expected, actual);
+  }
+
+  void TestAll(UnpackBiasFunc<Uint> unpack_bias, UnpackFunc<Uint> unpack) {
+    constexpr int kMaxBitWidth = 8 * sizeof(Uint);
+
+    // 0 must reproduce plain unpack. The top two force the add to wrap, which is
+    // the documented behaviour (the add is modular in Uint) and is what
+    // frame-of-reference callers rely on when they reinterpret the result as
+    // signed.
+    const std::vector<Uint> kBiases = {Uint{0}, Uint{1}, static_cast<Uint>(~Uint{0}),
+                                       static_cast<Uint>(Uint{1} << (kMaxBitWidth - 1))};
+
+    for (int num_values_base : {64, 128, 2048}) {
+      SCOPED_TRACE(::testing::Message() << "Testing num_values=" << num_values_base);
+
+      for (int bit_width = 0; bit_width <= kMaxBitWidth; ++bit_width) {
+        SCOPED_TRACE(::testing::Message() << "Testing bit_width=" << bit_width);
+
+        // Every misalignment, to reach the prolog with a bias.
+        for (int bit_offset = 0; bit_offset < 8; ++bit_offset) {
+          SCOPED_TRACE(::testing::Message() << "Testing bit_offset=" << bit_offset);
+          const UnpackOptions opts{
+              .batch_size = num_values_base,
+              .bit_width = bit_width,
+              .bit_offset = bit_offset,
+              .max_read_bytes = -1,  // No over-reading in testing (strict ASAN)
+          };
+          for (Uint bias : kBiases) {
+            TestOne(unpack_bias, unpack, opts, bias);
+            if (testing::Test::HasFailure()) return;
+          }
+        }
+
+        // Every epilog size, to reach the tail with a bias.
+        for (int epilogue_size = 0; epilogue_size <= kMaxBitWidth; ++epilogue_size) {
+          SCOPED_TRACE(::testing::Message() << "Testing epilog_size=" << epilogue_size);
+          const UnpackOptions opts{
+              .batch_size = num_values_base + epilogue_size,
+              .bit_width = bit_width,
+              .bit_offset = 0,
+              .max_read_bytes = -1,  // No over-reading in testing (strict ASAN)
+          };
+          for (Uint bias : kBiases) {
+            TestOne(unpack_bias, unpack, opts, bias);
+            if (testing::Test::HasFailure()) return;
+          }
+        }
+      }
+    }
+  }
+};
+
+// No bool: an add has no meaning on a bool output and unpack_bias is not
+// instantiated for it.
+using UnpackBiasTypes = ::testing::Types<uint8_t, uint16_t, uint32_t, uint64_t>;
+
+TYPED_TEST_SUITE(TestUnpackBias, UnpackBiasTypes, UnpackTypeNames);
+
+TYPED_TEST(TestUnpackBias, UnpackBiasScalar) {
+  this->TestAll(&bpacking::unpack_bias_scalar<TypeParam>,
+                &bpacking::unpack_scalar<TypeParam>);
+}
+
+#if defined(ARROW_HAVE_SSE4_2)
+TYPED_TEST(TestUnpackBias, UnpackBiasSse4_2) {
+  this->TestAll(&bpacking::unpack_bias_sse4_2<TypeParam>,
+                &bpacking::unpack_sse4_2<TypeParam>);
+}
+#endif
+
+#if defined(ARROW_HAVE_RUNTIME_AVX2)
+TYPED_TEST(TestUnpackBias, UnpackBiasAvx2) {
+  if (!CpuInfo::GetInstance()->IsSupported(CpuInfo::AVX2)) {
+    GTEST_SKIP() << "Test requires AVX2";
+  }
+  this->TestAll(&bpacking::unpack_bias_avx2<TypeParam>,
+                &bpacking::unpack_avx2<TypeParam>);
+}
+#endif
+
+#if defined(ARROW_HAVE_RUNTIME_AVX512)
+TYPED_TEST(TestUnpackBias, UnpackBiasAvx512) {
+  if (!CpuInfo::GetInstance()->IsSupported(CpuInfo::AVX512)) {
+    GTEST_SKIP() << "Test requires AVX512";
+  }
+  this->TestAll(&bpacking::unpack_bias_avx512<TypeParam>,
+                &bpacking::unpack_avx512<TypeParam>);
+}
+#endif
+
+#if defined(ARROW_HAVE_NEON)
+TYPED_TEST(TestUnpackBias, UnpackBiasNeon) {
+  this->TestAll(&bpacking::unpack_bias_neon<TypeParam>,
+                &bpacking::unpack_neon<TypeParam>);
+}
+#endif
+
+#if defined(ARROW_HAVE_RUNTIME_SVE128)
+TYPED_TEST(TestUnpackBias, UnpackBiasSve128) {
+  if (!CpuInfo::GetInstance()->IsSupported(CpuInfo::SVE128)) {
+    GTEST_SKIP() << "Test requires SVE128";
+  }
+  this->TestAll(&bpacking::unpack_bias_sve128<TypeParam>,
+                &bpacking::unpack_sve128<TypeParam>);
+}
+#endif
+
+#if defined(ARROW_HAVE_RUNTIME_SVE256)
+TYPED_TEST(TestUnpackBias, UnpackBiasSve256) {
+  if (!CpuInfo::GetInstance()->IsSupported(CpuInfo::SVE256)) {
+    GTEST_SKIP() << "Test requires SVE256";
+  }
+  this->TestAll(&bpacking::unpack_bias_sve256<TypeParam>,
+                &bpacking::unpack_sve256<TypeParam>);
+}
+#endif
+
+TYPED_TEST(TestUnpackBias, UnpackBias) {
+  this->TestAll(&unpack_bias<TypeParam>, &unpack<TypeParam>);
+}
+
 }  // namespace arrow::internal

From 1db491393b7c142d59d0019419b4043514f75c5a Mon Sep 17 00:00:00 2001
From: Prateek Gaur <prateek.gaur@snowflake.com>
Date: Sat, 3 Oct 2026 03:11:46 +0000
Subject: [PATCH 2/6] Add the PFOR codec and page format

Implement frame selection, bit packing, exception handling, endian-independent wire serialization, and validated vector and page decoding for int32 and int64. Build the codec with CMake and Meson and include focused unit and benchmark coverage.
---
 cpp/src/arrow/CMakeLists.txt                  |   2 +
 cpp/src/arrow/meson.build                     |   2 +
 cpp/src/arrow/util/CMakeLists.txt             |   4 +
 cpp/src/arrow/util/meson.build                |   1 +
 cpp/src/arrow/util/pfor/pfor.cc               | 396 +++++++++
 cpp/src/arrow/util/pfor/pfor_benchmark.cc     | 312 +++++++
 .../arrow/util/pfor/pfor_constants_internal.h | 103 +++
 cpp/src/arrow/util/pfor/pfor_internal.h       | 237 ++++++
 cpp/src/arrow/util/pfor/pfor_test.cc          | 773 ++++++++++++++++++
 cpp/src/arrow/util/pfor/pfor_wrapper.cc       | 416 ++++++++++
 .../arrow/util/pfor/pfor_wrapper_internal.h   | 156 ++++
 11 files changed, 2402 insertions(+)
 create mode 100644 cpp/src/arrow/util/pfor/pfor.cc
 create mode 100644 cpp/src/arrow/util/pfor/pfor_benchmark.cc
 create mode 100644 cpp/src/arrow/util/pfor/pfor_constants_internal.h
 create mode 100644 cpp/src/arrow/util/pfor/pfor_internal.h
 create mode 100644 cpp/src/arrow/util/pfor/pfor_test.cc
 create mode 100644 cpp/src/arrow/util/pfor/pfor_wrapper.cc
 create mode 100644 cpp/src/arrow/util/pfor/pfor_wrapper_internal.h

diff --git a/cpp/src/arrow/CMakeLists.txt b/cpp/src/arrow/CMakeLists.txt
index 8750598f6c3b..0a239e893258 100644
--- a/cpp/src/arrow/CMakeLists.txt
+++ b/cpp/src/arrow/CMakeLists.txt
@@ -566,6 +566,8 @@ set(ARROW_UTIL_SRCS
     util/math_internal.cc
     util/memory.cc
     util/mutex.cc
+    util/pfor/pfor.cc
+    util/pfor/pfor_wrapper.cc
     util/ree_util.cc
     util/secure_string.cc
     util/string.cc
diff --git a/cpp/src/arrow/meson.build b/cpp/src/arrow/meson.build
index 831bc1218083..ebba2cd22fbb 100644
--- a/cpp/src/arrow/meson.build
+++ b/cpp/src/arrow/meson.build
@@ -204,6 +204,8 @@ arrow_util_srcs = [
     'util/math_internal.cc',
     'util/memory.cc',
     'util/mutex.cc',
+    'util/pfor/pfor.cc',
+    'util/pfor/pfor_wrapper.cc',
     'util/ree_util.cc',
     'util/secure_string.cc',
     'util/string.cc',
diff --git a/cpp/src/arrow/util/CMakeLists.txt b/cpp/src/arrow/util/CMakeLists.txt
index 628e9a4d1c7e..9be9dbfa7188 100644
--- a/cpp/src/arrow/util/CMakeLists.txt
+++ b/cpp/src/arrow/util/CMakeLists.txt
@@ -118,6 +118,10 @@ add_arrow_test(threading-utility-test
                test_common.cc
                thread_pool_test.cc)
 
+add_arrow_test(pfor-test SOURCES pfor/pfor_test.cc)
+
+add_arrow_benchmark(pfor/pfor_benchmark)
+
 add_arrow_benchmark(bit_block_counter_benchmark)
 add_arrow_benchmark(bit_util_benchmark)
 add_arrow_benchmark(bitmap_reader_benchmark)
diff --git a/cpp/src/arrow/util/meson.build b/cpp/src/arrow/util/meson.build
index c39e09c2d030..41f306d3c7d2 100644
--- a/cpp/src/arrow/util/meson.build
+++ b/cpp/src/arrow/util/meson.build
@@ -269,6 +269,7 @@ util_tests = {
         ],
     },
     'arrow-crc32-test': {'sources': ['crc32_test.cc']},
+    'arrow-pfor-test': {'sources': ['pfor/pfor_test.cc']},
 }
 
 foreach key, val : util_tests
diff --git a/cpp/src/arrow/util/pfor/pfor.cc b/cpp/src/arrow/util/pfor/pfor.cc
new file mode 100644
index 000000000000..ca73bc7dd2fc
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor.cc
@@ -0,0 +1,396 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Core PFOR (Patched Frame of Reference) compression implementation
+//
+// Implementation notes:
+//   - Vector size: 1024
+//   - Max exceptions: PforConstants::ExceptionCountType
+//   - Exception values: original integers (not FOR offsets)
+//   - Bit packing: Arrow's BitWriter/unpack
+
+#include "arrow/util/pfor/pfor_internal.h"
+
+#include <algorithm>
+#include <array>
+#include <cstring>
+#include <limits>
+#include <span>
+
+#include "arrow/util/bit_stream_utils_internal.h"
+#include "arrow/util/bit_util.h"
+#include "arrow/util/bpacking_internal.h"
+#include "arrow/util/endian.h"
+#include "arrow/util/logging.h"
+#include "arrow/util/macros.h"
+#include "arrow/util/ubsan.h"
+
+namespace arrow {
+namespace util {
+namespace pfor {
+
+namespace {
+
+// The PFOR wire format is little-endian, so every multi-byte field converts on the
+// way in and out. The bit-packed deltas need no conversion of their own:
+// bit_util::BitWriter writes them little-endian and arrow::internal::unpack reads
+// them back the same way, so those bytes are copied verbatim.
+//
+// On a little-endian host both helpers below are a plain memcpy.
+template <typename T>
+void StoreLittleEndianArray(const T* values, int64_t num_values, uint8_t* output) {
+  if constexpr (ARROW_LITTLE_ENDIAN == 1) {
+    std::memcpy(output, values, static_cast<size_t>(num_values) * sizeof(T));
+  } else {
+    for (int64_t i = 0; i < num_values; ++i) {
+      util::SafeStore(output + i * sizeof(T), bit_util::ToLittleEndian(values[i]));
+    }
+  }
+}
+
+}  // namespace
+
+// ----------------------------------------------------------------------
+// FindOptimalBitWidth: histogram-based cost model
+
+template <typename T>
+BitWidthResult PforCompression<T>::FindOptimalBitWidth(const UnsignedT* deltas,
+                                                       int32_t num_elements) {
+  constexpr uint8_t max_bits = PforTypeTraits<T>::kMaxBitWidth;
+  constexpr int32_t position_bits =
+      static_cast<int32_t>(sizeof(PforConstants::PositionType)) * 8;
+  constexpr int32_t value_bits = sizeof(T) * 8;
+
+  // Build histogram: histogram[b] = count of deltas requiring exactly b bits.
+  // Use 4 independent accumulators so the read-modify-write doesn't serialize
+  // on repeated bins and the four load->clz->bump chains overlap (this loop is
+  // ~half of encode time; a single histogram array runs scalar and stalls).
+  std::array<int32_t, 65> h0{}, h1{}, h2{}, h3{};
+  int32_t i = 0;
+  for (; i + 4 <= num_elements; i += 4) {
+    ++h0[PforTypeTraits<T>::BitsRequired(deltas[i])];
+    ++h1[PforTypeTraits<T>::BitsRequired(deltas[i + 1])];
+    ++h2[PforTypeTraits<T>::BitsRequired(deltas[i + 2])];
+    ++h3[PforTypeTraits<T>::BitsRequired(deltas[i + 3])];
+  }
+  for (; i < num_elements; ++i) ++h0[PforTypeTraits<T>::BitsRequired(deltas[i])];
+  std::array<int32_t, 65> histogram{};
+  for (int b = 0; b <= 64; ++b) histogram[b] = h0[b] + h1[b] + h2[b] + h3[b];
+
+  // Evaluate each candidate bit width
+  int64_t best_cost = std::numeric_limits<int64_t>::max();
+  uint8_t best_bit_width = max_bits;
+  PforConstants::ExceptionCountType best_num_exceptions = 0;
+
+  int64_t exceptions_above = num_elements;
+
+  for (uint8_t b = 0; b <= max_bits; ++b) {
+    exceptions_above -= histogram[b];
+
+    // A vector holds at most kMaxVectorSize elements, so that is also the most
+    // exceptions one can name. Skipping the wider counts keeps the cast below
+    // exact; the full-width candidate has none at all, so a best is always
+    // found.
+    if (exceptions_above > PforConstants::kMaxVectorSize) {
+      continue;
+    }
+
+    int64_t packing_cost = static_cast<int64_t>(num_elements) * b;
+    int64_t exception_cost = exceptions_above * (position_bits + value_bits);
+    int64_t total_cost = packing_cost + exception_cost;
+
+    if (total_cost < best_cost) {
+      best_cost = total_cost;
+      best_bit_width = b;
+      best_num_exceptions =
+          static_cast<PforConstants::ExceptionCountType>(exceptions_above);
+    }
+  }
+
+  return {best_bit_width, best_num_exceptions};
+}
+
+// ----------------------------------------------------------------------
+// EncodeVector
+
+template <typename T>
+PforEncodedVector<T> PforCompression<T>::EncodeVector(const T* values,
+                                                      int32_t num_elements) {
+  ARROW_DCHECK(num_elements > 0);
+
+  // Step 1: Find min (frame of reference)
+  T min_val = values[0];
+  for (int32_t i = 1; i < num_elements; ++i) {
+    if (values[i] < min_val) min_val = values[i];
+  }
+
+  // Step 2: Compute unsigned deltas. Use a stack scratch for the common
+  // (<=vector-size) case to avoid a per-vector heap alloc + zero-init.
+  const auto unsigned_min = static_cast<UnsignedT>(min_val);
+  constexpr int32_t kFull = static_cast<int32_t>(PforConstants::kPforVectorSize);
+  UnsignedT stack_deltas[kFull];
+  std::vector<UnsignedT> heap_deltas;
+  UnsignedT* deltas = stack_deltas;
+  if (num_elements > kFull) {
+    heap_deltas.resize(num_elements);
+    deltas = heap_deltas.data();
+  }
+  for (int32_t i = 0; i < num_elements; ++i) {
+    deltas[i] = static_cast<UnsignedT>(values[i]) - unsigned_min;
+  }
+
+  // Step 3: Find optimal bit width
+  auto [bit_width, num_exceptions] = FindOptimalBitWidth(deltas, num_elements);
+
+  // Step 4: Collect exceptions and replace with placeholder (0)
+  PforEncodedVector<T> result;
+  result.set_info(PforVectorInfo<T>(min_val, bit_width, num_exceptions));
+
+  if (num_exceptions > 0) {
+    result.mutable_exception_positions().reserve(num_exceptions);
+    result.mutable_exception_values().reserve(num_exceptions);
+
+    UnsignedT mask = (bit_width >= PforTypeTraits<T>::kMaxBitWidth)
+                         ? static_cast<UnsignedT>(-1)
+                         : (static_cast<UnsignedT>(1) << bit_width) - 1;
+
+    for (int32_t i = 0; i < num_elements; ++i) {
+      if (deltas[i] > mask) {
+        result.mutable_exception_positions().push_back(
+            static_cast<PforConstants::PositionType>(i));
+        result.mutable_exception_values().push_back(values[i]);
+        deltas[i] = 0;
+      }
+    }
+  }
+
+  // Step 5: Bit-pack the deltas
+  if (bit_width > 0) {
+    int64_t packed_size =
+        bit_util::BytesForBits(static_cast<int64_t>(num_elements) * bit_width);
+    result.mutable_packed_values().resize(static_cast<size_t>(packed_size), 0);
+
+    bit_util::BitWriter writer(result.mutable_packed_values().data(),
+                               static_cast<int>(packed_size));
+    for (int32_t i = 0; i < num_elements; ++i) {
+      writer.PutValue(static_cast<uint64_t>(deltas[i]), bit_width);
+    }
+    writer.Flush();
+  }
+
+  return result;
+}
+
+// ----------------------------------------------------------------------
+// DecodeVector
+
+template <typename T>
+Result<int64_t> PforCompression<T>::DecodeVector(std::span<const uint8_t> data,
+                                                 int32_t num_elements, T* values) {
+  // Step 1: Read vector info
+  ARROW_ASSIGN_OR_RAISE(auto info, PforVectorInfo<T>::Load(data));
+  const uint8_t* read_ptr = data.data() + PforVectorInfo<T>::kStoredSize;
+
+  // `values` holds num_elements slots, and everything below is sized by fields
+  // that came off the wire, so check them against it before reading or writing.
+  if (info.num_exceptions() > num_elements) {
+    return Status::Invalid("PFOR vector has ", info.num_exceptions(),
+                           " exceptions but only ", num_elements, " elements");
+  }
+  const int64_t packed_bytes =
+      bit_util::BytesForBits(static_cast<int64_t>(num_elements) * info.bit_width());
+  const int64_t exception_bytes =
+      info.num_exceptions() *
+      (static_cast<int64_t>(sizeof(PforConstants::PositionType)) + sizeof(T));
+  if (PforVectorInfo<T>::kStoredSize + packed_bytes + exception_bytes >
+      static_cast<int64_t>(data.size())) {
+    return Status::Invalid(
+        "PFOR vector needs ",
+        PforVectorInfo<T>::kStoredSize + packed_bytes + exception_bytes,
+        " bytes but only ", data.size(), " remain");
+  }
+
+  // Step 2: Handle constant data (bit_width == 0, no exceptions)
+  if (info.bit_width() == 0 && info.num_exceptions() == 0) {
+    std::fill(values, values + num_elements, info.frame_of_reference());
+    return PforVectorInfo<T>::kStoredSize;
+  }
+
+  // Step 3: Unpack bit-packed deltas and add FOR
+  if (info.bit_width() > 0) {
+    const auto unsigned_for = static_cast<UnsignedT>(info.frame_of_reference());
+
+    // The vector kernels load a fixed-size window per step. Use the remaining
+    // page bytes as the read bound so a kernel can process the final step when
+    // its load extends beyond this vector's packed payload.
+    //
+    // `data` runs from this vector to the end of the page, so every byte after
+    // this vector's header is inside the caller's buffer and ours to read.
+    const auto readable_bytes = static_cast<int>(std::min<int64_t>(
+        static_cast<int64_t>(data.size()) - PforVectorInfo<T>::kStoredSize,
+        std::numeric_limits<int>::max()));
+
+    if (unsigned_for == 0) {
+      // FOR is zero: there is no bias to add, so unpack straight into the
+      // output. T and UnsignedT are the same width, so the unsigned bits the
+      // unpacker writes are the signed values — no scratch buffer and no
+      // second (add-FOR) pass. This is the common case (any column whose
+      // minimum is 0) and decodes at the raw unpack speed. Exceptions are
+      // still patched below in Step 4.
+      arrow::internal::unpack(read_ptr, reinterpret_cast<UnsignedT*>(values),
+                              arrow::internal::UnpackOptions{
+                                  static_cast<int>(num_elements), info.bit_width(),
+                                  /*bit_offset=*/0, readable_bytes});
+    } else {
+      // Fold the non-zero frame into the unpacker's store to avoid a second
+      // traversal of the output.
+      //
+      // The add is modular in UnsignedT, so the bits the unpacker stores are the
+      // signed values, exactly as in the FOR==0 case above — no cast pass, no
+      // scratch, and no aliasing question. Exceptions are patched in Step 4.
+      arrow::internal::unpack_bias(read_ptr, reinterpret_cast<UnsignedT*>(values),
+                                   arrow::internal::UnpackOptions{
+                                       static_cast<int>(num_elements), info.bit_width(),
+                                       /*bit_offset=*/0, readable_bytes},
+                                   unsigned_for);
+    }
+
+    read_ptr += packed_bytes;
+  } else {
+    // bit_width == 0 but has exceptions - fill with FOR
+    std::fill(values, values + num_elements, info.frame_of_reference());
+  }
+
+  // Step 4: Patch exceptions (stored as original values at their positions).
+  const PforConstants::ExceptionCountType num_exceptions = info.num_exceptions();
+  if (num_exceptions > 0) {
+    const uint8_t* positions_ptr = read_ptr;
+    read_ptr += num_exceptions * sizeof(PforConstants::PositionType);
+
+    const uint8_t* values_ptr = read_ptr;
+    read_ptr += num_exceptions * sizeof(T);
+
+    // Every position indexes `values`, so one past the end is an out-of-bounds
+    // write. Take the maximum first: a reduction still vectorizes, where a
+    // bounds check with an early return inside the patch loop would not.
+    PforConstants::PositionType max_position = 0;
+    for (PforConstants::ExceptionCountType i = 0; i < num_exceptions; ++i) {
+      max_position = std::max(
+          max_position,
+          bit_util::FromLittleEndian(util::SafeLoadAs<PforConstants::PositionType>(
+              positions_ptr + i * sizeof(PforConstants::PositionType))));
+    }
+    if (max_position >= num_elements) {
+      return Status::Invalid("PFOR exception position ", max_position,
+                             " is outside a vector of ", num_elements, " elements");
+    }
+
+    for (PforConstants::ExceptionCountType i = 0; i < num_exceptions; ++i) {
+      PforConstants::PositionType pos =
+          bit_util::FromLittleEndian(util::SafeLoadAs<PforConstants::PositionType>(
+              positions_ptr + i * sizeof(PforConstants::PositionType)));
+      T value =
+          bit_util::FromLittleEndian(util::SafeLoadAs<T>(values_ptr + i * sizeof(T)));
+      values[static_cast<size_t>(pos)] = value;
+    }
+  }
+
+  return static_cast<int64_t>(read_ptr - data.data());
+}
+
+// ----------------------------------------------------------------------
+// Serialization helpers
+
+template <typename T>
+int64_t PforCompression<T>::SerializedVectorSize(const PforEncodedVector<T>& vec,
+                                                 int32_t num_elements) {
+  int64_t size = PforVectorInfo<T>::kStoredSize;
+  if (vec.info().bit_width() > 0) {
+    size += bit_util::BytesForBits(static_cast<int64_t>(num_elements) *
+                                   vec.info().bit_width());
+  }
+  size += vec.info().num_exceptions() *
+          static_cast<int64_t>(sizeof(PforConstants::PositionType));
+  size += vec.info().num_exceptions() * static_cast<int64_t>(sizeof(T));
+  return size;
+}
+
+template <typename T>
+Result<int64_t> PforCompression<T>::SerializeVector(const PforEncodedVector<T>& vec,
+                                                    int32_t num_elements,
+                                                    std::span<uint8_t> dest) {
+  const int64_t needed = SerializedVectorSize(vec, num_elements);
+  if (static_cast<int64_t>(dest.size()) < needed) {
+    return Status::Invalid("PFOR vector needs ", needed, " bytes to serialize but only ",
+                           dest.size(), " remain");
+  }
+
+  // `needed` is computed from bit_width and num_exceptions, while the copies
+  // below take their lengths from the sections themselves, so a vector whose
+  // info disagrees with its sections would write past `needed` bytes.
+  const int64_t expected_packed_bytes =
+      vec.info().bit_width() > 0
+          ? bit_util::BytesForBits(static_cast<int64_t>(num_elements) *
+                                   vec.info().bit_width())
+          : 0;
+  if (static_cast<int64_t>(vec.packed_values().size()) != expected_packed_bytes) {
+    return Status::Invalid("PFOR vector has ", vec.packed_values().size(),
+                           " packed bytes but bit_width ",
+                           static_cast<int>(vec.info().bit_width()), " over ",
+                           num_elements, " elements needs ", expected_packed_bytes);
+  }
+  if (vec.exception_positions().size() != vec.info().num_exceptions() ||
+      vec.exception_values().size() != vec.info().num_exceptions()) {
+    return Status::Invalid("PFOR vector claims ", vec.info().num_exceptions(),
+                           " exceptions but carries ", vec.exception_positions().size(),
+                           " positions and ", vec.exception_values().size(), " values");
+  }
+
+  uint8_t* write_ptr = dest.data();
+
+  // Write vector info
+  vec.info().Store(std::span<uint8_t>(write_ptr, PforVectorInfo<T>::kStoredSize));
+  write_ptr += PforVectorInfo<T>::kStoredSize;
+
+  // Write packed values
+  if (vec.info().bit_width() > 0) {
+    std::memcpy(write_ptr, vec.packed_values().data(), vec.packed_values().size());
+    write_ptr += vec.packed_values().size();
+  }
+
+  // Write exception positions
+  if (vec.info().num_exceptions() > 0) {
+    StoreLittleEndianArray(vec.exception_positions().data(), vec.info().num_exceptions(),
+                           write_ptr);
+    write_ptr += vec.info().num_exceptions() * sizeof(PforConstants::PositionType);
+
+    // Write exception values (original integers)
+    StoreLittleEndianArray(vec.exception_values().data(), vec.info().num_exceptions(),
+                           write_ptr);
+    write_ptr += vec.info().num_exceptions() * sizeof(T);
+  }
+
+  return static_cast<int64_t>(write_ptr - dest.data());
+}
+
+// Explicit template instantiations
+template class PforCompression<int32_t>;
+template class PforCompression<int64_t>;
+
+}  // namespace pfor
+}  // namespace util
+}  // namespace arrow
diff --git a/cpp/src/arrow/util/pfor/pfor_benchmark.cc b/cpp/src/arrow/util/pfor/pfor_benchmark.cc
new file mode 100644
index 000000000000..127965e0210d
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor_benchmark.cc
@@ -0,0 +1,312 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// PFOR encoding/decoding benchmarks.
+//
+// Data distributions cover the key archetypes that exercise PFOR's cost model
+// differently:
+//   - Constant: bit_width=0, best case
+//   - Sequential: small range, ideal FOR
+//   - SmallRange: clustered random, good FOR compression
+//   - HighBaseSmallRange: high absolute values, small delta range (timestamps)
+//   - WithOutliers: tests exception handling path
+//   - Random: worst case, full bit-width
+//   - TPC-DS DateSk/StoreSk/ItemSk/Quantity: realistic surrogate key distributions
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <cstring>
+#include <limits>
+#include <numeric>
+#include <random>
+#include <vector>
+
+#include "benchmark/benchmark.h"
+
+#include "arrow/util/logging.h"
+#include "arrow/util/pfor/pfor_internal.h"
+#include "arrow/util/pfor/pfor_wrapper_internal.h"
+
+namespace arrow::util::pfor {
+namespace {
+
+// ----------------------------------------------------------------------
+// Data Generators
+
+using Int32Gen = std::vector<int32_t> (*)(int64_t);
+using Int64Gen = std::vector<int64_t> (*)(int64_t);
+
+template <typename T>
+std::vector<T> GenConstant(int64_t n) {
+  return std::vector<T>(n, static_cast<T>(42));
+}
+
+template <typename T>
+std::vector<T> GenSequential(int64_t n) {
+  std::vector<T> v(n);
+  std::iota(v.begin(), v.end(), static_cast<T>(0));
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenSmallRange(int64_t n) {
+  std::vector<T> v(n);
+  std::mt19937_64 rng(12345);
+  std::uniform_int_distribution<T> dist(100000, 200000);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenHighBaseSmallRange(int64_t n) {
+  std::vector<T> v(n);
+  const T kBase = static_cast<T>(1704067200);
+  std::mt19937_64 rng(12345);
+  std::uniform_int_distribution<T> dist(0, 1000);
+  for (auto& x : v) x = kBase + dist(rng);
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenWithOutliers(int64_t n) {
+  std::vector<T> v(n);
+  std::mt19937_64 rng(42);
+  std::uniform_int_distribution<T> small_dist(1000, 1255);
+  for (auto& x : v) x = small_dist(rng);
+  std::uniform_int_distribution<int64_t> pos_dist(0, n - 1);
+  int num_outliers = std::max(static_cast<int64_t>(1), n / 100);
+  for (int i = 0; i < num_outliers; ++i) {
+    v[pos_dist(rng)] = static_cast<T>(std::numeric_limits<T>::max() / 2 + i);
+  }
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenRandom(int64_t n) {
+  std::vector<T> v(n);
+  std::mt19937_64 rng(99);
+  std::uniform_int_distribution<T> dist(std::numeric_limits<T>::min(),
+                                        std::numeric_limits<T>::max());
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenTpcdsSoldDateSk(int64_t n) {
+  std::vector<T> v(n);
+  const T kBase = 2450815;
+  std::mt19937_64 rng(12345);
+  std::uniform_int_distribution<T> dist(0, 1820);
+  for (auto& x : v) x = kBase + dist(rng);
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenTpcdsStoreSk(int64_t n) {
+  std::vector<T> v(n);
+  std::mt19937_64 rng(12345);
+  std::uniform_int_distribution<T> dist(1, 1000);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenTpcdsItemSk(int64_t n) {
+  std::vector<T> v(n);
+  const T kMax = 100000;
+  std::mt19937_64 rng(12345);
+  std::exponential_distribution<double> exp_dist(0.00005);
+  for (auto& x : v) {
+    T val = static_cast<T>(exp_dist(rng));
+    x = std::min(static_cast<T>(val + 1), kMax);
+  }
+  return v;
+}
+
+template <typename T>
+std::vector<T> GenTpcdsQuantity(int64_t n) {
+  std::vector<T> v(n);
+  std::mt19937_64 rng(12345);
+  std::uniform_int_distribution<T> small_dist(1, 10);
+  std::uniform_int_distribution<T> large_dist(11, 100);
+  std::uniform_int_distribution<int> chance(0, 99);
+  for (auto& x : v) {
+    x = (chance(rng) < 90) ? small_dist(rng) : large_dist(rng);
+  }
+  return v;
+}
+
+// ----------------------------------------------------------------------
+// Benchmark Core
+
+template <typename T>
+void BM_PforEncodeImpl(benchmark::State& state, std::vector<T> (*generator)(int64_t)) {
+  const int64_t num_values = state.range(0);
+  auto values = generator(num_values);
+
+  int64_t max_size =
+      PforWrapper<T>::GetMaxCompressedSize(static_cast<int32_t>(num_values)).ValueOrDie();
+  std::vector<uint8_t> compressed(max_size);
+
+  for (auto _ : state) {
+    int64_t comp_size = max_size;
+    ARROW_CHECK_OK(
+        PforWrapper<T>::Encode(values.data(), num_values, compressed.data(), &comp_size));
+    benchmark::DoNotOptimize(comp_size);
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * num_values *
+                          static_cast<int64_t>(sizeof(T)));
+  state.SetItemsProcessed(state.iterations() * num_values);
+
+  // Report compression ratio
+  int64_t comp_size = max_size;
+  ARROW_CHECK_OK(
+      PforWrapper<T>::Encode(values.data(), num_values, compressed.data(), &comp_size));
+  state.counters["CompRatio%"] =
+      benchmark::Counter(100.0 * static_cast<double>(comp_size) /
+                         static_cast<double>(num_values * sizeof(T)));
+}
+
+template <typename T>
+void BM_PforDecodeImpl(benchmark::State& state, std::vector<T> (*generator)(int64_t)) {
+  const int64_t num_values = state.range(0);
+  auto values = generator(num_values);
+
+  int64_t max_size =
+      PforWrapper<T>::GetMaxCompressedSize(static_cast<int32_t>(num_values)).ValueOrDie();
+  std::vector<uint8_t> compressed(max_size);
+  int64_t comp_size = max_size;
+  ARROW_CHECK_OK(
+      PforWrapper<T>::Encode(values.data(), num_values, compressed.data(), &comp_size));
+
+  std::vector<T> decoded(num_values);
+
+  for (auto _ : state) {
+    ARROW_CHECK_OK(
+        PforWrapper<T>::Decode(compressed.data(), comp_size, num_values, decoded.data()));
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * num_values *
+                          static_cast<int64_t>(sizeof(T)));
+  state.SetItemsProcessed(state.iterations() * num_values);
+}
+
+// ----------------------------------------------------------------------
+// Non-template wrappers to avoid comma-in-macro issues with BENCHMARK_CAPTURE
+
+void BM_PforEncodeInt32(benchmark::State& state, Int32Gen gen) {
+  BM_PforEncodeImpl<int32_t>(state, gen);
+}
+void BM_PforDecodeInt32(benchmark::State& state, Int32Gen gen) {
+  BM_PforDecodeImpl<int32_t>(state, gen);
+}
+void BM_PforEncodeInt64(benchmark::State& state, Int64Gen gen) {
+  BM_PforEncodeImpl<int64_t>(state, gen);
+}
+void BM_PforDecodeInt64(benchmark::State& state, Int64Gen gen) {
+  BM_PforDecodeImpl<int64_t>(state, gen);
+}
+
+// ----------------------------------------------------------------------
+// Benchmark sizes: 1K, 10K, 100K, 1M
+
+static void CustomArgs(benchmark::internal::Benchmark* b) {
+  for (int64_t n : {1024, 10240, 102400, 1048576}) {
+    b->Arg(n);
+  }
+}
+
+// ----------------------------------------------------------------------
+// INT32 Encode
+
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, Constant, &GenConstant<int32_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, Sequential, &GenSequential<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, SmallRange, &GenSmallRange<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, HighBaseSmallRange, &GenHighBaseSmallRange<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, WithOutliers, &GenWithOutliers<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, Random, &GenRandom<int32_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, TpcdsSoldDateSk, &GenTpcdsSoldDateSk<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, TpcdsStoreSk, &GenTpcdsStoreSk<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, TpcdsItemSk, &GenTpcdsItemSk<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt32, TpcdsQuantity, &GenTpcdsQuantity<int32_t>)
+    ->Apply(CustomArgs);
+
+// INT32 Decode
+
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, Constant, &GenConstant<int32_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, Sequential, &GenSequential<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, SmallRange, &GenSmallRange<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, HighBaseSmallRange, &GenHighBaseSmallRange<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, WithOutliers, &GenWithOutliers<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, Random, &GenRandom<int32_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, TpcdsSoldDateSk, &GenTpcdsSoldDateSk<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, TpcdsStoreSk, &GenTpcdsStoreSk<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, TpcdsItemSk, &GenTpcdsItemSk<int32_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt32, TpcdsQuantity, &GenTpcdsQuantity<int32_t>)
+    ->Apply(CustomArgs);
+
+// ----------------------------------------------------------------------
+// INT64 Encode
+
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, Constant, &GenConstant<int64_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, Sequential, &GenSequential<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, SmallRange, &GenSmallRange<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, HighBaseSmallRange, &GenHighBaseSmallRange<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, WithOutliers, &GenWithOutliers<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, Random, &GenRandom<int64_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforEncodeInt64, TpcdsSoldDateSk, &GenTpcdsSoldDateSk<int64_t>)
+    ->Apply(CustomArgs);
+
+// INT64 Decode
+
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, Constant, &GenConstant<int64_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, Sequential, &GenSequential<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, SmallRange, &GenSmallRange<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, HighBaseSmallRange, &GenHighBaseSmallRange<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, WithOutliers, &GenWithOutliers<int64_t>)
+    ->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, Random, &GenRandom<int64_t>)->Apply(CustomArgs);
+BENCHMARK_CAPTURE(BM_PforDecodeInt64, TpcdsSoldDateSk, &GenTpcdsSoldDateSk<int64_t>)
+    ->Apply(CustomArgs);
+
+}  // namespace
+}  // namespace arrow::util::pfor
diff --git a/cpp/src/arrow/util/pfor/pfor_constants_internal.h b/cpp/src/arrow/util/pfor/pfor_constants_internal.h
new file mode 100644
index 000000000000..863ffa5a7343
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor_constants_internal.h
@@ -0,0 +1,103 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Constants for PFOR (Patched Frame of Reference) compression
+
+#pragma once
+
+#include <bit>
+#include <cstdint>
+#include <type_traits>
+
+namespace arrow {
+namespace util {
+namespace pfor {
+
+/// \brief Constants used throughout PFOR compression
+class PforConstants {
+ public:
+  /// Number of elements compressed together as a unit.
+  static constexpr int64_t kPforVectorSize = 1024;
+
+  /// log2(kPforVectorSize)
+  static constexpr uint8_t kDefaultLogVectorSize = 10;
+
+  /// Minimum allowed log vector size
+  static constexpr uint8_t kMinLogVectorSize = 3;
+
+  /// Maximum allowed log vector size
+  static constexpr uint8_t kMaxLogVectorSize = 15;
+
+  /// Type used to store vector data offsets (supports pages up to 4GB)
+  using OffsetType = uint32_t;
+
+  /// Type used to store exception positions within a compressed vector.
+  using PositionType = uint16_t;
+
+  /// Type used to store the number of exceptions in a compressed vector.
+  ///
+  /// Unsigned: a vector holds up to 2^kMaxLogVectorSize elements and every one
+  /// of them can be an exception, so a count of 32768 has to be representable.
+  using ExceptionCountType = uint16_t;
+
+  /// Largest vector the format allows, in elements.
+  static constexpr int32_t kMaxVectorSize = 1 << kMaxLogVectorSize;
+
+  /// Page header size in bytes: packing_mode, log_vector_size and
+  /// value_byte_width one byte each, then num_elements. Derived from the field
+  /// types rather than written out, so that widening a field cannot leave the
+  /// constant behind; StoreHeader and LoadHeader are the two readers of it.
+  static constexpr int64_t kHeaderSize =
+      sizeof(uint8_t) + sizeof(uint8_t) + sizeof(uint8_t) + sizeof(int32_t);
+
+  /// Packing mode: FOR + bit-packing (currently the only mode).
+  static constexpr uint8_t kPackingModeForBitPack = 0;
+};
+
+/// \brief Type traits for PFOR integer types
+template <typename T>
+struct PforTypeTraits {};
+
+template <>
+struct PforTypeTraits<int32_t> {
+  using UnsignedType = uint32_t;
+  static constexpr uint8_t kMaxBitWidth = 32;
+  /// PforVectorInfo size: frame of reference, bit-width byte, exception count.
+  static constexpr int64_t kVectorInfoSize =
+      sizeof(int32_t) + sizeof(uint8_t) + sizeof(PforConstants::ExceptionCountType);
+
+  static uint8_t BitsRequired(uint32_t value) {
+    return static_cast<uint8_t>(std::bit_width(value));
+  }
+};
+
+template <>
+struct PforTypeTraits<int64_t> {
+  using UnsignedType = uint64_t;
+  static constexpr uint8_t kMaxBitWidth = 64;
+  /// PforVectorInfo size: frame of reference, bit-width byte, exception count.
+  static constexpr int64_t kVectorInfoSize =
+      sizeof(int64_t) + sizeof(uint8_t) + sizeof(PforConstants::ExceptionCountType);
+
+  static uint8_t BitsRequired(uint64_t value) {
+    return static_cast<uint8_t>(std::bit_width(value));
+  }
+};
+
+}  // namespace pfor
+}  // namespace util
+}  // namespace arrow
diff --git a/cpp/src/arrow/util/pfor/pfor_internal.h b/cpp/src/arrow/util/pfor/pfor_internal.h
new file mode 100644
index 000000000000..e766f144813f
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor_internal.h
@@ -0,0 +1,237 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Core PFOR (Patched Frame of Reference) compression algorithm
+//
+// PFOR compresses integer columns by:
+//   1. Subtracting the minimum value (Frame of Reference)
+//   2. Choosing an optimal bit width via a cost model
+//   3. Bit-packing the deltas at the chosen width
+//   4. Storing outlier values (exceptions) separately
+
+#pragma once
+
+#include <cstdint>
+#include <cstring>
+#include <span>
+#include <vector>
+
+#include "arrow/result.h"
+#include "arrow/status.h"
+#include "arrow/util/endian.h"
+#include "arrow/util/pfor/pfor_constants_internal.h"
+#include "arrow/util/ubsan.h"
+
+namespace arrow {
+namespace util {
+namespace pfor {
+
+// ----------------------------------------------------------------------
+// Per-vector metadata
+
+/// \brief PFOR vector metadata stored at the start of each compressed vector.
+///
+/// For INT32 (7 bytes): [frame_of_reference(4B)] [bit_width(1B)] [num_exceptions(2B)]
+/// For INT64 (11 bytes): [frame_of_reference(8B)] [bit_width(1B)] [num_exceptions(2B)]
+///
+/// num_exceptions is unsigned: a vector holds up to kMaxVectorSize elements,
+/// so the count has to reach 32768, which a signed 16-bit field cannot hold.
+/// Its wire type is PforConstants::ExceptionCountType.
+///
+/// The bit_width byte stores the actual bit width in bits 0..6; bit 7 is
+/// reserved (always written as 0 and ignored on load), leaving room for a
+/// future flag without changing the layout of existing buffers.
+///
+/// Seven bits, not six: the range is 0..64 inclusive, and 64 does not fit in
+/// six. A 6-bit mask stored an INT64 vector whose deltas need the full 64 bits
+/// as width 0, and since such a vector has no exceptions either, Load reported
+/// a constant vector and the decoder filled the output with the frame of
+/// reference -- silently, with no error and no size mismatch.
+template <typename T>
+class PforVectorInfo {
+ public:
+  static constexpr uint8_t kBitWidthMask = 0x7F;
+
+  PforVectorInfo() = default;
+  PforVectorInfo(T frame_of_reference, uint8_t bit_width,
+                 PforConstants::ExceptionCountType num_exceptions)
+      : frame_of_reference_(frame_of_reference),
+        bit_width_(bit_width),
+        num_exceptions_(num_exceptions) {}
+
+  T frame_of_reference() const { return frame_of_reference_; }
+  uint8_t bit_width() const { return bit_width_; }
+  PforConstants::ExceptionCountType num_exceptions() const { return num_exceptions_; }
+
+  void set_frame_of_reference(T frame_of_reference) {
+    frame_of_reference_ = frame_of_reference;
+  }
+  void set_bit_width(uint8_t bit_width) { bit_width_ = bit_width; }
+  void set_num_exceptions(PforConstants::ExceptionCountType num_exceptions) {
+    num_exceptions_ = num_exceptions;
+  }
+
+  /// \brief Store this info to a byte buffer (little-endian)
+  void Store(std::span<uint8_t> dest) const {
+    uint8_t* ptr = dest.data();
+    util::SafeStore(ptr, bit_util::ToLittleEndian(frame_of_reference_));
+    // bits 0..6 = bit width; bit 7 reserved (0).
+    ptr[sizeof(T)] = static_cast<uint8_t>(bit_width_ & kBitWidthMask);
+    util::SafeStore(ptr + sizeof(T) + 1, bit_util::ToLittleEndian(num_exceptions_));
+  }
+
+  /// \brief Load this info from a byte buffer (little-endian)
+  static Result<PforVectorInfo> Load(std::span<const uint8_t> src) {
+    if (src.size() < static_cast<size_t>(kStoredSize)) {
+      return Status::Invalid("PFOR vector info buffer too small: ", src.size(), " < ",
+                             kStoredSize);
+    }
+    PforVectorInfo info;
+    const uint8_t* ptr = src.data();
+    info.frame_of_reference_ = bit_util::FromLittleEndian(util::SafeLoadAs<T>(ptr));
+    // Mask off the reserved high bit (7).
+    info.bit_width_ = static_cast<uint8_t>(ptr[sizeof(T)] & kBitWidthMask);
+    info.num_exceptions_ = bit_util::FromLittleEndian(
+        util::SafeLoadAs<PforConstants::ExceptionCountType>(ptr + sizeof(T) + 1));
+    if (info.bit_width_ > PforTypeTraits<T>::kMaxBitWidth) {
+      return Status::Invalid("PFOR bit_width out of range: ",
+                             static_cast<int>(info.bit_width_));
+    }
+    if (info.num_exceptions_ > PforConstants::kMaxVectorSize) {
+      return Status::Invalid("PFOR num_exceptions exceeds the maximum vector size: ",
+                             info.num_exceptions_);
+    }
+    return info;
+  }
+
+  /// \brief Serialized size in bytes
+  static constexpr int64_t kStoredSize = PforTypeTraits<T>::kVectorInfoSize;
+
+ private:
+  T frame_of_reference_ = 0;
+  uint8_t bit_width_ = 0;
+  PforConstants::ExceptionCountType num_exceptions_ = 0;
+
+  static_assert(kStoredSize == sizeof(frame_of_reference_) + sizeof(bit_width_) +
+                                   sizeof(num_exceptions_),
+                "kStoredSize must match the fields Store writes and Load reads");
+};
+
+// ----------------------------------------------------------------------
+// Encoded vector representation
+
+/// \brief A PFOR-encoded vector with all its data sections
+template <typename T>
+class PforEncodedVector {
+ public:
+  PforEncodedVector() = default;
+
+  const PforVectorInfo<T>& info() const { return info_; }
+  PforVectorInfo<T>& mutable_info() { return info_; }
+  void set_info(const PforVectorInfo<T>& info) { info_ = info; }
+
+  const std::vector<uint8_t>& packed_values() const { return packed_values_; }
+  std::vector<uint8_t>& mutable_packed_values() { return packed_values_; }
+  void set_packed_values(std::vector<uint8_t> v) { packed_values_ = std::move(v); }
+
+  const std::vector<PforConstants::PositionType>& exception_positions() const {
+    return exception_positions_;
+  }
+  std::vector<PforConstants::PositionType>& mutable_exception_positions() {
+    return exception_positions_;
+  }
+  void set_exception_positions(std::vector<PforConstants::PositionType> v) {
+    exception_positions_ = std::move(v);
+  }
+
+  const std::vector<T>& exception_values() const { return exception_values_; }
+  std::vector<T>& mutable_exception_values() { return exception_values_; }
+  void set_exception_values(std::vector<T> v) { exception_values_ = std::move(v); }
+
+ private:
+  PforVectorInfo<T> info_;
+  std::vector<uint8_t> packed_values_;
+  std::vector<PforConstants::PositionType> exception_positions_;
+  std::vector<T> exception_values_;
+};
+
+// ----------------------------------------------------------------------
+// Cost model result
+
+/// \brief Result of the optimal bit width search
+struct BitWidthResult {
+  uint8_t bit_width = 0;
+  PforConstants::ExceptionCountType num_exceptions = 0;
+};
+
+// ----------------------------------------------------------------------
+// Core compression/decompression
+
+/// \brief PFOR compression and decompression algorithms
+///
+/// \tparam T the integer type (int32_t or int64_t)
+template <typename T>
+class PforCompression {
+ public:
+  using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
+
+  /// \brief Find the optimal bit width using the cost model
+  ///
+  /// Evaluates every candidate bit width and selects the one that
+  /// minimizes total encoded size (packing cost + exception cost).
+  ///
+  /// \param[in] deltas unsigned deltas after FOR subtraction
+  /// \param[in] num_elements number of elements
+  /// \return the optimal bit width and exception count
+  static BitWidthResult FindOptimalBitWidth(const UnsignedT* deltas,
+                                            int32_t num_elements);
+
+  /// \brief Encode a single vector of integers
+  ///
+  /// \param[in] values input integer values
+  /// \param[in] num_elements number of elements (up to vector_size)
+  /// \pre num_elements > 0; the frame of reference is values[0] reduced over the
+  ///      rest, so there is no answer for an empty vector
+  /// \return the encoded vector with all sections
+  static PforEncodedVector<T> EncodeVector(const T* values, int32_t num_elements);
+
+  /// \brief Decode a single vector from compressed data
+  ///
+  /// \param[in] data span over the compressed vector data
+  /// \param[in] num_elements number of elements in this vector
+  /// \param[out] values output buffer for num_elements decoded integers
+  /// \return number of bytes consumed from data, or error
+  static Result<int64_t> DecodeVector(std::span<const uint8_t> data, int32_t num_elements,
+                                      T* values);
+
+  /// \brief Calculate the serialized size of an encoded vector
+  static int64_t SerializedVectorSize(const PforEncodedVector<T>& vec,
+                                      int32_t num_elements);
+
+  /// \brief Serialize an encoded vector to a byte buffer
+  ///
+  /// \param[in] vec the encoded vector
+  /// \param[in] num_elements number of elements
+  /// \param[out] dest output buffer, at least SerializedVectorSize() bytes
+  /// \return number of bytes written, or an error if `dest` is too small
+  static Result<int64_t> SerializeVector(const PforEncodedVector<T>& vec,
+                                         int32_t num_elements, std::span<uint8_t> dest);
+};
+
+}  // namespace pfor
+}  // namespace util
+}  // namespace arrow
diff --git a/cpp/src/arrow/util/pfor/pfor_test.cc b/cpp/src/arrow/util/pfor/pfor_test.cc
new file mode 100644
index 000000000000..85ae04738f09
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor_test.cc
@@ -0,0 +1,773 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <cstdint>
+#include <limits>
+#include <numeric>
+#include <random>
+#include <span>
+#include <string>
+#include <vector>
+
+#include "arrow/testing/gtest_util.h"
+#include "arrow/util/logging.h"
+#include "arrow/util/pfor/pfor_internal.h"
+#include "arrow/util/pfor/pfor_wrapper_internal.h"
+
+namespace arrow::util::pfor {
+
+// ----------------------------------------------------------------------
+// Test fixture
+//
+// PFOR is instantiated for int32_t and int64_t, and the two differ in the
+// widths of the frame of reference, the packed deltas and the exception values,
+// so nearly every test here belongs to both. The helpers hide the width
+// arithmetic; tests that poke at particular byte offsets derive them from
+// sizeof(T) and kStoredSize rather than writing them out.
+
+template <typename T>
+class PforTest : public ::testing::Test {
+ protected:
+  using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
+
+  /// Encode, serialize and decode a single vector, checking that it round-trips.
+  ///
+  /// \param[out] encoded_out the encoded form, for tests that assert on its
+  ///             metadata; may be null
+  void RoundTripVector(const std::vector<T>& values,
+                       PforEncodedVector<T>* encoded_out = nullptr) {
+    const auto num_elements = static_cast<int32_t>(values.size());
+    auto encoded = PforCompression<T>::EncodeVector(values.data(), num_elements);
+
+    const int64_t needed =
+        PforCompression<T>::SerializedVectorSize(encoded, num_elements);
+    std::vector<uint8_t> buffer(needed);
+    ASSERT_OK_AND_ASSIGN(const int64_t written, PforCompression<T>::SerializeVector(
+                                                    encoded, num_elements, buffer));
+    ASSERT_EQ(needed, written);
+
+    std::vector<T> decoded(values.size());
+    ASSERT_OK(PforCompression<T>::DecodeVector(buffer, num_elements, decoded.data()));
+    ASSERT_EQ(values, decoded);
+
+    if (encoded_out != nullptr) {
+      *encoded_out = std::move(encoded);
+    }
+  }
+
+  /// Encode and decode a whole page, checking that it round-trips and stays
+  /// inside the bound the encoder allocates from.
+  ///
+  /// \param[out] comp_size_out the compressed size, for tests that assert on
+  ///             the compression ratio; may be null
+  void RoundTripPage(const std::vector<T>& values, int64_t* comp_size_out = nullptr) {
+    const auto num_values = static_cast<int32_t>(values.size());
+    ASSERT_OK_AND_ASSIGN(const int64_t max_size,
+                         PforWrapper<T>::GetMaxCompressedSize(num_values));
+    std::vector<uint8_t> compressed(max_size);
+    int64_t comp_size = max_size;
+    ASSERT_OK(
+        PforWrapper<T>::Encode(values.data(), num_values, compressed.data(), &comp_size));
+    ASSERT_GT(comp_size, 0);
+    ASSERT_LE(comp_size, max_size);
+
+    std::vector<T> decoded(values.size());
+    ASSERT_OK(
+        PforWrapper<T>::Decode(compressed.data(), comp_size, num_values, decoded.data()));
+    ASSERT_EQ(values, decoded);
+
+    if (comp_size_out != nullptr) {
+      *comp_size_out = comp_size;
+    }
+  }
+
+  /// Encode `values` and return the compressed bytes, sized exactly.
+  static std::vector<uint8_t> EncodePage(const std::vector<T>& values) {
+    const auto num_values = static_cast<int32_t>(values.size());
+    int64_t comp_size = PforWrapper<T>::GetMaxCompressedSize(num_values).ValueOrDie();
+    std::vector<uint8_t> compressed(comp_size);
+    ARROW_CHECK_OK(
+        PforWrapper<T>::Encode(values.data(), num_values, compressed.data(), &comp_size));
+    compressed.resize(comp_size);
+    return compressed;
+  }
+
+  /// Offset of the first vector in a single-vector page: header, then the
+  /// one-entry offset array.
+  static constexpr int64_t kFirstVectorOffset =
+      PforConstants::kHeaderSize +
+      static_cast<int64_t>(sizeof(PforConstants::OffsetType));
+
+  /// Offsets of the PforVectorInfo fields, relative to the start of a vector.
+  static constexpr int64_t kBitWidthOffset = static_cast<int64_t>(sizeof(T));
+  static constexpr int64_t kNumExceptionsOffset = kBitWidthOffset + 1;
+
+  static std::vector<T> RandomValues(int32_t num_values, T min, T max, uint32_t seed) {
+    std::vector<T> values(num_values);
+    std::mt19937 rng(seed);
+    std::uniform_int_distribution<T> dist(min, max);
+    for (auto& v : values) v = dist(rng);
+    return values;
+  }
+};
+
+using PforTypes = ::testing::Types<int32_t, int64_t>;
+TYPED_TEST_SUITE(PforTest, PforTypes);
+
+namespace {
+
+void StoreLE32(uint8_t* dest, uint32_t value) {
+  for (int i = 0; i < 4; ++i) {
+    dest[i] = static_cast<uint8_t>(value >> (8 * i));
+  }
+}
+
+}  // namespace
+
+// ----------------------------------------------------------------------
+// Constants Tests
+
+TEST(PforConstantsTest, VectorSizeIsPowerOfTwo) {
+  EXPECT_EQ(PforConstants::kPforVectorSize, 1024);
+  EXPECT_EQ(1 << PforConstants::kDefaultLogVectorSize, PforConstants::kPforVectorSize);
+}
+
+TEST(PforConstantsTest, VectorInfoSizes) {
+  EXPECT_EQ(PforTypeTraits<int32_t>::kVectorInfoSize, 7);
+  EXPECT_EQ(PforTypeTraits<int64_t>::kVectorInfoSize, 11);
+}
+
+// ----------------------------------------------------------------------
+// BitsRequired Tests
+
+TYPED_TEST(PforTest, BitsRequired) {
+  using T = TypeParam;
+  using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
+
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(0), 0);
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(1), 1);
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(2), 2);
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(3), 2);
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(255), 8);
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(256), 9);
+  EXPECT_EQ(PforTypeTraits<T>::BitsRequired(std::numeric_limits<UnsignedT>::max()),
+            PforTypeTraits<T>::kMaxBitWidth);
+}
+
+// ----------------------------------------------------------------------
+// VectorInfo Serialization Tests
+
+TYPED_TEST(PforTest, VectorInfoRoundTrip) {
+  using T = TypeParam;
+  PforVectorInfo<T> info;
+  info.set_frame_of_reference(-42);
+  info.set_bit_width(17);
+  info.set_num_exceptions(300);
+
+  std::vector<uint8_t> buf(PforVectorInfo<T>::kStoredSize);
+  info.Store(buf);
+  ASSERT_OK_AND_ASSIGN(auto loaded, PforVectorInfo<T>::Load(buf));
+
+  EXPECT_EQ(loaded.frame_of_reference(), -42);
+  EXPECT_EQ(loaded.bit_width(), 17);
+  EXPECT_EQ(loaded.num_exceptions(), 300);
+}
+
+// The extremes of every field at once: the widest frame of reference the type
+// can hold and the full bit width. A six-bit width field could not store 64,
+// and reported such a vector as constant.
+TYPED_TEST(PforTest, VectorInfoRoundTripAtFieldExtremes) {
+  using T = TypeParam;
+  constexpr T kFrameOfReference = std::numeric_limits<T>::min();
+  PforVectorInfo<T> info(kFrameOfReference, PforTypeTraits<T>::kMaxBitWidth, 30000);
+
+  std::vector<uint8_t> buf(PforVectorInfo<T>::kStoredSize);
+  info.Store(buf);
+  ASSERT_OK_AND_ASSIGN(auto loaded, PforVectorInfo<T>::Load(buf));
+
+  EXPECT_EQ(loaded.frame_of_reference(), kFrameOfReference);
+  EXPECT_EQ(loaded.bit_width(), PforTypeTraits<T>::kMaxBitWidth);
+  EXPECT_EQ(loaded.num_exceptions(), 30000);
+}
+
+// Every element of a maximum-size vector can be an exception, so the count has
+// to reach kMaxVectorSize. A signed 16-bit field stopped one short of that.
+TYPED_TEST(PforTest, VectorInfoNumExceptionsAtMaxVectorSize) {
+  using T = TypeParam;
+  PforVectorInfo<T> info;
+  info.set_bit_width(3);
+  info.set_num_exceptions(PforConstants::kMaxVectorSize);
+
+  std::vector<uint8_t> buf(PforVectorInfo<T>::kStoredSize);
+  info.Store(buf);
+  ASSERT_OK_AND_ASSIGN(auto loaded, PforVectorInfo<T>::Load(buf));
+
+  EXPECT_EQ(loaded.num_exceptions(), PforConstants::kMaxVectorSize);
+}
+
+TYPED_TEST(PforTest, VectorInfoRejectsNumExceptionsAboveMaxVectorSize) {
+  using T = TypeParam;
+  // [FOR] [bit_width 1B] [num_exceptions 2B], with a count no vector can have.
+  std::vector<uint8_t> buf(PforVectorInfo<T>::kStoredSize, 0);
+  buf[TestFixture::kBitWidthOffset] = 3;
+  buf[TestFixture::kNumExceptionsOffset] = 0xFF;
+  buf[TestFixture::kNumExceptionsOffset + 1] = 0xFF;
+  ASSERT_RAISES(Invalid, PforVectorInfo<T>::Load(buf));
+}
+
+TYPED_TEST(PforTest, VectorInfoRejectsUndersizedBuffer) {
+  using T = TypeParam;
+  std::vector<uint8_t> buf(PforVectorInfo<T>::kStoredSize - 1, 0);
+  ASSERT_RAISES(Invalid, PforVectorInfo<T>::Load(buf));
+}
+
+// ----------------------------------------------------------------------
+// Cost Model Tests
+
+TYPED_TEST(PforTest, CostModelAllIdentical) {
+  using T = TypeParam;
+  using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
+  // All deltas are 0 => bit_width should be 0, no exceptions
+  std::vector<UnsignedT> deltas(100, 0);
+  auto result = PforCompression<T>::FindOptimalBitWidth(deltas.data(), 100);
+  EXPECT_EQ(result.bit_width, 0);
+  EXPECT_EQ(result.num_exceptions, 0);
+}
+
+TYPED_TEST(PforTest, CostModelSingleOutlier) {
+  using T = TypeParam;
+  using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
+  // 99 values fit in 3 bits, 1 outlier needs 16 bits
+  std::vector<UnsignedT> deltas(100, 5);  // all fit in 3 bits
+  deltas[50] = 50000;                     // outlier: 16 bits
+  auto result = PforCompression<T>::FindOptimalBitWidth(deltas.data(), 100);
+  // An exception costs a 16-bit position plus a full-width value, so at
+  // bit_width=3 the vector costs 100*3 + 1*(16 + 8*sizeof(T)) bits, against
+  // 100*16 at bit_width=16. Patching the one outlier wins for both widths of T.
+  EXPECT_EQ(result.bit_width, 3);
+  EXPECT_EQ(result.num_exceptions, 1);
+}
+
+TYPED_TEST(PforTest, CostModelNoOutliers) {
+  using T = TypeParam;
+  using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
+  // All values fit in 8 bits
+  std::vector<UnsignedT> deltas(100);
+  for (int32_t i = 0; i < 100; ++i) deltas[i] = i * 2;
+  auto result = PforCompression<T>::FindOptimalBitWidth(deltas.data(), 100);
+  EXPECT_EQ(result.num_exceptions, 0);
+  EXPECT_LE(result.bit_width, 8);
+}
+
+// ----------------------------------------------------------------------
+// Vector Encode/Decode Round-Trip Tests
+
+TYPED_TEST(PforTest, VectorSimpleSequence) {
+  using T = TypeParam;
+  std::vector<T> values(64);
+  std::iota(values.begin(), values.end(), 100);
+
+  PforEncodedVector<T> encoded;
+  this->RoundTripVector(values, &encoded);
+  EXPECT_EQ(encoded.info().frame_of_reference(), 100);
+  EXPECT_EQ(encoded.info().num_exceptions(), 0);
+}
+
+TYPED_TEST(PforTest, VectorWithOutlier) {
+  using T = TypeParam;
+  std::vector<T> values = {100, 102, 101, 103, 100, 99, 50000, 104};
+
+  PforEncodedVector<T> encoded;
+  this->RoundTripVector(values, &encoded);
+  EXPECT_EQ(encoded.info().frame_of_reference(), 99);
+  EXPECT_GT(encoded.info().num_exceptions(), 0);
+}
+
+TYPED_TEST(PforTest, VectorAllIdentical) {
+  using T = TypeParam;
+  std::vector<T> values(100, 42);
+
+  PforEncodedVector<T> encoded;
+  this->RoundTripVector(values, &encoded);
+  EXPECT_EQ(encoded.info().bit_width(), 0);
+  EXPECT_EQ(encoded.info().num_exceptions(), 0);
+}
+
+TYPED_TEST(PforTest, VectorNegativeValues) {
+  using T = TypeParam;
+  std::vector<T> values = {-100, -50, -200, -1, -150};
+
+  PforEncodedVector<T> encoded;
+  this->RoundTripVector(values, &encoded);
+  EXPECT_EQ(encoded.info().frame_of_reference(), -200);
+}
+
+// The frame of reference is subtracted in the unsigned domain, so a vector
+// spanning the whole range of T has a delta that only wraps to the right answer.
+TYPED_TEST(PforTest, VectorMinMaxEdge) {
+  using T = TypeParam;
+  std::vector<T> values = {std::numeric_limits<T>::min(), std::numeric_limits<T>::max(),
+                           0, -1, 1};
+  this->RoundTripVector(values);
+}
+
+TYPED_TEST(PforTest, VectorSingleElement) {
+  using T = TypeParam;
+  this->RoundTripVector(std::vector<T>{42});
+}
+
+// ----------------------------------------------------------------------
+// Page-Level Wrapper Tests
+
+TYPED_TEST(PforTest, PageSmall) { this->RoundTripPage({10, 20, 30, 40, 50}); }
+
+TYPED_TEST(PforTest, PageExactOneVector) {
+  using T = TypeParam;
+  std::vector<T> values(PforConstants::kPforVectorSize);
+  std::iota(values.begin(), values.end(), 0);
+  this->RoundTripPage(values);
+}
+
+TYPED_TEST(PforTest, PageMultipleVectors) {
+  // 2.5 vectors worth of data
+  this->RoundTripPage(TestFixture::RandomValues(2560, 0, 1000, /*seed=*/42));
+}
+
+TYPED_TEST(PforTest, PageWithOutliers) {
+  using T = TypeParam;
+  std::vector<T> values(1024, 100);
+  values[0] = -999999;
+  values[100] = 888888;
+  values[500] = 777777;
+  values[1023] = -123456;
+  this->RoundTripPage(values);
+}
+
+TYPED_TEST(PforTest, PagePartialTrailingVector) {
+  using T = TypeParam;
+  auto values = TestFixture::RandomValues(3000, 0, 100000, /*seed=*/123);
+  values[0] = std::numeric_limits<T>::max() / 2;
+  values[1500] = std::numeric_limits<T>::min() / 2;
+  this->RoundTripPage(values);
+}
+
+TYPED_TEST(PforTest, PageSingleElement) {
+  using T = TypeParam;
+  this->RoundTripPage(std::vector<T>{42});
+}
+
+TYPED_TEST(PforTest, PageAllZeros) {
+  using T = TypeParam;
+  std::vector<T> values(1024, 0);
+  int64_t comp_size = 0;
+  this->RoundTripPage(values, &comp_size);
+  // bit_width is 0, so the page is header, offset array and vector info only.
+  EXPECT_LT(comp_size, 100);
+}
+
+TYPED_TEST(PforTest, PageLargeRandom) {
+  using T = TypeParam;
+  this->RoundTripPage(TestFixture::RandomValues(10000, std::numeric_limits<T>::min(),
+                                                std::numeric_limits<T>::max(),
+                                                /*seed=*/99));
+}
+
+// Covers the FOR==0 fast path (bit_width > 0 with frame_of_reference == 0):
+// decode unpacks straight into the output, skipping the scratch buffer and the
+// add-FOR pass. Forces min == 0, a range that needs bit_width > 0, outliers to
+// exercise the exception patch on that path, and multiple vectors.
+TYPED_TEST(PforTest, PageZeroMinWithExceptions) {
+  auto values = TestFixture::RandomValues(3000, 0, 500, /*seed=*/2024);
+  values[0] = 0;            // force min == 0 -> FOR == 0
+  values[100] = 1'000'000;  // outliers -> exceptions on the FOR==0 path
+  values[1500] = 999'999;
+  values[2999] = 500'000;
+  this->RoundTripPage(values);
+}
+
+// ----------------------------------------------------------------------
+// Encode Argument Validation
+
+TYPED_TEST(PforTest, EncodeZeroValuesWritesABareHeader) {
+  using T = TypeParam;
+  // An all-null page holds no values, and the reader still has to be able to load
+  // a header from it, so zero values encodes to the header and nothing else. The
+  // pointer is null because the buffer the values would come from is empty.
+  std::vector<uint8_t> compressed(64);
+  int64_t comp_size = 64;
+  ASSERT_OK(PforWrapper<T>::Encode(nullptr, 0, compressed.data(), &comp_size));
+  ASSERT_EQ(PforConstants::kHeaderSize, comp_size);
+
+  ASSERT_OK_AND_ASSIGN(const int32_t count,
+                       PforWrapper<T>::DecodeElementCount(compressed.data(), comp_size));
+  ASSERT_EQ(0, count);
+  ASSERT_OK(PforWrapper<T>::Decode(compressed.data(), comp_size, 0, nullptr));
+}
+
+TYPED_TEST(PforTest, EncodeRejectsNegativeCount) {
+  using T = TypeParam;
+  std::vector<T> values = {1, 2, 3};
+  std::vector<uint8_t> compressed(64);
+  int64_t comp_size = 64;
+  ASSERT_RAISES(Invalid,
+                PforWrapper<T>::Encode(values.data(), -1, compressed.data(), &comp_size));
+}
+
+TYPED_TEST(PforTest, EncodeRejectsNullInputWithValuesToEncode) {
+  using T = TypeParam;
+  std::vector<uint8_t> compressed(64);
+  int64_t comp_size = 64;
+  ASSERT_RAISES(Invalid,
+                PforWrapper<T>::Encode(nullptr, 3, compressed.data(), &comp_size));
+}
+
+TYPED_TEST(PforTest, EncodeRejectsUnrepresentableVectorSize) {
+  using T = TypeParam;
+  std::vector<T> values = {1, 2, 3};
+  std::vector<uint8_t> compressed(64);
+
+  // Not a power of two.
+  int64_t comp_size = 64;
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Encode(values.data(), 3, 1000, compressed.data(),
+                                                &comp_size));
+
+  // A power of two, but the header's log_vector_size field cannot describe it.
+  comp_size = 64;
+  ASSERT_RAISES(
+      Invalid, PforWrapper<T>::Encode(values.data(), 3, PforConstants::kMaxVectorSize * 2,
+                                      compressed.data(), &comp_size));
+}
+
+// ----------------------------------------------------------------------
+// Compression Ratio Test
+
+TYPED_TEST(PforTest, ClusteredDataCompresses) {
+  using T = TypeParam;
+  // Data clustered around 1000 with one outlier
+  auto values = TestFixture::RandomValues(1024, 1000, 1255, /*seed=*/42);
+  values[500] = 999999;
+
+  int64_t comp_size = 0;
+  this->RoundTripPage(values, &comp_size);
+
+  const size_t plain_size = 1024 * sizeof(T);
+  EXPECT_LT(comp_size, static_cast<int64_t>(plain_size / 2));
+}
+
+// ----------------------------------------------------------------------
+// Corrupt Page Tests
+//
+// A PFOR page can come from anywhere, so Decode has to reject a header that
+// disagrees with the buffer it arrived in rather than trusting it and reading
+// or writing out of bounds.
+
+namespace {
+
+// A tight cluster plus one far outlier, so the cost model packs narrow and
+// patches the outlier. The outlier is 31 bits out rather than 16: an exception
+// costs a position plus a full-width value, so a 16-bit outlier is cheaper to
+// pack than to patch once the values are 64 bits wide, and the tests below need
+// a vector that actually has an exception section.
+template <typename T>
+std::vector<T> ClusterWithOutlier() {
+  return {10, 20, 30, 40, 2'000'000'000};
+}
+
+}  // namespace
+
+TYPED_TEST(PforTest, DecodeElementCountReadsThePageHeader) {
+  using T = TypeParam;
+  std::vector<T> values(2048);
+  std::iota(values.begin(), values.end(), 0);
+  auto compressed = TestFixture::EncodePage(values);
+
+  ASSERT_OK_AND_ASSIGN(const int32_t count, PforWrapper<T>::DecodeElementCount(
+                                                compressed.data(), compressed.size()));
+  EXPECT_EQ(count, static_cast<int32_t>(values.size()));
+}
+
+TYPED_TEST(PforTest, DecodeElementCountRejectsMalformedInput) {
+  using T = TypeParam;
+  const std::vector<T> values = {10, 20, 30, 40, 50};
+  auto compressed = TestFixture::EncodePage(values);
+
+  ASSERT_RAISES(Invalid, PforWrapper<T>::DecodeElementCount(
+                             compressed.data(), PforConstants::kHeaderSize - 1));
+  ASSERT_RAISES(Invalid, PforWrapper<T>::DecodeElementCount(nullptr, compressed.size()));
+  ASSERT_RAISES(Invalid, PforWrapper<T>::DecodeElementCount(compressed.data(), -1));
+}
+
+TYPED_TEST(PforTest, CorruptBufferTooSmallForHeader) {
+  using T = TypeParam;
+  const std::vector<T> values = {10, 20, 30, 40, 50};
+  auto compressed = TestFixture::EncodePage(values);
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid,
+                PforWrapper<T>::Decode(compressed.data(), PforConstants::kHeaderSize - 1,
+                                       5, decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptElementCountExceedsOutputCapacity) {
+  using T = TypeParam;
+  const std::vector<T> values = {10, 20, 30, 40, 50};
+  auto compressed = TestFixture::EncodePage(values);
+
+  // num_elements lives at header byte 3.
+  StoreLE32(compressed.data() + 3, 6);
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(), 5,
+                                                decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptElementCountBelowOutputCapacity) {
+  using T = TypeParam;
+  const std::vector<T> values = {10, 20, 30, 40, 50};
+  auto compressed = TestFixture::EncodePage(values);
+
+  // A count short of the caller's capacity would fill part of the output and
+  // leave the rest holding whatever it held before.
+  StoreLE32(compressed.data() + 3, 4);
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(), 5,
+                                                decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptOffsetArrayTruncated) {
+  using T = TypeParam;
+  // Four vectors, so the offset array is 16 bytes; hand Decode a buffer with
+  // room for only two of them.
+  std::vector<T> values(4096);
+  std::iota(values.begin(), values.end(), 0);
+  auto compressed = TestFixture::EncodePage(values);
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid,
+                PforWrapper<T>::Decode(compressed.data(), PforConstants::kHeaderSize + 8,
+                                       4096, decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptVectorOffsetPastEndOfBuffer) {
+  using T = TypeParam;
+  std::vector<T> values(2048);
+  std::iota(values.begin(), values.end(), 0);
+  auto compressed = TestFixture::EncodePage(values);
+
+  // Point the second vector past the end of the buffer.
+  StoreLE32(compressed.data() + TestFixture::kFirstVectorOffset,
+            static_cast<uint32_t>(compressed.size()));
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(),
+                                                2048, decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptFirstVectorOffsetSkipsTheOffsetArray) {
+  using T = TypeParam;
+  const std::vector<T> values = {10, 20, 30, 40, 50};
+  auto compressed = TestFixture::EncodePage(values);
+
+  // One vector, so its data starts right after the four byte offset array.
+  StoreLE32(compressed.data() + PforConstants::kHeaderSize, 5);
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(), 5,
+                                                decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptVectorOffsetsRunBackwards) {
+  using T = TypeParam;
+  std::vector<T> values(2048);
+  std::iota(values.begin(), values.end(), 0);
+  auto compressed = TestFixture::EncodePage(values);
+
+  // Point the second vector at the first one's data. Both offsets are inside the
+  // buffer, so only reading them as a chain catches it.
+  StoreLE32(compressed.data() + TestFixture::kFirstVectorOffset,
+            static_cast<uint32_t>(2 * sizeof(PforConstants::OffsetType)));
+
+  std::vector<T> decoded(values.size());
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(),
+                                                2048, decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptExceptionPositionPastEndOfVector) {
+  using T = TypeParam;
+  const std::vector<T> values = ClusterWithOutlier<T>();
+  auto compressed = TestFixture::EncodePage(values);
+
+  // Locate the stored exception position: the vector info, then the packed
+  // deltas at whatever width the cost model chose.
+  const int64_t vector_start = TestFixture::kFirstVectorOffset;
+  ASSERT_GT(compressed[vector_start + TestFixture::kNumExceptionsOffset], 0)
+      << "the cost model packed this vector without exceptions, so there is no "
+         "exception position to corrupt";
+  const uint8_t bit_width = compressed[vector_start + TestFixture::kBitWidthOffset];
+  const int64_t packed_bytes = (5 * bit_width + 7) / 8;
+  const int64_t position_offset =
+      vector_start + PforVectorInfo<T>::kStoredSize + packed_bytes;
+
+  // Point the exception at index 100 of a five-element vector.
+  compressed[position_offset] = 100;
+  compressed[position_offset + 1] = 0;
+
+  std::vector<T> decoded(5);
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(), 5,
+                                                decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptExceptionCountExceedsVectorLength) {
+  using T = TypeParam;
+  const std::vector<T> values = ClusterWithOutlier<T>();
+  auto compressed = TestFixture::EncodePage(values);
+
+  const int64_t vector_start = TestFixture::kFirstVectorOffset;
+  compressed[vector_start + TestFixture::kNumExceptionsOffset] = 6;
+  compressed[vector_start + TestFixture::kNumExceptionsOffset + 1] = 0;
+
+  std::vector<T> decoded(5);
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Decode(compressed.data(), compressed.size(), 5,
+                                                decoded.data()));
+}
+
+TYPED_TEST(PforTest, CorruptExceptionDataTruncated) {
+  using T = TypeParam;
+  const std::vector<T> values = ClusterWithOutlier<T>();
+  auto compressed = TestFixture::EncodePage(values);
+
+  // Drop the trailing exception value, leaving its position behind.
+  ASSERT_GT(
+      compressed[TestFixture::kFirstVectorOffset + TestFixture::kNumExceptionsOffset], 0);
+  std::vector<T> decoded(5);
+  ASSERT_RAISES(
+      Invalid, PforWrapper<T>::Decode(compressed.data(),
+                                      static_cast<int64_t>(compressed.size() - sizeof(T)),
+                                      5, decoded.data()));
+}
+
+// ----------------------------------------------------------------------
+// Output sizing
+
+TYPED_TEST(PforTest, MaxCompressedSizeRejectsInvalidArguments) {
+  using T = TypeParam;
+  ASSERT_RAISES(Invalid, PforWrapper<T>::GetMaxCompressedSize(-1));
+  // A zero vector_size would divide by zero on the way to the answer.
+  for (const int32_t vector_size : {0, 3, 1000, PforConstants::kMaxVectorSize * 2}) {
+    SCOPED_TRACE("vector_size=" + std::to_string(vector_size));
+    ASSERT_RAISES(Invalid, PforWrapper<T>::GetMaxCompressedSize(1024, vector_size));
+    std::vector<T> values(16, 0);
+    int64_t comp_size = 1 << 20;
+    std::vector<uint8_t> compressed(comp_size);
+    ASSERT_RAISES(Invalid, PforWrapper<T>::Encode(values.data(), 16, vector_size,
+                                                  compressed.data(), &comp_size));
+  }
+}
+
+TYPED_TEST(PforTest, EncodeRejectsUndersizedOutputBuffer) {
+  using T = TypeParam;
+  std::vector<T> values(1024);
+  std::iota(values.begin(), values.end(), 0);
+  ASSERT_OK_AND_ASSIGN(const int64_t max_size,
+                       PforWrapper<T>::GetMaxCompressedSize(1024));
+
+  std::vector<uint8_t> compressed(max_size);
+  int64_t comp_size = max_size - 1;
+  ASSERT_RAISES(Invalid, PforWrapper<T>::Encode(values.data(), 1024, compressed.data(),
+                                                &comp_size));
+}
+
+TYPED_TEST(PforTest, SerializeVectorRejectsUndersizedDestination) {
+  using T = TypeParam;
+  std::vector<T> values(64);
+  std::iota(values.begin(), values.end(), 0);
+  const auto encoded = PforCompression<T>::EncodeVector(values.data(), 64);
+  const int64_t needed = PforCompression<T>::SerializedVectorSize(encoded, 64);
+
+  std::vector<uint8_t> buffer(needed);
+  ASSERT_OK_AND_ASSIGN(const int64_t written,
+                       PforCompression<T>::SerializeVector(encoded, 64, buffer));
+  ASSERT_EQ(needed, written);
+  ASSERT_RAISES(Invalid, PforCompression<T>::SerializeVector(
+                             encoded, 64, std::span<uint8_t>(buffer).subspan(1)));
+}
+
+// SerializedVectorSize is derived from the vector info, while the copy that
+// follows it takes its lengths from the sections, so a vector whose info and
+// sections disagree has to be refused rather than written past the size the
+// caller reserved.
+TYPED_TEST(PforTest, SerializeVectorRejectsInfoInconsistentWithSections) {
+  using T = TypeParam;
+  std::vector<T> values(64);
+  std::iota(values.begin(), values.end(), 0);
+  const auto encoded = PforCompression<T>::EncodeVector(values.data(), 64);
+  std::vector<uint8_t> buffer(PforCompression<T>::SerializedVectorSize(encoded, 64) + 64);
+
+  {
+    // A bit width that does not account for the packed bytes present.
+    auto corrupted = encoded;
+    corrupted.mutable_info().set_bit_width(
+        static_cast<uint8_t>(encoded.info().bit_width() + 1));
+    ASSERT_RAISES(Invalid, PforCompression<T>::SerializeVector(corrupted, 64, buffer));
+  }
+  {
+    // An exception count with no exception sections behind it.
+    auto corrupted = encoded;
+    corrupted.mutable_info().set_num_exceptions(1);
+    ASSERT_RAISES(Invalid, PforCompression<T>::SerializeVector(corrupted, 64, buffer));
+  }
+}
+
+// GetMaxCompressedSize is what the encoder allocates, and it is derived from the
+// cost model rather than from a worst case that assumes every value is an
+// exception, so inputs that push the model in different directions all have to
+// land inside it.
+TYPED_TEST(PforTest, MaxCompressedSizeBoundHoldsForAdversarialInputs) {
+  using T = TypeParam;
+  constexpr int32_t kNumValues = 3000;
+  std::mt19937 rng(7);
+  std::uniform_int_distribution<T> full_range(std::numeric_limits<T>::min(),
+                                              std::numeric_limits<T>::max());
+
+  std::vector<std::vector<T>> inputs;
+  // Incompressible: every delta needs the full width, so the model picks it.
+  inputs.emplace_back(kNumValues);
+  for (auto& v : inputs.back()) v = full_range(rng);
+  // A narrow cluster with a scatter of far-away values, which is the case that
+  // trades bit width against exception count.
+  inputs.emplace_back(kNumValues, 1000);
+  for (int32_t i = 0; i < kNumValues; i += 3) {
+    inputs.back()[i] = full_range(rng);
+  }
+  // Alternating extremes, so the frame of reference cannot help.
+  inputs.emplace_back(kNumValues);
+  for (int32_t i = 0; i < kNumValues; ++i) {
+    inputs.back()[i] =
+        (i % 2 == 0) ? std::numeric_limits<T>::min() : std::numeric_limits<T>::max();
+  }
+
+  for (size_t i = 0; i < inputs.size(); ++i) {
+    SCOPED_TRACE("input " + std::to_string(i));
+    this->RoundTripPage(inputs[i]);
+  }
+}
+
+}  // namespace arrow::util::pfor
diff --git a/cpp/src/arrow/util/pfor/pfor_wrapper.cc b/cpp/src/arrow/util/pfor/pfor_wrapper.cc
new file mode 100644
index 000000000000..0dd3e1c04f39
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor_wrapper.cc
@@ -0,0 +1,416 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// PFOR page-level wrapper implementation
+//
+// Page layout:
+//   [Header 7B] [Offset Array: numVectors * 4B] [Vector 0] [Vector 1] ...
+//
+// Each vector:
+//   [PforVectorInfo] [PackedValues] [ExceptionPositions] [ExceptionValues]
+
+#include "arrow/util/pfor/pfor_wrapper_internal.h"
+
+#include <algorithm>
+#include <bit>
+#include <cstring>
+#include <span>
+#include <vector>
+
+#include "arrow/util/bit_util.h"
+#include "arrow/util/endian.h"
+#include "arrow/util/logging.h"
+#include "arrow/util/ubsan.h"
+
+namespace arrow {
+namespace util {
+namespace pfor {
+
+namespace {
+
+/// Width of one entry in the per-page offset array.
+constexpr int64_t kOffsetSize = sizeof(PforConstants::OffsetType);
+
+/// \brief Accept only the vector sizes the page header can describe
+///
+/// A size outside this range would encode a page that Decode then rejects, so
+/// refuse it up front.
+Status ValidateVectorSize(int32_t vector_size) {
+  if (!std::has_single_bit(static_cast<uint32_t>(vector_size)) ||
+      vector_size < (1 << PforConstants::kMinLogVectorSize) ||
+      vector_size > PforConstants::kMaxVectorSize) {
+    return Status::Invalid("PFOR vector_size must be a power of two in [",
+                           1 << PforConstants::kMinLogVectorSize, ", ",
+                           PforConstants::kMaxVectorSize, "]: ", vector_size);
+  }
+  return Status::OK();
+}
+
+/// \brief Check the offset array before any of it steers a read
+///
+/// The offsets are byte counts from the start of the offset array, and the
+/// vectors they point at were written back to back in order, so a well-formed
+/// page has the first offset landing just past the array and the rest strictly
+/// increasing. Checking the chain as a whole, before decoding any of it, keeps a
+/// page whose offsets overlap or run backwards from decoding part-way and
+/// emitting values built out of the wrong bytes.
+Status ValidateOffsets(const uint8_t* offset_array_start, int32_t num_vectors,
+                       int64_t offset_array_size, int64_t payload_size) {
+  int64_t previous = -1;
+  for (int32_t v = 0; v < num_vectors; ++v) {
+    const int64_t offset =
+        bit_util::FromLittleEndian(util::SafeLoadAs<PforConstants::OffsetType>(
+            offset_array_start + v * kOffsetSize));
+    if (v == 0) {
+      if (offset != offset_array_size) {
+        return Status::Invalid("PFOR first vector offset ", offset,
+                               " does not follow the ", offset_array_size,
+                               " byte offset array");
+      }
+    } else if (offset <= previous) {
+      return Status::Invalid("PFOR vector ", v, " offset ", offset,
+                             " does not follow offset ", previous,
+                             " of the vector before it");
+    }
+    if (offset >= payload_size) {
+      return Status::Invalid("PFOR vector ", v, " offset ", offset,
+                             " is past the end of the ", payload_size, " byte payload");
+    }
+    previous = offset;
+  }
+  return Status::OK();
+}
+
+}  // namespace
+
+// ----------------------------------------------------------------------
+// Header serialization
+
+template <typename T>
+void PforWrapper<T>::StoreHeader(std::span<uint8_t> dest, const PforHeader& header) {
+  static_assert(PforConstants::kHeaderSize == sizeof(PforHeader::packing_mode) +
+                                                  sizeof(PforHeader::log_vector_size) +
+                                                  sizeof(PforHeader::value_byte_width) +
+                                                  sizeof(PforHeader::num_elements),
+                "kHeaderSize must match the fields StoreHeader and LoadHeader move");
+  uint8_t* ptr = dest.data();
+  util::SafeStore(ptr + 0, header.packing_mode);
+  util::SafeStore(ptr + 1, header.log_vector_size);
+  util::SafeStore(ptr + 2, header.value_byte_width);
+  util::SafeStore(ptr + 3, bit_util::ToLittleEndian(header.num_elements));
+}
+
+template <typename T>
+Result<typename PforWrapper<T>::PforHeader> PforWrapper<T>::LoadHeader(
+    std::span<const uint8_t> src) {
+  if (src.size() < static_cast<size_t>(PforConstants::kHeaderSize)) {
+    return Status::Invalid("PFOR compressed buffer too small for header: ", src.size(),
+                           " < ", PforConstants::kHeaderSize);
+  }
+  PforHeader header;
+  const uint8_t* ptr = src.data();
+  header.packing_mode = util::SafeLoadAs<uint8_t>(ptr + 0);
+  header.log_vector_size = util::SafeLoadAs<uint8_t>(ptr + 1);
+  header.value_byte_width = util::SafeLoadAs<uint8_t>(ptr + 2);
+  header.num_elements = bit_util::FromLittleEndian(util::SafeLoadAs<int32_t>(ptr + 3));
+
+  if (header.packing_mode != PforConstants::kPackingModeForBitPack) {
+    return Status::Invalid("PFOR unsupported packing mode: ",
+                           static_cast<int>(header.packing_mode));
+  }
+  if (header.value_byte_width != sizeof(T)) {
+    return Status::Invalid(
+        "PFOR value_byte_width mismatch: ", static_cast<int>(header.value_byte_width),
+        " vs expected ", sizeof(T));
+  }
+  if (header.log_vector_size < PforConstants::kMinLogVectorSize ||
+      header.log_vector_size > PforConstants::kMaxLogVectorSize) {
+    return Status::Invalid("PFOR invalid log_vector_size: ",
+                           static_cast<int>(header.log_vector_size));
+  }
+  if (header.num_elements < 0) {
+    return Status::Invalid("PFOR invalid num_elements: ", header.num_elements);
+  }
+  return header;
+}
+
+// ----------------------------------------------------------------------
+// Encode
+
+template <typename T>
+Status PforWrapper<T>::Encode(const T* values, int32_t num_values, int32_t vector_size,
+                              uint8_t* comp, int64_t* comp_size) {
+  if (num_values < 0) {
+    return Status::Invalid("PFOR num_values must be non-negative: ", num_values);
+  }
+  // An all-null page holds no values and is still written, and a reader loads the
+  // header before it knows how many values a page has, so zero values encodes to a
+  // bare header rather than to nothing at all. The buffer it comes from is empty in
+  // that case, and an empty container is entitled to a null data pointer.
+  if (values == nullptr && num_values > 0) {
+    return Status::Invalid("PFOR input pointer is null");
+  }
+  if (comp == nullptr) {
+    return Status::Invalid("PFOR output pointer is null");
+  }
+  if (comp_size == nullptr) {
+    return Status::Invalid("PFOR output size pointer is null");
+  }
+  RETURN_NOT_OK(ValidateVectorSize(vector_size));
+
+  // Everything below writes into `comp` without re-checking, including the
+  // header and the offset array, so confirm once that the caller gave us the
+  // buffer the API asks for.
+  ARROW_ASSIGN_OR_RAISE(const int64_t max_size,
+                        GetMaxCompressedSize(num_values, vector_size));
+  if (*comp_size < max_size) {
+    return Status::Invalid("PFOR output buffer of ", *comp_size,
+                           " bytes is smaller than the ", max_size, " bytes ", num_values,
+                           " values may need");
+  }
+
+  const int32_t num_vectors =
+      static_cast<int32_t>(bit_util::CeilDiv(num_values, vector_size));
+
+  // ValidateVectorSize has already established that vector_size is a power of
+  // two, so its trailing-zero count is log2 of it.
+  const auto log_vector_size =
+      static_cast<uint8_t>(std::countr_zero(static_cast<uint32_t>(vector_size)));
+
+  uint8_t* dest = comp;
+
+  // Step 1: Write header
+  PforHeader header;
+  header.packing_mode = PforConstants::kPackingModeForBitPack;
+  header.log_vector_size = log_vector_size;
+  header.value_byte_width = sizeof(T);
+  header.num_elements = num_values;
+  StoreHeader(std::span<uint8_t>(dest, PforConstants::kHeaderSize), header);
+  uint8_t* write_ptr = dest + PforConstants::kHeaderSize;
+
+  // Step 2: Reserve space for offset array
+  uint8_t* offset_array_start = write_ptr;
+  write_ptr += num_vectors * kOffsetSize;
+
+  // Step 3: Encode each vector and build offset array
+  const uint8_t* data_start = offset_array_start;
+
+  for (int32_t v = 0; v < num_vectors; ++v) {
+    // Record offset (from start of offset array)
+    const auto offset = static_cast<PforConstants::OffsetType>(write_ptr - data_start);
+    util::SafeStore(offset_array_start + v * kOffsetSize,
+                    bit_util::ToLittleEndian(offset));
+
+    // Determine elements in this vector
+    int32_t start_idx = v * vector_size;
+    int32_t elements_in_vector = std::min(vector_size, num_values - start_idx);
+
+    auto encoded =
+        PforCompression<T>::EncodeVector(values + start_idx, elements_in_vector);
+
+    // Serialize to output
+    ARROW_ASSIGN_OR_RAISE(
+        const int64_t bytes_written,
+        PforCompression<T>::SerializeVector(
+            encoded, elements_in_vector,
+            std::span<uint8_t>(write_ptr, dest + *comp_size - write_ptr)));
+    write_ptr += bytes_written;
+  }
+
+  *comp_size = static_cast<int64_t>(write_ptr - dest);
+  return Status::OK();
+}
+
+template <typename T>
+Status PforWrapper<T>::Encode(const T* values, int32_t num_values, uint8_t* comp,
+                              int64_t* comp_size) {
+  return Encode(values, num_values, kVectorSize, comp, comp_size);
+}
+
+// ----------------------------------------------------------------------
+// Decode
+
+template <typename T>
+Status PforWrapper<T>::Decode(const uint8_t* comp, int64_t comp_size, int32_t num_values,
+                              T* values) {
+  if (num_values < 0) {
+    return Status::Invalid("PFOR num_values must be non-negative: ", num_values);
+  }
+  if (comp == nullptr) {
+    return Status::Invalid("PFOR compressed data pointer is null");
+  }
+  // Every bound below is expressed against `comp_size`, and it also becomes the
+  // size of a std::span, where a negative value would convert to a huge size_t
+  // and read past the end of the buffer.
+  if (comp_size < PforConstants::kHeaderSize) {
+    return Status::Invalid("PFOR compressed buffer too small for header: ", comp_size,
+                           " < ", PforConstants::kHeaderSize);
+  }
+
+  const uint8_t* src = comp;
+
+  // Step 1: Read header
+  ARROW_ASSIGN_OR_RAISE(PforHeader header,
+                        LoadHeader(std::span<const uint8_t>(src, comp_size)));
+
+  // The loop below sizes its work from the header's count while `values` is only
+  // as large as `num_values`, so a header claiming more would write past the end
+  // of the output and one claiming fewer would fill part of it and still return
+  // OK, leaving the rest whatever it held before. Require the two to agree.
+  if (header.num_elements != num_values) {
+    return Status::Invalid("PFOR header element count ", header.num_elements,
+                           " does not match the expected value count ", num_values);
+  }
+
+  const int32_t vector_size = 1 << header.log_vector_size;
+  const int32_t num_vectors =
+      static_cast<int32_t>(bit_util::CeilDiv(header.num_elements, vector_size));
+
+  // Step 2: Read and check the offset array
+  const uint8_t* offset_array_start = src + PforConstants::kHeaderSize;
+  const int64_t offset_array_size = num_vectors * kOffsetSize;
+  if (PforConstants::kHeaderSize + offset_array_size > comp_size) {
+    return Status::Invalid("PFOR offset array for ", num_vectors,
+                           " vectors does not fit in ", comp_size, " bytes");
+  }
+  const int64_t payload_size = comp_size - PforConstants::kHeaderSize;
+  ARROW_RETURN_NOT_OK(
+      ValidateOffsets(offset_array_start, num_vectors, offset_array_size, payload_size));
+
+  // Step 3: Decode each vector
+  for (int32_t v = 0; v < num_vectors; ++v) {
+    const auto offset =
+        bit_util::FromLittleEndian(util::SafeLoadAs<PforConstants::OffsetType>(
+            offset_array_start + v * kOffsetSize));
+    const uint8_t* vector_data = offset_array_start + offset;
+
+    int32_t start_idx = v * vector_size;
+    int32_t elements_in_vector = std::min(vector_size, header.num_elements - start_idx);
+
+    ARROW_RETURN_NOT_OK(PforCompression<T>::DecodeVector(
+        std::span<const uint8_t>(vector_data, src + comp_size - vector_data),
+        elements_in_vector, values + start_idx));
+  }
+
+  return Status::OK();
+}
+
+// ----------------------------------------------------------------------
+// DecodeElementCount
+
+template <typename T>
+Result<int32_t> PforWrapper<T>::DecodeElementCount(const uint8_t* comp,
+                                                   int64_t comp_size) {
+  if (comp == nullptr) {
+    return Status::Invalid("PFOR compressed data pointer is null");
+  }
+  if (comp_size < 0) {
+    return Status::Invalid("PFOR compressed size must be non-negative: ", comp_size);
+  }
+  ARROW_ASSIGN_OR_RAISE(const PforHeader header,
+                        LoadHeader(std::span<const uint8_t>(comp, comp_size)));
+  return header.num_elements;
+}
+
+// ----------------------------------------------------------------------
+// VectorReader
+
+template <typename T>
+Result<typename PforWrapper<T>::VectorReader> PforWrapper<T>::VectorReader::Open(
+    std::span<const uint8_t> input) {
+  ARROW_ASSIGN_OR_RAISE(const PforHeader header, PforWrapper<T>::LoadHeader(input));
+
+  VectorReader reader;
+  reader.input_ = input;
+  reader.num_elements_ = header.num_elements;
+  reader.vector_size_ = 1 << header.log_vector_size;
+  reader.num_vectors_ =
+      static_cast<int32_t>(bit_util::CeilDiv(reader.num_elements_, reader.vector_size_));
+  reader.offset_array_start_ = input.data() + PforConstants::kHeaderSize;
+  const int64_t offset_array_size =
+      static_cast<int64_t>(reader.num_vectors_) * kOffsetSize;
+  if (PforConstants::kHeaderSize + offset_array_size >
+      static_cast<int64_t>(input.size())) {
+    return Status::Invalid("PFOR offset array for ", reader.num_vectors_,
+                           " vectors does not fit in ", input.size(), " bytes");
+  }
+  reader.payload_size_ = static_cast<int64_t>(input.size()) - PforConstants::kHeaderSize;
+  RETURN_NOT_OK(ValidateOffsets(reader.offset_array_start_, reader.num_vectors_,
+                                offset_array_size, reader.payload_size_));
+  return reader;
+}
+
+template <typename T>
+Result<int32_t> PforWrapper<T>::VectorReader::VectorLength(int32_t vector_index) const {
+  if (vector_index < 0 || vector_index >= num_vectors_) {
+    return Status::Invalid("PFOR vector index ", vector_index, " is outside [0, ",
+                           num_vectors_, ")");
+  }
+  return std::min(vector_size_, num_elements_ - vector_index * vector_size_);
+}
+
+template <typename T>
+Status PforWrapper<T>::VectorReader::DecodeVector(int32_t vector_index,
+                                                  std::span<T> output) const {
+  ARROW_ASSIGN_OR_RAISE(const int32_t vector_length, VectorLength(vector_index));
+  if (output.size() < static_cast<size_t>(vector_length)) {
+    return Status::Invalid("PFOR vector output has ", output.size(), " slots but needs ",
+                           vector_length);
+  }
+  const auto offset =
+      bit_util::FromLittleEndian(util::SafeLoadAs<PforConstants::OffsetType>(
+          offset_array_start_ + vector_index * kOffsetSize));
+  const uint8_t* vector_data = offset_array_start_ + offset;
+  return PforCompression<T>::DecodeVector(
+             std::span<const uint8_t>(vector_data,
+                                      input_.data() + input_.size() - vector_data),
+             vector_length, output.data())
+      .status();
+}
+
+// ----------------------------------------------------------------------
+// GetMaxCompressedSize
+
+template <typename T>
+Result<int64_t> PforWrapper<T>::GetMaxCompressedSize(int32_t num_values,
+                                                     int32_t vector_size) {
+  if (num_values < 0) {
+    return Status::Invalid("PFOR num_values must be non-negative: ", num_values);
+  }
+  RETURN_NOT_OK(ValidateVectorSize(vector_size));
+
+  const int64_t num_vectors = bit_util::CeilDiv(num_values, vector_size);
+
+  // A vector never serializes to more than its values occupy unpacked.
+  // FindOptimalBitWidth minimises `num_elements * bit_width + num_exceptions *
+  // (16 + 8 * sizeof(T))` bits, and the full-width candidate scores
+  // `num_elements * 8 * sizeof(T)` bits with no exceptions at all, so whatever
+  // width it does pick costs no more than that. Bit packing rounds the packed
+  // section up to a whole byte, hence the trailing byte.
+  const int64_t max_vector_size =
+      PforVectorInfo<T>::kStoredSize + vector_size * static_cast<int64_t>(sizeof(T)) + 1;
+
+  return PforConstants::kHeaderSize + num_vectors * (kOffsetSize + max_vector_size);
+}
+
+// Explicit template instantiations
+template class PforWrapper<int32_t>;
+template class PforWrapper<int64_t>;
+
+}  // namespace pfor
+}  // namespace util
+}  // namespace arrow
diff --git a/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h b/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h
new file mode 100644
index 000000000000..b438df1c7f35
--- /dev/null
+++ b/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h
@@ -0,0 +1,156 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// High-level wrapper interface for PFOR compression
+//
+// Handles page-level serialization: header, offset array, and vectors.
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <span>
+
+#include "arrow/result.h"
+#include "arrow/status.h"
+#include "arrow/util/pfor/pfor_internal.h"
+
+namespace arrow {
+namespace util {
+namespace pfor {
+
+/// \class PforWrapper
+/// \brief High-level interface for PFOR page-level compression
+///
+/// Manages this page layout (offsets are relative to the offset array):
+///
+///   +---------------------------------------------------------------+
+///   | PFOR header (7 bytes)                                         |
+///   | Offset 0 | Offset 1 | ... | Offset n-1      (4 bytes each)    |
+///   | Vector 0 | Vector 1 | ... | Vector n-1                         |
+///   +---------------------------------------------------------------+
+///
+/// Header fields:
+///
+///   +--------+--------------------+---------------------+
+///   | Offset | Field              | Size                |
+///   +--------+--------------------+---------------------+
+///   |      0 | packing_mode       | 1 byte (uint8)      |
+///   |      1 | log_vector_size    | 1 byte (uint8)      |
+///   |      2 | value_byte_width   | 1 byte (uint8)      |
+///   |      3 | num_elements       | 4 bytes (int32)     |
+///   +--------+--------------------+---------------------+
+///
+/// \tparam T the integer type (int32_t or int64_t)
+template <typename T>
+class PforWrapper {
+ public:
+  /// A validated view of one encoded page.  It keeps no decoded values and can
+  /// therefore serve arbitrary vectors without materializing the whole page.
+  class VectorReader {
+   public:
+    static Result<VectorReader> Open(std::span<const uint8_t> input);
+
+    int32_t num_elements() const { return num_elements_; }
+    int32_t vector_size() const { return vector_size_; }
+    int32_t num_vectors() const { return num_vectors_; }
+
+    Result<int32_t> VectorLength(int32_t vector_index) const;
+    Status DecodeVector(int32_t vector_index, std::span<T> output) const;
+
+   private:
+    std::span<const uint8_t> input_;
+    const uint8_t* offset_array_start_ = nullptr;
+    int64_t payload_size_ = 0;
+    int32_t num_elements_ = 0;
+    int32_t vector_size_ = 0;
+    int32_t num_vectors_ = 0;
+  };
+
+  /// \brief Encode integer values into a PFOR-compressed page
+  ///
+  /// \param[in] values pointer to input integers
+  /// \param[in] num_values total number of values; zero writes a bare header,
+  ///            which is what an all-null page encodes to
+  /// \param[in] vector_size number of elements per vector (must be a power of 2,
+  ///            in [2^kMinLogVectorSize, 2^kMaxLogVectorSize])
+  /// \param[out] comp pointer to output buffer, at least
+  ///             GetMaxCompressedSize(num_values, vector_size) bytes
+  /// \param[in,out] comp_size input: available buffer size, which must be at
+  ///                least GetMaxCompressedSize(num_values, vector_size);
+  ///                output: bytes written
+  /// \return Status::OK on success, or an error if the arguments are invalid
+  static Status Encode(const T* values, int32_t num_values, int32_t vector_size,
+                       uint8_t* comp, int64_t* comp_size);
+
+  /// Convenience overload with default vector_size = kPforVectorSize
+  static Status Encode(const T* values, int32_t num_values, uint8_t* comp,
+                       int64_t* comp_size);
+
+  /// \brief Decode a PFOR-compressed page
+  ///
+  /// \param[in] comp pointer to compressed data
+  /// \param[in] comp_size size of compressed data
+  /// \param[in] num_values number of values the page holds, which must equal the
+  ///            count in its header; DecodeElementCount reads that count. Zero is
+  ///            valid: an all-null page is a bare header.
+  /// \param[out] values pointer to output buffer, sized for num_values
+  /// \return Status::OK on success, or an error if the data is malformed
+  static Status Decode(const uint8_t* comp, int64_t comp_size, int32_t num_values,
+                       T* values);
+
+  /// \brief Read the value count a page declares in its own header
+  ///
+  /// The parquet page header counts nulls, which a PFOR page does not store, so
+  /// a caller holding a page needs this to learn how many values are in it.
+  ///
+  /// \param[in] comp pointer to compressed data
+  /// \param[in] comp_size size of compressed data
+  /// \return the number of values the page holds, or an error if the header is
+  ///         malformed
+  static Result<int32_t> DecodeElementCount(const uint8_t* comp, int64_t comp_size);
+
+  /// \brief Get the maximum compressed size for a given number of values
+  ///
+  /// \param[in] num_values number of integer values
+  /// \param[in] vector_size number of elements per vector (must be a power of 2,
+  ///            in [2^kMinLogVectorSize, 2^kMaxLogVectorSize])
+  /// \return maximum possible compressed page size in bytes, or an error if the
+  ///         arguments are invalid
+  static Result<int64_t> GetMaxCompressedSize(
+      int32_t num_values,
+      int32_t vector_size = static_cast<int32_t>(PforConstants::kPforVectorSize));
+
+ private:
+  /// \brief Page header structure (7 bytes)
+  struct PforHeader {
+    uint8_t packing_mode;      // 0 = FOR + bit-packing
+    uint8_t log_vector_size;   // log2(vector_size)
+    uint8_t value_byte_width;  // sizeof(T): 4 or 8
+    int32_t num_elements;      // total element count
+  };
+
+  static constexpr int32_t kVectorSize =
+      static_cast<int32_t>(PforConstants::kPforVectorSize);
+
+  static void StoreHeader(std::span<uint8_t> dest, const PforHeader& header);
+  static Result<PforHeader> LoadHeader(std::span<const uint8_t> src);
+};
+
+}  // namespace pfor
+}  // namespace util
+}  // namespace arrow

From eca116c80efa067533e08ccf22bf2278ee82b0e8 Mon Sep 17 00:00:00 2001
From: Prateek Gaur <prateek.gaur@snowflake.com>
Date: Sat, 3 Oct 2026 03:11:56 +0000
Subject: [PATCH 3/6] Integrate PFOR with Parquet integer columns

Register PFOR for INT32 and INT64, connect its encoder and decoder to the Parquet factories, and support dense, nullable, and vector-at-a-time page reads. Add the codec sources and integration targets to both build systems.
---
 cpp/src/parquet/CMakeLists.txt   |   2 +
 cpp/src/parquet/column_reader.cc |   3 +-
 cpp/src/parquet/decoder.cc       | 193 ++++++++++++++++++++++++++++++-
 cpp/src/parquet/encoder.cc       | 110 ++++++++++++++++++
 cpp/src/parquet/meson.build      |   1 +
 cpp/src/parquet/types.cc         |   2 +
 cpp/src/parquet/types.h          |   3 +-
 7 files changed, 310 insertions(+), 4 deletions(-)

diff --git a/cpp/src/parquet/CMakeLists.txt b/cpp/src/parquet/CMakeLists.txt
index f8a42b5b96bf..b97df02726cb 100644
--- a/cpp/src/parquet/CMakeLists.txt
+++ b/cpp/src/parquet/CMakeLists.txt
@@ -407,6 +407,7 @@ add_parquet_test(chunker-test SOURCES chunker_internal_test.cc)
 
 add_parquet_test(arrow-reader-writer-test
                  SOURCES
+                 arrow/arrow_encoding_test.cc
                  arrow/arrow_reader_writer_test.cc
                  arrow/arrow_statistics_test.cc
                  arrow/variant_test.cc)
@@ -452,5 +453,6 @@ add_parquet_benchmark(level_conversion_benchmark)
 add_parquet_benchmark(metadata_benchmark)
 add_parquet_benchmark(page_index_benchmark SOURCES page_index_benchmark.cc
                       benchmark_util.cc)
+add_parquet_benchmark(pfor_comparison_benchmark)
 add_parquet_benchmark(arrow/reader_writer_benchmark PREFIX "parquet-arrow")
 add_parquet_benchmark(arrow/size_stats_benchmark PREFIX "parquet-arrow")
diff --git a/cpp/src/parquet/column_reader.cc b/cpp/src/parquet/column_reader.cc
index 162a72bd1576..b2d5c18630c8 100644
--- a/cpp/src/parquet/column_reader.cc
+++ b/cpp/src/parquet/column_reader.cc
@@ -971,7 +971,8 @@ class ColumnReaderImplBase {
         case Encoding::RLE:
         case Encoding::DELTA_BINARY_PACKED:
         case Encoding::DELTA_BYTE_ARRAY:
-        case Encoding::DELTA_LENGTH_BYTE_ARRAY: {
+        case Encoding::DELTA_LENGTH_BYTE_ARRAY:
+        case Encoding::PFOR: {
           auto decoder = MakeTypedDecoder<DType>(encoding, descr_, pool_);
           current_decoder_.SetDecoder(decoder.get());
           decoders_[static_cast<int>(encoding)] = std::move(decoder);
diff --git a/cpp/src/parquet/decoder.cc b/cpp/src/parquet/decoder.cc
index c4d3fe5a8a5a..1a4e8c93af49 100644
--- a/cpp/src/parquet/decoder.cc
+++ b/cpp/src/parquet/decoder.cc
@@ -24,6 +24,8 @@
 #include <cstring>
 #include <limits>
 #include <memory>
+#include <optional>
+#include <span>
 #include <string>
 #include <string_view>
 #include <type_traits>
@@ -44,6 +46,7 @@
 #include "arrow/util/checked_cast.h"
 #include "arrow/util/int_util_overflow.h"
 #include "arrow/util/logging_internal.h"
+#include "arrow/util/pfor/pfor_wrapper_internal.h"
 #include "arrow/util/rle_encoding_internal.h"
 #include "arrow/util/spaced_internal.h"
 #include "arrow/util/ubsan.h"
@@ -2372,6 +2375,183 @@ class ByteStreamSplitDecoder<FLBAType> : public ByteStreamSplitDecoderBase<FLBAT
   }
 };
 
+// ----------------------------------------------------------------------
+// PFOR Decoder
+
+template <typename DType>
+class PforDecoder : public TypedDecoderImpl<DType> {
+ public:
+  using Base = TypedDecoderImpl<DType>;
+  using T = typename DType::c_type;
+  using VectorReader = typename ::arrow::util::pfor::PforWrapper<T>::VectorReader;
+
+  explicit PforDecoder(const ColumnDescriptor* descr,
+                       MemoryPool* pool = ::arrow::default_memory_pool())
+      : Base(descr, Encoding::PFOR), cached_vector_(AllocateBuffer(pool, 0)) {}
+
+  void SetData(int num_values, const uint8_t* data, int len) override {
+    if (num_values < 0 || len < 0) {
+      throw ParquetException("PFOR SetData: num_values=" + std::to_string(num_values) +
+                             " len=" + std::to_string(len));
+    }
+    Base::SetData(num_values, data, len);
+    if (num_values > 0 && len == 0) {
+      throw ParquetException("PFOR SetData: num_values=" + std::to_string(num_values) +
+                             " but len=" + std::to_string(len));
+    }
+    // A decoder is cached per encoding and reused across the data pages of a
+    // column chunk, so every piece of state describing the previous page has to
+    // be dropped along with the page itself.
+    cached_vector_index_ = -1;
+    // `num_values` is the page's level count, which includes nulls, while a PFOR
+    // page stores only the non-null values. Its own header is the authority on
+    // how many, so take the count from there.
+    if (len > 0) {
+      PARQUET_ASSIGN_OR_THROW(
+          reader_, VectorReader::Open({this->data_, static_cast<size_t>(this->len_)}));
+      const int32_t encoded_values = reader_->num_elements();
+      if (encoded_values > num_values) {
+        throw ParquetException("PFOR page declares " + std::to_string(encoded_values) +
+                               " values but the page header allows at most " +
+                               std::to_string(num_values));
+      }
+      this->num_values_ = encoded_values;
+    } else {
+      reader_.reset();
+      this->num_values_ = 0;
+    }
+    levels_remaining_ = num_values;
+  }
+
+  int Decode(T* buffer, int max_values) override {
+    if (ARROW_PREDICT_FALSE(max_values < 0)) {
+      throw ParquetException("PFOR Decode: max_values must be non-negative");
+    }
+    max_values = std::min(max_values, this->num_values_);
+    if (max_values == 0) return 0;
+    DecodeInternal(buffer, max_values);
+    this->num_values_ -= max_values;
+    levels_remaining_ -= max_values;
+    CheckPageConsumed();
+    return max_values;
+  }
+
+  int DecodeSpaced(T* buffer, int num_values, int null_count, const uint8_t* valid_bits,
+                   int64_t valid_bits_offset) override {
+    const int decoded =
+        Base::DecodeSpaced(buffer, num_values, null_count, valid_bits, valid_bits_offset);
+    levels_remaining_ -= null_count;
+    CheckPageConsumed();
+    return decoded;
+  }
+
+  // `num_values` counts output slots; only the non-null ones are backed by
+  // encoded values, so decode that many and spread them over the valid runs.
+  int DecodeArrow(int num_values, int null_count, const uint8_t* valid_bits,
+                  int64_t valid_bits_offset,
+                  typename EncodingTraits<DType>::Accumulator* builder) override {
+    const int values_to_decode = num_values - null_count;
+    if (ARROW_PREDICT_FALSE(this->num_values_ < values_to_decode)) {
+      ParquetException::EofException(
+          "PFOR DecodeArrow: not enough values available. "
+          "Available: " +
+          std::to_string(this->num_values_) +
+          ", requested: " + std::to_string(values_to_decode));
+    }
+
+    PARQUET_THROW_NOT_OK(builder->Reserve(num_values));
+
+    // 1. Land the values in the builder's storage packed to the right, so step 2
+    //    can expand them in place into their final positions. An all-null run
+    //    asks for no values, and a page carrying none has nothing to decode.
+    if (values_to_decode > 0) {
+      T* decode_out = builder->GetMutableValue(builder->length() + null_count);
+      DecodeInternal(decode_out, values_to_decode);
+    }
+
+    // 2. Expand the values into their final positions.
+    if (null_count == 0) {
+      builder->UnsafeAdvance(num_values);
+    } else {
+      ::arrow::util::internal::SpacedExpandLeftward(
+          reinterpret_cast<uint8_t*>(builder->GetMutableValue(builder->length())),
+          static_cast<int>(sizeof(T)), num_values, null_count, valid_bits,
+          valid_bits_offset);
+      builder->UnsafeAdvance(num_values, valid_bits, valid_bits_offset);
+    }
+    this->num_values_ -= values_to_decode;
+    levels_remaining_ -= num_values;
+    CheckPageConsumed();
+    return values_to_decode;
+  }
+
+  int DecodeArrow(int num_values, int null_count, const uint8_t* valid_bits,
+                  int64_t valid_bits_offset,
+                  typename EncodingTraits<DType>::DictAccumulator* out) override {
+    const int values_decoded = num_values - null_count;
+    std::vector<T> values(values_decoded);
+    if (Decode(values.data(), values_decoded) != values_decoded) {
+      ParquetException::EofException();
+    }
+    levels_remaining_ -= null_count;
+    CheckPageConsumed();
+
+    const T* data = values.data();
+    PARQUET_THROW_NOT_OK(out->Reserve(num_values));
+    VisitNullBitmapInline(
+        valid_bits, valid_bits_offset, num_values, null_count,
+        [&]() { PARQUET_THROW_NOT_OK(out->Append(*data++)); },
+        [&]() { PARQUET_THROW_NOT_OK(out->AppendNull()); });
+    return values_decoded;
+  }
+
+ private:
+  void CheckPageConsumed() const {
+    ARROW_DCHECK_GE(levels_remaining_, 0) << "PFOR decoder consumed too many levels";
+    if (ARROW_PREDICT_FALSE(levels_remaining_ <= 0 && this->num_values_ > 0)) {
+      throw ParquetException("PFOR page has " + std::to_string(this->num_values_) +
+                             " unconsumed values after all levels were read");
+    }
+  }
+
+  void DecodeInternal(T* output, int count) {
+    const int32_t vector_size = reader_->vector_size();
+    int32_t processed = reader_->num_elements() - this->num_values_;
+    for (int32_t remaining = count; remaining > 0;) {
+      const int32_t vector_index = processed / vector_size;
+      const int32_t position = processed % vector_size;
+      PARQUET_ASSIGN_OR_THROW(const int32_t vector_length,
+                              reader_->VectorLength(vector_index));
+      const int32_t take = std::min(remaining, vector_length - position);
+      if (position == 0 && take == vector_length) {
+        PARQUET_THROW_NOT_OK(reader_->DecodeVector(
+            vector_index, {output, static_cast<size_t>(vector_length)}));
+      } else {
+        if (cached_vector_index_ != vector_index) {
+          PARQUET_THROW_NOT_OK(
+              cached_vector_->Resize(static_cast<int64_t>(vector_length) * sizeof(T),
+                                     /*shrink_to_fit=*/false));
+          PARQUET_THROW_NOT_OK(
+              reader_->DecodeVector(vector_index, {cached_vector_->mutable_data_as<T>(),
+                                                   static_cast<size_t>(vector_length)}));
+          cached_vector_index_ = vector_index;
+        }
+        std::memcpy(output, cached_vector_->data_as<T>() + position,
+                    static_cast<size_t>(take) * sizeof(T));
+      }
+      output += take;
+      processed += take;
+      remaining -= take;
+    }
+  }
+
+  std::optional<VectorReader> reader_;
+  // One vector of pool-backed scratch, reused when a batch begins or ends inside it.
+  std::shared_ptr<ResizableBuffer> cached_vector_;
+  int32_t cached_vector_index_ = -1;
+  int64_t levels_remaining_ = 0;
+};
+
 }  // namespace
 
 // ----------------------------------------------------------------------
@@ -2448,6 +2628,15 @@ std::unique_ptr<Decoder> MakeDecoder(Type::type type_num, Encoding::type encodin
       return std::make_unique<RleBooleanDecoder>(descr);
     }
     throw ParquetException("RLE encoding only supports BOOLEAN");
+  } else if (encoding == Encoding::PFOR) {
+    switch (type_num) {
+      case Type::INT32:
+        return std::make_unique<PforDecoder<Int32Type>>(descr, pool);
+      case Type::INT64:
+        return std::make_unique<PforDecoder<Int64Type>>(descr, pool);
+      default:
+        throw ParquetException("PFOR decoder only supports INT32 and INT64");
+    }
   } else {
     ParquetException::NYI("Selected encoding is not supported");
   }
@@ -2491,8 +2680,8 @@ std::vector<Encoding::type> SupportedEncodings(Type::type physical_type) {
       return {Encoding::PLAIN, Encoding::RLE};
     case Type::INT32:
     case Type::INT64:
-      return {Encoding::PLAIN, Encoding::DELTA_BINARY_PACKED,
-              Encoding::BYTE_STREAM_SPLIT};
+      return {Encoding::PLAIN, Encoding::DELTA_BINARY_PACKED, Encoding::BYTE_STREAM_SPLIT,
+              Encoding::PFOR};
     case Type::INT96:
       return {Encoding::PLAIN};
     case Type::FLOAT:
diff --git a/cpp/src/parquet/encoder.cc b/cpp/src/parquet/encoder.cc
index 3e469df277b8..ce675a2dfb4c 100644
--- a/cpp/src/parquet/encoder.cc
+++ b/cpp/src/parquet/encoder.cc
@@ -40,6 +40,7 @@
 #include "arrow/util/hashing.h"
 #include "arrow/util/int_util_overflow.h"
 #include "arrow/util/logging_internal.h"
+#include "arrow/util/pfor/pfor_wrapper_internal.h"
 #include "arrow/util/rle_encoding_internal.h"
 #include "arrow/util/spaced_internal.h"
 #include "arrow/util/ubsan.h"
@@ -1763,6 +1764,106 @@ std::shared_ptr<Buffer> RleBooleanEncoder::FlushValues() {
 
 }  // namespace
 
+// ----------------------------------------------------------------------
+// PFOR Encoder
+
+// TODO: support incremental encoding. Today `Put` only appends raw input
+// to `values_`, and `FlushValues` runs the entire PFOR pipeline on the
+// whole buffer in one shot. A future revision should encode complete
+// vectors as `Put` calls fill them, holding only a partial-vector tail
+// across calls, so the encoder can produce output progressively and use
+// bounded memory. This is deferred to a follow-up change; the decoder
+// carries the matching TODO.
+//
+// TODO: fall back to PLAIN when PFOR is not paying for itself. This encoder
+// always emits a PFOR page, and the cost model's worst case is the full width
+// with no exceptions, so a column whose deltas never narrow (random values, or
+// a low null sentinel that becomes the frame of reference and can never be an
+// exception) encodes to its plain size plus the page header, the offset array
+// and one PforVectorInfo per vector.
+//
+// The decision belongs in ColumnWriterImpl, not here: `encoding_` is const, so
+// this encoder cannot relabel its own page, and the choice depends on the page
+// compressor, which this layer knows nothing about. The mechanism already
+// exists -- mirror `FallbackToPlainEncoding()` in column_writer.cc, which swaps
+// `current_encoder_` for a PLAIN encoder and updates `encoding_`. Parquet
+// records the encoding per page, so mixing PLAIN and PFOR pages in one column
+// chunk needs no format change.
+//
+// What is missing on this side is a way for the writer to know the ratio
+// before paying for the encode. FindOptimalBitWidth already computes the cost
+// of a vector in bits, so a sampled estimate over the first few vectors would
+// answer the question without encoding the page twice.
+template <typename DType>
+class PforEncoder : public EncoderImpl, virtual public TypedEncoder<DType> {
+ public:
+  using T = typename DType::c_type;
+  using TypedEncoder<DType>::Put;
+
+  explicit PforEncoder(const ColumnDescriptor* descr, MemoryPool* pool)
+      : EncoderImpl(descr, Encoding::PFOR, pool), pool_(pool) {}
+
+  std::shared_ptr<Buffer> FlushValues() override {
+    // An all-null optional page adds no values and is still written, so an empty
+    // buffer has to encode to a header-only page rather than to zero bytes, which
+    // the reader would reject for having no header to load.
+    const int32_t num_values = static_cast<int32_t>(values_.size());
+    PARQUET_ASSIGN_OR_THROW(
+        int64_t max_size,
+        ::arrow::util::pfor::PforWrapper<T>::GetMaxCompressedSize(num_values));
+    PARQUET_ASSIGN_OR_THROW(auto buffer,
+                            ::arrow::AllocateResizableBuffer(max_size, pool_));
+
+    int64_t comp_size = max_size;
+    PARQUET_THROW_NOT_OK(::arrow::util::pfor::PforWrapper<T>::Encode(
+        values_.data(), num_values, buffer->mutable_data(), &comp_size));
+
+    PARQUET_THROW_NOT_OK(buffer->Resize(comp_size));
+    values_.clear();
+    return buffer;
+  }
+
+  int64_t EstimatedDataEncodedSize() override {
+    return static_cast<int64_t>(values_.size() * sizeof(T));
+  }
+
+  void Put(const ::arrow::Array& values) override {
+    const auto& data = *values.data();
+    if (data.length > std::numeric_limits<int32_t>::max()) {
+      throw ParquetException("Array cannot be longer than ",
+                             std::numeric_limits<int32_t>::max());
+    }
+    if (values.null_count() == 0) {
+      Put(data.template GetValues<T>(1), static_cast<int>(data.length));
+    } else {
+      PutSpaced(data.template GetValues<T>(1), static_cast<int>(data.length),
+                data.GetValues<uint8_t>(0, 0), data.offset);
+    }
+  }
+
+  void Put(const T* buffer, int num_values) override {
+    values_.insert(values_.end(), buffer, buffer + num_values);
+  }
+
+  void PutSpaced(const T* src, int num_values, const uint8_t* valid_bits,
+                 int64_t valid_bits_offset) override {
+    if (valid_bits != NULLPTR) {
+      PARQUET_ASSIGN_OR_THROW(auto buffer,
+                              ::arrow::AllocateBuffer(num_values * sizeof(T), pool_));
+      T* dest = reinterpret_cast<T*>(buffer->mutable_data());
+      int num_valid = ::arrow::util::internal::SpacedCompress<T>(
+          src, num_values, valid_bits, valid_bits_offset, dest);
+      Put(dest, num_valid);
+    } else {
+      Put(src, num_values);
+    }
+  }
+
+ private:
+  MemoryPool* pool_;
+  std::vector<T> values_;
+};
+
 // ----------------------------------------------------------------------
 // Factory function
 
@@ -1862,6 +1963,15 @@ std::unique_ptr<Encoder> MakeEncoder(Type::type type_num, Encoding::type encodin
         throw ParquetException(
             "DELTA_BYTE_ARRAY only supports BYTE_ARRAY and FIXED_LEN_BYTE_ARRAY");
     }
+  } else if (encoding == Encoding::PFOR) {
+    switch (type_num) {
+      case Type::INT32:
+        return std::make_unique<PforEncoder<Int32Type>>(descr, pool);
+      case Type::INT64:
+        return std::make_unique<PforEncoder<Int64Type>>(descr, pool);
+      default:
+        throw ParquetException("PFOR encoder only supports INT32 and INT64");
+    }
   } else {
     ParquetException::NYI("Selected encoding is not supported");
   }
diff --git a/cpp/src/parquet/meson.build b/cpp/src/parquet/meson.build
index 9069ccb5fd1a..1200427fe2f7 100644
--- a/cpp/src/parquet/meson.build
+++ b/cpp/src/parquet/meson.build
@@ -226,6 +226,7 @@ parquet_tests = {
     'chunker-test': {'sources': files('chunker_internal_test.cc')},
     'arrow-reader-writer-test': {
         'sources': files(
+            'arrow/arrow_encoding_test.cc',
             'arrow/arrow_reader_writer_test.cc',
             'arrow/arrow_statistics_test.cc',
             'arrow/variant_test.cc',
diff --git a/cpp/src/parquet/types.cc b/cpp/src/parquet/types.cc
index 9d7604faec30..1567d2b559e2 100644
--- a/cpp/src/parquet/types.cc
+++ b/cpp/src/parquet/types.cc
@@ -270,6 +270,8 @@ std::string EncodingToString(Encoding::type t) {
       return "RLE_DICTIONARY";
     case Encoding::BYTE_STREAM_SPLIT:
       return "BYTE_STREAM_SPLIT";
+    case Encoding::PFOR:
+      return "PFOR";
     default:
       return "UNKNOWN";
   }
diff --git a/cpp/src/parquet/types.h b/cpp/src/parquet/types.h
index 687353aa9bcb..acfedb45d795 100644
--- a/cpp/src/parquet/types.h
+++ b/cpp/src/parquet/types.h
@@ -539,8 +539,9 @@ struct Encoding {
     DELTA_BYTE_ARRAY = 7,
     RLE_DICTIONARY = 8,
     BYTE_STREAM_SPLIT = 9,
+    PFOR = 11,
     // Should always be last element (except UNKNOWN)
-    UNDEFINED = 10,
+    UNDEFINED = 12,
     UNKNOWN = 999
   };
 };

From 4c2dd6fec5b2eccccf7e86d42a92052a5437febb Mon Sep 17 00:00:00 2001
From: Prateek Gaur <prateek.gaur@snowflake.com>
Date: Sat, 3 Oct 2026 03:12:04 +0000
Subject: [PATCH 4/6] Test and benchmark Parquet PFOR integration

Add end-to-end file round trips, null handling, batched reads, malformed-input cases, and encoding-factory coverage. Compare PFOR with existing integer encodings over modeled analytical column distributions.
---
 .gitignore                                   |    3 +
 cpp/src/parquet/arrow/arrow_encoding_test.cc |  392 +++++++
 cpp/src/parquet/column_writer_test.cc        |   52 +
 cpp/src/parquet/encoding_test.cc             |  238 +++++
 cpp/src/parquet/pfor_comparison_benchmark.cc | 1003 ++++++++++++++++++
 5 files changed, 1688 insertions(+)
 create mode 100644 cpp/src/parquet/arrow/arrow_encoding_test.cc
 create mode 100644 cpp/src/parquet/pfor_comparison_benchmark.cc

diff --git a/.gitignore b/.gitignore
index 83458ab2057b..dc53bf2c0d82 100644
--- a/.gitignore
+++ b/.gitignore
@@ -94,3 +94,6 @@ rat.txt
 
 # for ODBC DLL
 *.rc
+
+# Local out-of-tree benchmark build dir
+cpp/build-bench/
diff --git a/cpp/src/parquet/arrow/arrow_encoding_test.cc b/cpp/src/parquet/arrow/arrow_encoding_test.cc
new file mode 100644
index 000000000000..1adec93341ea
--- /dev/null
+++ b/cpp/src/parquet/arrow/arrow_encoding_test.cc
@@ -0,0 +1,392 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// End-to-end tests for the column encodings, driven through the Arrow reader
+// and writer rather than through the encoder classes directly.
+
+#include "gmock/gmock.h"
+#include "gtest/gtest.h"
+
+#include <cstdint>
+#include <limits>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "arrow/chunked_array.h"
+#include "arrow/io/memory.h"
+#include "arrow/table.h"
+#include "arrow/testing/builder.h"
+#include "arrow/testing/gtest_util.h"
+#include "arrow/testing/random.h"
+#include "arrow/type.h"
+#include "arrow/util/config.h"
+
+#include "parquet/arrow/reader.h"
+#include "parquet/arrow/writer.h"
+#include "parquet/file_reader.h"
+#include "parquet/metadata.h"
+#include "parquet/platform.h"
+#include "parquet/properties.h"
+#include "parquet/test_util.h"
+#include "parquet/types.h"
+
+using arrow::ChunkedArray;
+using arrow::Table;
+using arrow::io::BufferReader;
+
+namespace parquet {
+namespace arrow {
+namespace {
+
+// Write `table` with `writer_properties` and read it straight back, handing back
+// the file's bytes as well so a caller can check what the writer chose.
+void DoRoundtrip(const std::shared_ptr<Table>& table, int64_t row_group_size,
+                 std::shared_ptr<Table>* out,
+                 const std::shared_ptr<WriterProperties>& writer_properties,
+                 std::shared_ptr<Buffer>* out_file = nullptr) {
+  auto sink = CreateOutputStream();
+  ASSERT_OK_NO_THROW(WriteTable(*table, ::arrow::default_memory_pool(), sink,
+                                row_group_size, writer_properties));
+  ASSERT_OK_AND_ASSIGN(auto buffer, sink->Finish());
+  if (out_file != nullptr) {
+    *out_file = buffer;
+  }
+
+  std::unique_ptr<FileReader> reader;
+  FileReaderBuilder builder;
+  ASSERT_OK_NO_THROW(builder.Open(std::make_shared<BufferReader>(buffer)));
+  ASSERT_OK(builder.Build(&reader));
+  ASSERT_OK_AND_ASSIGN(*out, reader->ReadTable());
+}
+
+// Fail unless every column chunk of `file` was written with `encoding`. Without
+// this a round trip still passes when the writer quietly chose something else,
+// and the test would be checking the default encoding instead.
+void AssertAllColumnsUse(const std::shared_ptr<Buffer>& file, Encoding::type encoding) {
+  auto metadata =
+      ParquetFileReader::Open(std::make_shared<BufferReader>(file))->metadata();
+  ASSERT_GT(metadata->num_row_groups(), 0);
+  for (int rg = 0; rg < metadata->num_row_groups(); ++rg) {
+    auto row_group = metadata->RowGroup(rg);
+    for (int col = 0; col < row_group->num_columns(); ++col) {
+      EXPECT_THAT(row_group->ColumnChunk(col)->encodings(), ::testing::Contains(encoding))
+          << "row group " << rg << " column " << col << " does not use "
+          << EncodingToString(encoding);
+    }
+  }
+}
+
+// ----------------------------------------------------------------------
+// PFOR encoding file-level integration tests
+
+class ParquetPforEncodingTest : public ::testing::Test {
+ public:
+  void TestPforRoundTrip(const std::shared_ptr<Table>& table,
+                         int64_t row_group_size = -1) {
+    auto writer_props = WriterProperties::Builder()
+                            .disable_dictionary()
+                            ->encoding(Encoding::PFOR)
+                            ->build();
+
+    std::shared_ptr<Table> result;
+    std::shared_ptr<Buffer> file;
+    DoRoundtrip(table, row_group_size < 0 ? table->num_rows() : row_group_size, &result,
+                writer_props, &file);
+
+    ASSERT_NO_FATAL_FAILURE(AssertAllColumnsUse(file, Encoding::PFOR));
+    ASSERT_NO_FATAL_FAILURE(::arrow::AssertTablesEqual(*table, *result));
+  }
+
+  void TestPforWithCompression(const std::shared_ptr<Table>& table,
+                               Compression::type compression) {
+    auto writer_props = WriterProperties::Builder()
+                            .disable_dictionary()
+                            ->encoding(Encoding::PFOR)
+                            ->compression(compression)
+                            ->build();
+
+    std::shared_ptr<Table> result;
+    std::shared_ptr<Buffer> file;
+    DoRoundtrip(table, table->num_rows(), &result, writer_props, &file);
+
+    ASSERT_NO_FATAL_FAILURE(AssertAllColumnsUse(file, Encoding::PFOR));
+    ASSERT_NO_FATAL_FAILURE(::arrow::AssertTablesEqual(*table, *result));
+  }
+
+  // A table of one column named "values" holding `values`.
+  template <typename ArrowType, typename C>
+  static std::shared_ptr<Table> TableOf(const std::shared_ptr<::arrow::DataType>& type,
+                                        const C& values) {
+    std::shared_ptr<::arrow::Array> array;
+    ::arrow::ArrayFromVector<ArrowType>(values, &array);
+    return Table::Make(::arrow::schema({::arrow::field("values", type)}),
+                       {std::make_shared<ChunkedArray>(array)});
+  }
+};
+
+TEST_F(ParquetPforEncodingTest, SimpleInt32Table) {
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = ::arrow::TableFromJSON(
+      schema, {R"([[1], [2], [3], [4], [5], [6], [7], [8], [9], [10]])"});
+  TestPforRoundTrip(table);
+}
+
+TEST_F(ParquetPforEncodingTest, SimpleInt64Table) {
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int64())});
+  auto table = ::arrow::TableFromJSON(
+      schema, {R"([[-100], [0], [100], [200], [300], [400], [500], [600], [700]])"});
+  TestPforRoundTrip(table);
+}
+
+TEST_F(ParquetPforEncodingTest, MixedTypesWithInt32Int64) {
+  auto schema = ::arrow::schema({::arrow::field("id", ::arrow::int32()),
+                                 ::arrow::field("count", ::arrow::int64()),
+                                 ::arrow::field("ratio", ::arrow::float64()),
+                                 ::arrow::field("name", ::arrow::utf8())});
+  auto table = ::arrow::TableFromJSON(schema, {R"([[1, 1000, 1.5, "a"],
+                                          [2, 1001, 2.5, "b"],
+                                          [3, 1002, 3.5, "c"],
+                                          [4, 1003, 4.5, "d"],
+                                          [5, 1004, 5.5, "e"]])"});
+  // PFOR takes only the two integer columns; the rest keep their defaults.
+  auto writer_props = WriterProperties::Builder()
+                          .disable_dictionary()
+                          ->encoding("id", Encoding::PFOR)
+                          ->encoding("count", Encoding::PFOR)
+                          ->build();
+
+  std::shared_ptr<Table> result;
+  std::shared_ptr<Buffer> file;
+  DoRoundtrip(table, table->num_rows(), &result, writer_props, &file);
+
+  auto metadata =
+      ParquetFileReader::Open(std::make_shared<BufferReader>(file))->metadata();
+  ASSERT_THAT(metadata->RowGroup(0)->ColumnChunk(0)->encodings(),
+              ::testing::Contains(Encoding::PFOR));
+  ASSERT_THAT(metadata->RowGroup(0)->ColumnChunk(1)->encodings(),
+              ::testing::Contains(Encoding::PFOR));
+  ASSERT_NO_FATAL_FAILURE(::arrow::AssertTablesEqual(*table, *result));
+}
+
+TEST_F(ParquetPforEncodingTest, LargeInt32Dataset) {
+  ::arrow::random::RandomArrayGenerator rag(42);
+  auto array = rag.Int32(10000, -1000000, 1000000);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  TestPforRoundTrip(table);
+}
+
+TEST_F(ParquetPforEncodingTest, LargeInt64Dataset) {
+  ::arrow::random::RandomArrayGenerator rag(42);
+  auto array = rag.Int64(10000, -1000000000LL, 1000000000LL);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int64())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  TestPforRoundTrip(table);
+}
+
+// The distribution PFOR is built for: a tight cluster sitting a long way from
+// zero, so the frame of reference carries the magnitude and the bit-packed
+// payload carries only the spread.
+TEST_F(ParquetPforEncodingTest, ClusteredValuesFarFromZero) {
+  std::vector<int64_t> values(4000);
+  for (size_t i = 0; i < values.size(); ++i) {
+    values[i] = 1'000'000'000'000LL + static_cast<int64_t>(i % 37);
+  }
+  TestPforRoundTrip(TableOf<::arrow::Int64Type>(::arrow::int64(), values));
+}
+
+// One vector of a constant, which encodes at bit width 0 and so has an empty
+// bit-packed payload.
+TEST_F(ParquetPforEncodingTest, ConstantColumn) {
+  std::vector<int32_t> values(2048, -7);
+  TestPforRoundTrip(TableOf<::arrow::Int32Type>(::arrow::int32(), values));
+}
+
+// A cluster with a few values far above it, which is what the exception path
+// exists to hold.
+TEST_F(ParquetPforEncodingTest, ClusterWithOutliers) {
+  std::vector<int32_t> values(3000);
+  for (size_t i = 0; i < values.size(); ++i) {
+    values[i] = 500 + static_cast<int32_t>(i % 11);
+    if (i % 97 == 0) {
+      values[i] = 1'000'000 + static_cast<int32_t>(i);
+    }
+  }
+  TestPforRoundTrip(TableOf<::arrow::Int32Type>(::arrow::int32(), values));
+}
+
+// The extremes of each type in one vector, where the span between the smallest
+// and largest value does not fit in the type and the encoder has to fall back
+// to storing full-width values.
+TEST_F(ParquetPforEncodingTest, Int32AtTypeBounds) {
+  std::vector<int32_t> values = {std::numeric_limits<int32_t>::lowest(),
+                                 std::numeric_limits<int32_t>::max(),
+                                 0,
+                                 -1,
+                                 1,
+                                 std::numeric_limits<int32_t>::lowest() + 1,
+                                 std::numeric_limits<int32_t>::max() - 1};
+  TestPforRoundTrip(TableOf<::arrow::Int32Type>(::arrow::int32(), values));
+}
+
+TEST_F(ParquetPforEncodingTest, Int64AtTypeBounds) {
+  std::vector<int64_t> values = {std::numeric_limits<int64_t>::lowest(),
+                                 std::numeric_limits<int64_t>::max(),
+                                 0,
+                                 -1,
+                                 1,
+                                 std::numeric_limits<int64_t>::lowest() + 1,
+                                 std::numeric_limits<int64_t>::max() - 1};
+  TestPforRoundTrip(TableOf<::arrow::Int64Type>(::arrow::int64(), values));
+}
+
+TEST_F(ParquetPforEncodingTest, Int32WithNulls) {
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = ::arrow::TableFromJSON(
+      schema, {R"([[1], [null], [3], [null], [5], [6], [null], [8]])"});
+  TestPforRoundTrip(table);
+}
+
+// A PFOR page holds no nulls, so an all-null page carries no values at all and
+// has to survive the round trip as a header with an empty payload.
+TEST_F(ParquetPforEncodingTest, AllNullColumn) {
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int64())});
+  auto table = ::arrow::TableFromJSON(
+      schema, {R"([[null], [null], [null], [null], [null], [null]])"});
+  TestPforRoundTrip(table);
+}
+
+// Nulls ahead of the first value, which makes the level count and the value
+// count differ from the very first batch a reader sees.
+TEST_F(ParquetPforEncodingTest, LeadingNulls) {
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = ::arrow::TableFromJSON(
+      schema, {R"([[null], [null], [null], [7], [8], [9], [null], [11]])"});
+  TestPforRoundTrip(table);
+}
+
+TEST_F(ParquetPforEncodingTest, MultipleRowGroups) {
+  ::arrow::random::RandomArrayGenerator rag(123);
+  auto array = rag.Int64(5000, -100, 100);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int64())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  TestPforRoundTrip(table, /*row_group_size=*/1000);
+}
+
+// Row groups that do not divide the vector size, so most pages end on a partial
+// vector.
+TEST_F(ParquetPforEncodingTest, RowGroupsEndOnPartialVectors) {
+  ::arrow::random::RandomArrayGenerator rag(7);
+  auto array = rag.Int32(5000, -50000, 50000);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  TestPforRoundTrip(table, /*row_group_size=*/1500);
+}
+
+#ifdef ARROW_WITH_ZSTD
+TEST_F(ParquetPforEncodingTest, PforWithZstdCompression) {
+  ::arrow::random::RandomArrayGenerator rag(42);
+  auto array = rag.Int64(5000, -1000, 1000);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int64())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  TestPforWithCompression(table, Compression::ZSTD);
+}
+#endif
+
+#ifdef ARROW_WITH_SNAPPY
+TEST_F(ParquetPforEncodingTest, PforWithSnappyCompression) {
+  ::arrow::random::RandomArrayGenerator rag(42);
+  auto array = rag.Int32(5000, -1000, 1000);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  TestPforWithCompression(table, Compression::SNAPPY);
+}
+#endif
+
+TEST_F(ParquetPforEncodingTest, VerifyPforEncodingUsed) {
+  std::vector<int64_t> values(1000);
+  for (size_t i = 0; i < values.size(); ++i) {
+    values[i] = 5'000'000 + static_cast<int64_t>(i);
+  }
+  auto table = TableOf<::arrow::Int64Type>(::arrow::int64(), values);
+
+  auto writer_props =
+      WriterProperties::Builder().disable_dictionary()->encoding(Encoding::PFOR)->build();
+
+  auto sink = CreateOutputStream();
+  ASSERT_OK(WriteTable(*table, ::arrow::default_memory_pool(), sink, table->num_rows(),
+                       writer_props));
+  ASSERT_OK_AND_ASSIGN(auto buffer, sink->Finish());
+
+  auto reader = ParquetFileReader::Open(std::make_shared<BufferReader>(buffer));
+  auto metadata = reader->metadata();
+
+  ASSERT_EQ(metadata->num_row_groups(), 1);
+  auto row_group = metadata->RowGroup(0);
+  ASSERT_EQ(row_group->num_columns(), 1);
+
+  auto encodings = row_group->ColumnChunk(0)->encodings();
+  EXPECT_THAT(encodings, ::testing::Contains(Encoding::PFOR))
+      << "PFOR encoding not found in column encodings";
+}
+
+// A reader that asks for fewer values than the page holds is served the rest on
+// later calls, so batches smaller than a page must reassemble exactly.
+TEST_F(ParquetPforEncodingTest, ReadInSmallBatches) {
+  ::arrow::random::RandomArrayGenerator rag(99);
+  auto array = rag.Int32(4096, -30000, 30000);
+
+  auto schema = ::arrow::schema({::arrow::field("values", ::arrow::int32())});
+  auto table = Table::Make(schema, {std::make_shared<ChunkedArray>(array)});
+
+  auto writer_props =
+      WriterProperties::Builder().disable_dictionary()->encoding(Encoding::PFOR)->build();
+
+  auto sink = CreateOutputStream();
+  ASSERT_OK(WriteTable(*table, ::arrow::default_memory_pool(), sink, table->num_rows(),
+                       writer_props));
+  ASSERT_OK_AND_ASSIGN(auto buffer, sink->Finish());
+
+  std::unique_ptr<FileReader> reader;
+  FileReaderBuilder builder;
+  ASSERT_OK_NO_THROW(builder.Open(std::make_shared<BufferReader>(buffer)));
+  ASSERT_OK(builder.properties(default_arrow_reader_properties())->Build(&reader));
+  reader->set_batch_size(97);
+
+  ASSERT_OK_AND_ASSIGN(auto batch_reader, reader->GetRecordBatchReader());
+  ASSERT_OK_AND_ASSIGN(auto result, batch_reader->ToTable());
+
+  ASSERT_NO_FATAL_FAILURE(
+      ::arrow::AssertTablesEqual(*table, *result, /*same_chunk_layout=*/false));
+}
+
+}  // namespace
+}  // namespace arrow
+}  // namespace parquet
diff --git a/cpp/src/parquet/column_writer_test.cc b/cpp/src/parquet/column_writer_test.cc
index 69ec07c1b78f..d4b183305da4 100644
--- a/cpp/src/parquet/column_writer_test.cc
+++ b/cpp/src/parquet/column_writer_test.cc
@@ -178,6 +178,40 @@ class TestPrimitiveWriter : public PrimitiveTypedTest<TestType> {
     ASSERT_NO_FATAL_FAILURE(this->ReadAndCompare(compression, num_rows, enable_checksum));
   }
 
+  // Round-trip an optional PFOR column through a DataPageV2 page. Optional pages
+  // carry definition levels, and when every value is null the encoder is flushed
+  // with no values at all.
+  void TestPforOptionalDataPageV2(int num_nulls) {
+    ASSERT_LE(num_nulls, SMALL_SIZE);
+    this->SetUpSchema(Repetition::OPTIONAL);
+    this->descr_ = this->schema_.Column(0);
+    this->GenerateData(SMALL_SIZE);
+
+    // The nulls come first, so the values the writer consumes are the leading
+    // SMALL_SIZE - num_nulls entries of `values_`.
+    std::vector<int16_t> definition_levels(SMALL_SIZE, 1);
+    for (int i = 0; i < num_nulls; ++i) {
+      definition_levels[i] = 0;
+    }
+
+    ColumnProperties column_properties;
+    column_properties.set_encoding(Encoding::PFOR);
+    auto writer =
+        this->BuildWriter(SMALL_SIZE, column_properties, ParquetVersion::PARQUET_2_LATEST,
+                          ParquetDataPageVersion::V2);
+    writer->WriteBatch(SMALL_SIZE, definition_levels.data(), nullptr, this->values_ptr_);
+    writer->Close();
+
+    ASSERT_EQ(SMALL_SIZE, this->metadata_num_values());
+
+    this->ReadColumn();
+    const int64_t num_expected = SMALL_SIZE - num_nulls;
+    ASSERT_EQ(num_expected, this->values_read_);
+    this->values_out_.resize(num_expected);
+    this->values_.resize(num_expected);
+    ASSERT_EQ(this->values_, this->values_out_);
+  }
+
   void TestRequiredWithCodecOptions(Encoding::type encoding,
                                     Compression::type compression, bool enable_dictionary,
                                     bool enable_statistics, int64_t num_rows = SMALL_SIZE,
@@ -2475,5 +2509,23 @@ TYPED_TEST(TestBloomFilterWriter, Basic) {
   }
 }
 
+// PFOR on an optional column with DataPageV2 pages
+TEST_F(TestValuesWriterInt32Type, PforOptionalDataPageV2) {
+  this->TestPforOptionalDataPageV2(/*num_nulls=*/3);
+}
+
+TEST_F(TestValuesWriterInt64Type, PforOptionalDataPageV2) {
+  this->TestPforOptionalDataPageV2(/*num_nulls=*/3);
+}
+
+// An all-null page holds no values, so its PFOR payload is a bare header
+TEST_F(TestValuesWriterInt32Type, PforAllNullDataPageV2) {
+  this->TestPforOptionalDataPageV2(/*num_nulls=*/SMALL_SIZE);
+}
+
+TEST_F(TestValuesWriterInt64Type, PforAllNullDataPageV2) {
+  this->TestPforOptionalDataPageV2(/*num_nulls=*/SMALL_SIZE);
+}
+
 }  // namespace test
 }  // namespace parquet
diff --git a/cpp/src/parquet/encoding_test.cc b/cpp/src/parquet/encoding_test.cc
index 831829e4a210..c9315f56c378 100644
--- a/cpp/src/parquet/encoding_test.cc
+++ b/cpp/src/parquet/encoding_test.cc
@@ -22,6 +22,7 @@
 #include <cstring>
 #include <functional>
 #include <limits>
+#include <numeric>
 #include <span>
 #include <utility>
 #include <vector>
@@ -1044,6 +1045,71 @@ class EncodingAdHocTyped : public ::testing::Test {
     ::arrow::AssertArraysEqual(*values, *result);
   }
 
+  void Pfor(int seed) {
+    if (!std::is_same<ParquetType, Int32Type>::value &&
+        !std::is_same<ParquetType, Int64Type>::value) {
+      return;
+    }
+    auto values = GetValues(seed);
+    auto encoder =
+        MakeTypedEncoder<ParquetType>(Encoding::PFOR,
+                                      /*use_dictionary=*/false, column_descr());
+    auto decoder = MakeTypedDecoder<ParquetType>(Encoding::PFOR, column_descr());
+
+    ASSERT_NO_THROW(encoder->Put(*values));
+    auto buf = encoder->FlushValues();
+
+    int num_values = static_cast<int>(values->length() - values->null_count());
+    decoder->SetData(num_values, buf->data(), static_cast<int>(buf->size()));
+
+    BuilderType acc(arrow_type(), ::arrow::default_memory_pool());
+    ASSERT_EQ(num_values,
+              decoder->DecodeArrow(static_cast<int>(values->length()),
+                                   static_cast<int>(values->null_count()),
+                                   values->null_bitmap_data(), values->offset(), &acc));
+
+    std::shared_ptr<::arrow::Array> result;
+    ASSERT_OK(acc.Finish(&result));
+    ASSERT_OK(result->ValidateFull());
+    ASSERT_EQ(size_, result->length());
+    ::arrow::AssertArraysEqual(*values, *result, /*verbose=*/true);
+  }
+
+  void PforDict(int seed) {
+    if constexpr (!std::is_same_v<ParquetType, Int32Type> &&
+                  !std::is_same_v<ParquetType, Int64Type>) {
+      return;
+    } else {
+      auto values = GetValues(seed);
+      auto encoder =
+          MakeTypedEncoder<ParquetType>(Encoding::PFOR,
+                                        /*use_dictionary=*/false, column_descr());
+      auto decoder = MakeTypedDecoder<ParquetType>(Encoding::PFOR, column_descr());
+
+      ASSERT_NO_THROW(encoder->Put(*values));
+      auto buf = encoder->FlushValues();
+
+      int num_values = static_cast<int>(values->length() - values->null_count());
+      decoder->SetData(num_values, buf->data(), static_cast<int>(buf->size()));
+
+      DictBuilderType acc(arrow_type(), ::arrow::default_memory_pool());
+      ASSERT_EQ(num_values,
+                decoder->DecodeArrow(static_cast<int>(values->length()),
+                                     static_cast<int>(values->null_count()),
+                                     values->null_bitmap_data(), values->offset(), &acc));
+
+      std::shared_ptr<::arrow::Array> result;
+      ASSERT_OK(acc.Finish(&result));
+      ASSERT_OK(result->ValidateFull());
+      ASSERT_EQ(size_, result->length());
+
+      // The accumulator produced a DictionaryArray; compare it densely.
+      ASSERT_OK_AND_ASSIGN(auto dense_datum,
+                           ::arrow::compute::Cast(::arrow::Datum(result), arrow_type()));
+      ::arrow::AssertArraysEqual(*values, *dense_datum.make_array(), /*verbose=*/true);
+    }
+  }
+
   void Dict(int seed) {
     if (std::is_same<ParquetType, BooleanType>::value) {
       return;
@@ -1228,6 +1294,27 @@ TYPED_TEST(EncodingAdHocTyped, DeltaBitPackArrowDirectPut) {
   }
 }
 
+TYPED_TEST(EncodingAdHocTyped, PforArrowDirectPut) {
+  for (auto seed : {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}) {
+    this->Pfor(seed);
+  }
+  // Same, but without nulls (this could trigger different code paths)
+  this->null_probability_ = 0.0;
+  for (auto seed : {0, 1, 2, 3, 4}) {
+    this->Pfor(seed);
+  }
+}
+
+TYPED_TEST(EncodingAdHocTyped, PforArrowDirectPutDictBuilder) {
+  for (auto seed : {0, 1, 2, 3, 4}) {
+    this->PforDict(seed);
+  }
+  this->null_probability_ = 0.0;
+  for (auto seed : {0, 1, 2, 3, 4}) {
+    this->PforDict(seed);
+  }
+}
+
 TYPED_TEST(EncodingAdHocTyped, DictArrowDirectPut) { this->Dict(0); }
 
 TYPED_TEST(EncodingAdHocTyped, DictArrowDirectPutIndices) { this->DictPutIndices(); }
@@ -2034,6 +2121,157 @@ TYPED_TEST(TestDeltaBitPackEncoding, ZeroDeltaBitWidth) {
   this->CheckRoundtripWithValues(int_values);
 }
 
+// ----------------------------------------------------------------------
+// PFOR encode/decode tests.
+
+template <typename Type>
+class TestPforEncoding : public TestEncodingBase<Type> {
+ public:
+  using c_type = typename Type::c_type;
+  static constexpr int TYPE = Type::type_num;
+
+  void CheckDecoding(int read_batch_size) {
+    auto decoder = MakeTypedDecoder<Type>(Encoding::PFOR, descr_.get());
+    decoder->SetData(num_values_, encode_buffer_->data(),
+                     static_cast<int>(encode_buffer_->size()));
+
+    std::vector<c_type> decoded(num_values_);
+    int values_decoded = 0;
+    while (values_decoded < num_values_) {
+      const int decoded_now =
+          decoder->Decode(decoded.data() + values_decoded, read_batch_size);
+      ASSERT_GT(decoded_now, 0);
+      values_decoded += decoded_now;
+    }
+    ASSERT_EQ(num_values_, values_decoded);
+    ASSERT_NO_FATAL_FAILURE(VerifyResults<c_type>(decoded.data(), draws_, num_values_));
+  }
+
+  void CheckRoundtrip() override {
+    auto encoder = MakeTypedEncoder<Type>(Encoding::PFOR,
+                                          /*use_dictionary=*/false, descr_.get());
+    encoder->Put(draws_, num_values_);
+    encode_buffer_ = encoder->FlushValues();
+
+    // A reader asks for whatever its batch size is, so the page has to come out
+    // the same whether it is drained in one call or in many.
+    for (const int read_batch_size : {1, 11, num_values_}) {
+      if (read_batch_size > 0) {
+        ASSERT_NO_FATAL_FAILURE(CheckDecoding(read_batch_size));
+      }
+    }
+  }
+
+ protected:
+  USING_BASE_MEMBERS();
+};
+
+using TestPforEncodingTypes = ::testing::Types<Int32Type, Int64Type>;
+TYPED_TEST_SUITE(TestPforEncoding, TestPforEncodingTypes);
+
+TYPED_TEST(TestPforEncoding, BasicRoundTrip) {
+  // The default vector size is 1024, so cover an empty page, a single value, a
+  // partial vector, an exact multiple, and a partial trailing vector.
+  ASSERT_NO_FATAL_FAILURE(this->Execute(0, 0));
+  ASSERT_NO_FATAL_FAILURE(this->Execute(1, 1));
+  ASSERT_NO_FATAL_FAILURE(this->Execute(100, 1));
+  ASSERT_NO_FATAL_FAILURE(this->Execute(1024, 4));
+  ASSERT_NO_FATAL_FAILURE(this->Execute(1025, 3));
+}
+
+TYPED_TEST(TestPforEncoding, DecoderReusedAcrossPages) {
+  using c_type = typename TypeParam::c_type;
+  auto encoder =
+      MakeTypedEncoder<TypeParam>(Encoding::PFOR,
+                                  /*use_dictionary=*/false, this->descr_.get());
+  auto decoder = MakeTypedDecoder<TypeParam>(Encoding::PFOR, this->descr_.get());
+
+  // A column chunk reuses one decoder for all of its data pages, with only
+  // SetData between them. The second page is the longer one, so a decoder that
+  // kept the first page's values would also read past the end of them.
+  const std::vector<std::vector<c_type>> pages = {
+      {10, 11, 12, 13}, {900, 901, 902, 903, 904, 905, 906, 907}};
+
+  for (const auto& page : pages) {
+    const int page_values = static_cast<int>(page.size());
+    encoder->Put(page.data(), page_values);
+    auto buffer = encoder->FlushValues();
+    decoder->SetData(page_values, buffer->data(), static_cast<int>(buffer->size()));
+
+    std::vector<c_type> decoded(page.size());
+    ASSERT_EQ(page_values, decoder->Decode(decoded.data(), page_values));
+    ASSERT_EQ(page, decoded);
+  }
+}
+
+TYPED_TEST(TestPforEncoding, AllNullPage) {
+  constexpr int kNumValues = 40;
+  auto encoder =
+      MakeTypedEncoder<TypeParam>(Encoding::PFOR,
+                                  /*use_dictionary=*/false, this->descr_.get());
+  auto buffer = encoder->FlushValues();
+
+  // A reader hands the decoder the page's level count, which counts the nulls, so
+  // the page and its bare header have to survive being handed the full count.
+  auto decoder = MakeTypedDecoder<TypeParam>(Encoding::PFOR, this->descr_.get());
+  decoder->SetData(kNumValues, buffer->data(), static_cast<int>(buffer->size()));
+
+  // All slots are null, so the page carries no encoded values at all.
+  std::vector<uint8_t> valid_bits(bit_util::BytesForBits(kNumValues), 0);
+  typename EncodingTraits<TypeParam>::Accumulator acc;
+  ASSERT_EQ(0, decoder->DecodeArrow(kNumValues, /*null_count=*/kNumValues,
+                                    valid_bits.data(), /*valid_bits_offset=*/0, &acc));
+
+  std::shared_ptr<::arrow::Array> result;
+  ASSERT_OK(acc.Finish(&result));
+  ASSERT_OK(result->ValidateFull());
+  ASSERT_EQ(kNumValues, result->length());
+  ASSERT_EQ(kNumValues, result->null_count());
+}
+
+TYPED_TEST(TestPforEncoding, RejectsPageWithUnreadValues) {
+  using c_type = typename TypeParam::c_type;
+  constexpr int kNumValues = 200;
+  constexpr int kNullCount = 30;
+
+  std::vector<c_type> values(kNumValues);
+  std::iota(values.begin(), values.end(), static_cast<c_type>(0));
+  auto encoder =
+      MakeTypedEncoder<TypeParam>(Encoding::PFOR,
+                                  /*use_dictionary=*/false, this->descr_.get());
+  encoder->Put(values.data(), kNumValues);
+  auto encoded = encoder->FlushValues();
+
+  std::vector<uint8_t> valid_bits(bit_util::BytesForBits(kNumValues), 0);
+  for (int i = 0; i < kNumValues - kNullCount; ++i) {
+    bit_util::SetBit(valid_bits.data(), i);
+  }
+  std::vector<c_type> output(kNumValues);
+  auto decoder = MakeTypedDecoder<TypeParam>(Encoding::PFOR, this->descr_.get());
+  decoder->SetData(kNumValues, encoded->data(), static_cast<int>(encoded->size()));
+  ASSERT_THROW(decoder->DecodeSpaced(output.data(), kNumValues, kNullCount,
+                                     valid_bits.data(), /*valid_bits_offset=*/0),
+               ParquetException);
+}
+
+TYPED_TEST(TestPforEncoding, RejectsNegativeArguments) {
+  using c_type = typename TypeParam::c_type;
+  auto decoder = MakeTypedDecoder<TypeParam>(Encoding::PFOR, this->descr_.get());
+  uint8_t byte = 0;
+  ASSERT_THROW(decoder->SetData(-1, &byte, 1), ParquetException);
+  ASSERT_THROW(decoder->SetData(0, &byte, -1), ParquetException);
+
+  auto encoder =
+      MakeTypedEncoder<TypeParam>(Encoding::PFOR,
+                                  /*use_dictionary=*/false, this->descr_.get());
+  const c_type value = 7;
+  encoder->Put(&value, 1);
+  auto encoded = encoder->FlushValues();
+  decoder->SetData(1, encoded->data(), static_cast<int>(encoded->size()));
+  c_type output{};
+  ASSERT_THROW(decoder->Decode(&output, -1), ParquetException);
+}
+
 // ----------------------------------------------------------------------
 // Rle for Boolean encode/decode tests.
 
diff --git a/cpp/src/parquet/pfor_comparison_benchmark.cc b/cpp/src/parquet/pfor_comparison_benchmark.cc
new file mode 100644
index 000000000000..7d7d8c48dfa2
--- /dev/null
+++ b/cpp/src/parquet/pfor_comparison_benchmark.cc
@@ -0,0 +1,1003 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Comparison benchmark: PFOR vs DeltaBitPack vs ZSTD vs RleBitPackHybrid
+//                       vs ByteStreamSplit+ZSTD vs ByteStreamSplit+LZ4
+//
+// All throughput is reported as uncompressed_size / time (MB/s).
+// Data generators mimic ClickBench and TPC-DS column distributions.
+
+#include <algorithm>
+#include <bit>
+#include <cmath>
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <numeric>
+#include <random>
+#include <string>
+#include <type_traits>
+#include <vector>
+
+#include "benchmark/benchmark.h"
+
+#include "arrow/util/compression.h"
+#include "arrow/util/logging.h"
+#include "arrow/util/pfor/pfor_wrapper_internal.h"
+#include "arrow/util/rle_encoding_internal.h"
+
+#include "parquet/encoding.h"
+#include "parquet/platform.h"
+#include "parquet/schema.h"
+#include "parquet/types.h"
+
+using ::arrow::Compression;
+using ::arrow::util::Codec;
+
+namespace parquet {
+namespace {
+
+// ----------------------------------------------------------------------
+// Data Generators — ClickBench-inspired
+
+// Generator pointer type, parameterized on the column value type.
+template <typename T>
+using GenT = std::vector<T> (*)(int64_t);
+using Gen32 = GenT<int32_t>;
+using Gen64 = GenT<int64_t>;
+
+// Map the C++ value type to its Parquet physical type + descriptor type.
+template <typename T>
+struct PqTraits;
+template <>
+struct PqTraits<int32_t> {
+  using PType = Int32Type;
+  static constexpr Type::type kPhysicalType = Type::INT32;
+};
+template <>
+struct PqTraits<int64_t> {
+  using PType = Int64Type;
+  static constexpr Type::type kPhysicalType = Type::INT64;
+};
+
+std::vector<int32_t> GenClientIP(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(101);
+  std::uniform_int_distribution<uint32_t> dist(0x0A000000, 0xDFFFFFFF);
+  for (auto& x : v) x = static_cast<int32_t>(dist(rng));
+  return v;
+}
+
+std::vector<int32_t> GenUrlRegionID(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(102);
+  // Zipf-like over ~1000 values
+  std::uniform_real_distribution<double> uni(0.0, 1.0);
+  for (auto& x : v) {
+    double u = uni(rng);
+    x = static_cast<int32_t>(std::pow(u, 2.0) * 1000) + 1;
+  }
+  return v;
+}
+
+std::vector<int32_t> GenCounterID(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(103);
+  std::uniform_int_distribution<int32_t> jitter(0, 3);
+  int32_t counter = 100000;
+  for (auto& x : v) {
+    counter += 1 + jitter(rng);
+    x = counter;
+  }
+  return v;
+}
+
+std::vector<int32_t> GenEventDate(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(104);
+  const int32_t dates[] = {19691, 19692, 19693, 19694, 19695};
+  std::uniform_int_distribution<int> idx(0, 4);
+  for (auto& x : v) x = dates[idx(rng)];
+  return v;
+}
+
+std::vector<int32_t> GenEventTime(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(105);
+  const int32_t base = 1704067200;  // 2024-01-01
+  std::uniform_int_distribution<int32_t> offset(0, 86399);
+  for (auto& x : v) x = base + offset(rng);
+  return v;
+}
+
+std::vector<int32_t> GenGoodEvent(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(106);
+  std::uniform_int_distribution<int> dist(0, 99);
+  for (auto& x : v) x = (dist(rng) < 95) ? 1 : 0;
+  return v;
+}
+
+std::vector<int32_t> GenHID(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(107);
+  std::uniform_int_distribution<int32_t> dist(std::numeric_limits<int32_t>::min(),
+                                              std::numeric_limits<int32_t>::max());
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+std::vector<int32_t> GenHitColor(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(108);
+  const int32_t colors[] = {1, 2, 3, 4, 5};
+  std::uniform_int_distribution<int> idx(0, 4);
+  for (auto& x : v) x = colors[idx(rng)];
+  return v;
+}
+
+std::vector<int32_t> GenIPNetworkID(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(109);
+  std::uniform_int_distribution<int32_t> dist(1, 10000);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+std::vector<int32_t> GenJavaEnable(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(110);
+  std::uniform_int_distribution<int> dist(0, 99);
+  for (auto& x : v) x = (dist(rng) < 85) ? 1 : 0;
+  return v;
+}
+
+std::vector<int32_t> GenOS(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(111);
+  std::uniform_int_distribution<int32_t> dist(1, 20);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+std::vector<int32_t> GenResolution(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(112);
+  const int32_t resolutions[] = {360,  480,  600,  720,  768,  800,  900,
+                                 1024, 1050, 1080, 1200, 1440, 1600, 2160};
+  std::uniform_int_distribution<int> idx(0, 13);
+  for (auto& x : v) x = resolutions[idx(rng)];
+  return v;
+}
+
+std::vector<int32_t> GenTrafficSourceID(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(113);
+  std::uniform_int_distribution<int32_t> dist(0, 10);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+std::vector<int32_t> GenUserAgent(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(114);
+  // Zipf-like over ~100 user agents
+  std::uniform_real_distribution<double> uni(0.0, 1.0);
+  for (auto& x : v) {
+    double u = uni(rng);
+    x = static_cast<int32_t>(std::pow(u, 1.5) * 100) + 1;
+  }
+  return v;
+}
+
+// ----------------------------------------------------------------------
+// Data Generators — TPC-DS (4 most queried columns from store_sales)
+
+std::vector<int32_t> GenTpcdsSoldDateSk(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kBase = 2450815;
+  std::mt19937 rng(201);
+  std::uniform_int_distribution<int32_t> dist(0, 1820);
+  for (auto& x : v) x = kBase + dist(rng);
+  return v;
+}
+
+std::vector<int32_t> GenTpcdsStoreSk(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(202);
+  std::uniform_int_distribution<int32_t> dist(1, 1000);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+std::vector<int32_t> GenTpcdsItemSk(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kMax = 100000;
+  std::mt19937 rng(203);
+  std::exponential_distribution<double> exp_dist(0.00005);
+  for (auto& x : v) {
+    int32_t val = static_cast<int32_t>(exp_dist(rng));
+    x = std::min(val + 1, kMax);
+  }
+  return v;
+}
+
+std::vector<int32_t> GenTpcdsQuantity(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(204);
+  std::uniform_int_distribution<int32_t> small_dist(1, 10);
+  std::uniform_int_distribution<int32_t> large_dist(11, 100);
+  std::uniform_int_distribution<int> chance(0, 99);
+  for (auto& x : v) {
+    x = (chance(rng) < 90) ? small_dist(rng) : large_dist(rng);
+  }
+  return v;
+}
+
+// --- TPC-H (lineitem) top-queried numeric columns (Q1/Q3/Q5/Q6) ------------
+// l_quantity: integer [1, 50], uniform. Small range, min 1.
+std::vector<int32_t> GenTpchLQuantity(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(301);
+  std::uniform_int_distribution<int32_t> dist(1, 50);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// l_extendedprice (cents): l_quantity * p_retailprice. p_retailprice spans
+// ~$900.00..$2099.00, so cents in [90000, 10495000]. Wide range, nonzero min.
+std::vector<int32_t> GenTpchLExtendedPrice(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(302);
+  std::uniform_int_distribution<int32_t> qty(1, 50);
+  std::uniform_int_distribution<int32_t> retail_cents(90000, 209900);
+  for (auto& x : v) x = qty(rng) * retail_cents(rng);
+  return v;
+}
+
+// l_discount (x100): integer [0, 10] i.e. 0.00..0.10. Genuinely includes 0
+// (0% discount is a real value), so this one legitimately starts at 0.
+std::vector<int32_t> GenTpchLDiscount(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(303);
+  std::uniform_int_distribution<int32_t> dist(0, 10);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// l_shipdate (days since 1970-01-01): 1992-01-01..1998-12 span. Base 8036,
+// range ~7 years. Large nonzero min -> exercises frame-of-reference.
+std::vector<int32_t> GenTpchLShipDate(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kBase = 8036;  // days since epoch for 1992-01-01
+  std::mt19937 rng(304);
+  std::uniform_int_distribution<int32_t> dist(0, 2557);
+  for (auto& x : v) x = kBase + dist(rng);
+  return v;
+}
+
+// --- TPC-DS (store_sales / date_dim) further top-queried numeric columns ---
+// ss_customer_sk: surrogate key, uniform [1, 2,000,000]. Big range, min 1.
+std::vector<int32_t> GenTpcdsCustomerSk(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(311);
+  std::uniform_int_distribution<int32_t> dist(1, 2000000);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// ss_ext_sales_price (cents): skewed price, exponential mean ~$50, floored at
+// $1.00 (a sale has a nonzero price), capped at $20,000. Long tail -> patches.
+std::vector<int32_t> GenTpcdsExtSalesPrice(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kMin = 100, kMax = 2000000;
+  std::mt19937 rng(312);
+  std::exponential_distribution<double> exp_dist(1.0 / 5000.0);
+  for (auto& x : v) {
+    int32_t val = kMin + static_cast<int32_t>(exp_dist(rng));
+    x = std::min(val, kMax);
+  }
+  return v;
+}
+
+// ss_net_profit (cents): usually a small profit, sometimes a loss -> negative
+// values, so the frame of reference is negative (not zero).
+std::vector<int32_t> GenTpcdsNetProfit(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(313);
+  std::uniform_int_distribution<int32_t> dist(-10000, 300000);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// d_year: queried date_dim year range [1998, 2003]. Low cardinality, min 1998.
+std::vector<int32_t> GenTpcdsDYear(int64_t n) {
+  std::vector<int32_t> v(n);
+  std::mt19937 rng(314);
+  std::uniform_int_distribution<int32_t> dist(1998, 2003);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// --- NYC yellow-taxi trip numeric columns ----------------------------------
+// pickup timestamp (unix seconds): 2015-01, base 1,420,070,400 + ~31 days.
+// Very large min -> frame-of-reference is essential.
+std::vector<int32_t> GenTaxiPickupUnixTime(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kBase = 1420070400;  // 2015-01-01 UTC
+  std::mt19937 rng(321);
+  std::uniform_int_distribution<int32_t> dist(0, 2678400);  // ~31 days
+  for (auto& x : v) x = kBase + dist(rng);
+  return v;
+}
+
+// trip_distance (x100 miles): exponential mean ~1.8 mi, floored at 0.10 mi
+// (no zero-distance trips), capped at 100 mi. Long tail -> patches.
+std::vector<int32_t> GenTaxiTripDistanceX100(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kMin = 10, kMax = 10000;
+  std::mt19937 rng(322);
+  std::exponential_distribution<double> exp_dist(1.0 / 180.0);
+  for (auto& x : v) {
+    int32_t val = kMin + static_cast<int32_t>(exp_dist(rng));
+    x = std::min(val, kMax);
+  }
+  return v;
+}
+
+// fare_amount (cents): $2.50 base + exponential mean ~$10, capped at $150.
+// Nonzero floor at the base fare, skewed with a long tail.
+std::vector<int32_t> GenTaxiFareCents(int64_t n) {
+  std::vector<int32_t> v(n);
+  const int32_t kBase = 250, kMax = 15000;
+  std::mt19937 rng(323);
+  std::exponential_distribution<double> exp_dist(1.0 / 1000.0);
+  for (auto& x : v) {
+    int32_t val = kBase + static_cast<int32_t>(exp_dist(rng));
+    x = std::min(val, kMax);
+  }
+  return v;
+}
+
+// ----------------------------------------------------------------------
+// Data Generators — int64 / BIGINT columns (values that require 8 bytes,
+// i.e. exceed the int32 range). Covers the common 64-bit analytic cases:
+// nanosecond timestamps, large surrogate keys, scaled-decimal money, monotone
+// IDs, and wide counters.
+
+// Nanosecond epoch timestamp (Parquet TIMESTAMP(NANOS)): 2024-01-01 base plus
+// up to ~1 day of jitter. Min ~1.70e18 -> very large frame of reference; raw
+// values need ~61 bits.
+std::vector<int64_t> GenTsNanos(int64_t n) {
+  std::vector<int64_t> v(n);
+  const int64_t kBase = 1704067200000000000LL;  // 2024-01-01T00:00:00Z in ns
+  std::mt19937_64 rng(401);
+  std::uniform_int_distribution<int64_t> off(0, 86399999999999LL);  // ~1 day
+  for (auto& x : v) x = kBase + off(rng);
+  return v;
+}
+
+// BIGINT surrogate / order key, uniform over [1, 10 billion] (exceeds 2^32).
+std::vector<int64_t> GenOrderKey(int64_t n) {
+  std::vector<int64_t> v(n);
+  std::mt19937_64 rng(402);
+  std::uniform_int_distribution<int64_t> dist(1, 10000000000LL);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// Money as int64 scaled decimal (micro-units): $0.01 .. ~$100k, skewed, with a
+// nonzero floor at one cent.
+std::vector<int64_t> GenPriceMicros(int64_t n) {
+  std::vector<int64_t> v(n);
+  const int64_t kMin = 10000, kMax = 100000000000LL;  // $0.01 .. $100,000
+  std::mt19937_64 rng(403);
+  std::exponential_distribution<double> exp_dist(1.0 / 5000000.0);  // mean ~$5
+  for (auto& x : v) {
+    int64_t val = kMin + static_cast<int64_t>(exp_dist(rng));
+    x = std::min(val, kMax);
+  }
+  return v;
+}
+
+// Snowflake-style monotone ID: large base + jittered per-row increments.
+// Monotone -> ideal for DELTA_BINARY_PACKED; huge min -> ideal for PFOR's FOR.
+std::vector<int64_t> GenSnowflakeId(int64_t n) {
+  std::vector<int64_t> v(n);
+  std::mt19937_64 rng(404);
+  std::uniform_int_distribution<int64_t> step(1, 4096);
+  int64_t id = 1500000000000000000LL;
+  for (auto& x : v) {
+    id += step(rng);
+    x = id;
+  }
+  return v;
+}
+
+// Wide cumulative byte counts, uniform [1024, 5 trillion] (wide 64-bit range).
+std::vector<int64_t> GenByteCount(int64_t n) {
+  std::vector<int64_t> v(n);
+  std::mt19937_64 rng(405);
+  std::uniform_int_distribution<int64_t> dist(1024, 5000000000000LL);
+  for (auto& x : v) x = dist(rng);
+  return v;
+}
+
+// ----------------------------------------------------------------------
+// Helpers
+
+template <typename T>
+static int32_t ComputeBitWidth(const std::vector<T>& values) {
+  using U = std::make_unsigned_t<T>;
+  U max_val = 0;
+  for (T v : values) {
+    max_val = std::max(max_val, static_cast<U>(v));
+  }
+  if (max_val == 0) return 1;
+  if constexpr (sizeof(T) == 8) {
+    return static_cast<int32_t>(std::bit_width(static_cast<uint64_t>(max_val)));
+  } else {
+    return static_cast<int32_t>(std::bit_width(static_cast<uint32_t>(max_val)));
+  }
+}
+
+template <typename T>
+static std::shared_ptr<ColumnDescriptor> MakeDescriptor() {
+  auto node = schema::PrimitiveNode::Make("col", Repetition::REQUIRED,
+                                          PqTraits<T>::kPhysicalType);
+  return std::make_shared<ColumnDescriptor>(node, /*max_def_level=*/0,
+                                            /*max_rep_level=*/0);
+}
+
+// ----------------------------------------------------------------------
+// PFOR Encode/Decode
+
+template <typename T>
+static void PforEncodeImpl(benchmark::State& state, GenT<T> gen) {
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  int64_t max_size = ::arrow::util::pfor::PforWrapper<T>::GetMaxCompressedSize(
+                         static_cast<int32_t>(num_values))
+                         .ValueOrDie();
+  std::vector<uint8_t> compressed(max_size);
+
+  // Compute comp_size once for the counter
+  int64_t comp_size = max_size;
+  ARROW_CHECK_OK(::arrow::util::pfor::PforWrapper<T>::Encode(
+      values.data(), static_cast<int32_t>(num_values), compressed.data(), &comp_size));
+
+  for (auto _ : state) {
+    int64_t sz = max_size;
+    ARROW_CHECK_OK(::arrow::util::pfor::PforWrapper<T>::Encode(
+        values.data(), static_cast<int32_t>(num_values), compressed.data(), &sz));
+    benchmark::DoNotOptimize(sz);
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_PforEncode(benchmark::State& state, Gen32 gen) {
+  PforEncodeImpl<int32_t>(state, gen);
+}
+static void BM_Pfor64Encode(benchmark::State& state, Gen64 gen) {
+  PforEncodeImpl<int64_t>(state, gen);
+}
+
+template <typename T>
+static void PforDecodeImpl(benchmark::State& state, GenT<T> gen) {
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  int64_t max_size = ::arrow::util::pfor::PforWrapper<T>::GetMaxCompressedSize(
+                         static_cast<int32_t>(num_values))
+                         .ValueOrDie();
+  std::vector<uint8_t> compressed(max_size);
+  int64_t comp_size = max_size;
+  ARROW_CHECK_OK(::arrow::util::pfor::PforWrapper<T>::Encode(
+      values.data(), static_cast<int32_t>(num_values), compressed.data(), &comp_size));
+
+  std::vector<T> decoded(num_values);
+  for (auto _ : state) {
+    auto status = ::arrow::util::pfor::PforWrapper<T>::Decode(
+        compressed.data(), comp_size, static_cast<int32_t>(num_values), decoded.data());
+    ARROW_CHECK_OK(status);
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_PforDecode(benchmark::State& state, Gen32 gen) {
+  PforDecodeImpl<int32_t>(state, gen);
+}
+static void BM_Pfor64Decode(benchmark::State& state, Gen64 gen) {
+  PforDecodeImpl<int64_t>(state, gen);
+}
+
+// ----------------------------------------------------------------------
+// DeltaBitPack Encode/Decode
+
+template <typename T>
+static void DeltaBitPackEncodeImpl(benchmark::State& state, GenT<T> gen) {
+  using PType = typename PqTraits<T>::PType;
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  auto encoder = MakeTypedEncoder<PType>(Encoding::DELTA_BINARY_PACKED);
+
+  // Compute comp_size once for the counter
+  encoder->Put(values.data(), static_cast<int>(num_values));
+  auto pre_buf = encoder->FlushValues();
+  int64_t comp_size = pre_buf->size();
+
+  for (auto _ : state) {
+    encoder->Put(values.data(), static_cast<int>(num_values));
+    auto buf = encoder->FlushValues();
+    benchmark::DoNotOptimize(buf);
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_DeltaBitPackEncode(benchmark::State& state, Gen32 gen) {
+  DeltaBitPackEncodeImpl<int32_t>(state, gen);
+}
+static void BM_DeltaBitPack64Encode(benchmark::State& state, Gen64 gen) {
+  DeltaBitPackEncodeImpl<int64_t>(state, gen);
+}
+
+template <typename T>
+static void DeltaBitPackDecodeImpl(benchmark::State& state, GenT<T> gen) {
+  using PType = typename PqTraits<T>::PType;
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  auto encoder = MakeTypedEncoder<PType>(Encoding::DELTA_BINARY_PACKED);
+  encoder->Put(values.data(), static_cast<int>(num_values));
+  auto buf = encoder->FlushValues();
+  int64_t comp_size = buf->size();
+
+  std::vector<T> decoded(num_values);
+  auto decoder = MakeTypedDecoder<PType>(Encoding::DELTA_BINARY_PACKED);
+
+  for (auto _ : state) {
+    decoder->SetData(static_cast<int>(num_values), buf->data(),
+                     static_cast<int>(buf->size()));
+    decoder->Decode(decoded.data(), static_cast<int>(num_values));
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_DeltaBitPackDecode(benchmark::State& state, Gen32 gen) {
+  DeltaBitPackDecodeImpl<int32_t>(state, gen);
+}
+static void BM_DeltaBitPack64Decode(benchmark::State& state, Gen64 gen) {
+  DeltaBitPackDecodeImpl<int64_t>(state, gen);
+}
+
+// ----------------------------------------------------------------------
+// Plain + ZSTD Encode/Decode
+
+template <typename T>
+static void PlainCodecEncodeImpl(benchmark::State& state, GenT<T> gen,
+                                 Compression::type codec_type) {
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+  const uint8_t* raw = reinterpret_cast<const uint8_t*>(values.data());
+
+  auto codec = *Codec::Create(codec_type);
+  int64_t max_comp = codec->MaxCompressedLen(uncompressed_size, raw);
+  std::vector<uint8_t> compressed(max_comp);
+
+  // Compute comp_size once for the counter
+  int64_t comp_size =
+      *codec->Compress(uncompressed_size, raw, max_comp, compressed.data());
+
+  for (auto _ : state) {
+    auto sz = *codec->Compress(uncompressed_size, raw, max_comp, compressed.data());
+    benchmark::DoNotOptimize(sz);
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+
+template <typename T>
+static void PlainCodecDecodeImpl(benchmark::State& state, GenT<T> gen,
+                                 Compression::type codec_type) {
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+  const uint8_t* raw = reinterpret_cast<const uint8_t*>(values.data());
+
+  auto codec = *Codec::Create(codec_type);
+  int64_t max_comp = codec->MaxCompressedLen(uncompressed_size, raw);
+  std::vector<uint8_t> compressed(max_comp);
+  int64_t comp_size =
+      *codec->Compress(uncompressed_size, raw, max_comp, compressed.data());
+
+  std::vector<uint8_t> decompressed(uncompressed_size);
+  for (auto _ : state) {
+    auto result = codec->Decompress(comp_size, compressed.data(), uncompressed_size,
+                                    decompressed.data());
+    ARROW_CHECK_OK(result.status());
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_PlainZstdEncode(benchmark::State& state, Gen32 gen) {
+  PlainCodecEncodeImpl<int32_t>(state, gen, Compression::ZSTD);
+}
+static void BM_PlainZstd64Encode(benchmark::State& state, Gen64 gen) {
+  PlainCodecEncodeImpl<int64_t>(state, gen, Compression::ZSTD);
+}
+static void BM_PlainZstdDecode(benchmark::State& state, Gen32 gen) {
+  PlainCodecDecodeImpl<int32_t>(state, gen, Compression::ZSTD);
+}
+static void BM_PlainZstd64Decode(benchmark::State& state, Gen64 gen) {
+  PlainCodecDecodeImpl<int64_t>(state, gen, Compression::ZSTD);
+}
+
+// ----------------------------------------------------------------------
+// Plain + LZ4 Encode/Decode
+
+static void BM_PlainLz4Encode(benchmark::State& state, Gen32 gen) {
+  PlainCodecEncodeImpl<int32_t>(state, gen, Compression::LZ4_FRAME);
+}
+static void BM_PlainLz464Encode(benchmark::State& state, Gen64 gen) {
+  PlainCodecEncodeImpl<int64_t>(state, gen, Compression::LZ4_FRAME);
+}
+static void BM_PlainLz4Decode(benchmark::State& state, Gen32 gen) {
+  PlainCodecDecodeImpl<int32_t>(state, gen, Compression::LZ4_FRAME);
+}
+static void BM_PlainLz464Decode(benchmark::State& state, Gen64 gen) {
+  PlainCodecDecodeImpl<int64_t>(state, gen, Compression::LZ4_FRAME);
+}
+
+// ----------------------------------------------------------------------
+// RleBitPackHybrid Encode/Decode
+
+template <typename T>
+static void RleBitPackEncodeImpl(benchmark::State& state, GenT<T> gen) {
+  using U = std::make_unsigned_t<T>;
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  int32_t bit_width = ComputeBitWidth<T>(values);
+  int64_t max_buf =
+      ::arrow::util::RleBitPackedEncoder::MaxBufferSize(bit_width, num_values) +
+      ::arrow::util::RleBitPackedEncoder::MinBufferSize(bit_width);
+  std::vector<uint8_t> buffer(max_buf);
+
+  // Compute comp_size once for the counter
+  int64_t comp_size;
+  {
+    ::arrow::util::RleBitPackedEncoder enc(buffer.data(), static_cast<int>(max_buf),
+                                           bit_width);
+    for (int64_t i = 0; i < num_values; ++i) {
+      enc.Put(static_cast<uint64_t>(static_cast<U>(values[i])));
+    }
+    comp_size = enc.Flush();
+  }
+
+  for (auto _ : state) {
+    ::arrow::util::RleBitPackedEncoder encoder(buffer.data(), static_cast<int>(max_buf),
+                                               bit_width);
+    for (int64_t i = 0; i < num_values; ++i) {
+      encoder.Put(static_cast<uint64_t>(static_cast<U>(values[i])));
+    }
+    auto sz = encoder.Flush();
+    benchmark::DoNotOptimize(sz);
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_RleBitPackEncode(benchmark::State& state, Gen32 gen) {
+  RleBitPackEncodeImpl<int32_t>(state, gen);
+}
+static void BM_RleBitPack64Encode(benchmark::State& state, Gen64 gen) {
+  RleBitPackEncodeImpl<int64_t>(state, gen);
+}
+
+template <typename T>
+static void RleBitPackDecodeImpl(benchmark::State& state, GenT<T> gen) {
+  using U = std::make_unsigned_t<T>;
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  int32_t bit_width = ComputeBitWidth<T>(values);
+  int64_t max_buf =
+      ::arrow::util::RleBitPackedEncoder::MaxBufferSize(bit_width, num_values) +
+      ::arrow::util::RleBitPackedEncoder::MinBufferSize(bit_width);
+  std::vector<uint8_t> buffer(max_buf);
+
+  ::arrow::util::RleBitPackedEncoder encoder(buffer.data(), static_cast<int>(max_buf),
+                                             bit_width);
+  for (int64_t i = 0; i < num_values; ++i) {
+    encoder.Put(static_cast<uint64_t>(static_cast<U>(values[i])));
+  }
+  int comp_size = encoder.Flush();
+
+  std::vector<T> decoded(num_values);
+  for (auto _ : state) {
+    ::arrow::util::RleBitPackedParser parser(buffer.data(), comp_size, bit_width);
+    int64_t out_idx = 0;
+    struct Handler {
+      T* output;
+      int64_t* idx;
+      int64_t max_values;
+      int32_t bw;
+      ::arrow::util::RleBitPackedParser::ControlFlow OnRleRun(::arrow::util::RleRun run) {
+        ::arrow::util::RleRunDecoder<T> dec(run, bw);
+        auto want = static_cast<int32_t>(
+            std::min(static_cast<int64_t>(run.values_count()), max_values - *idx));
+        auto count = dec.GetBatch(output + *idx, want, bw);
+        *idx += count;
+        return *idx >= max_values
+                   ? ::arrow::util::RleBitPackedParser::ControlFlow::Break
+                   : ::arrow::util::RleBitPackedParser::ControlFlow::Continue;
+      }
+      ::arrow::util::RleBitPackedParser::ControlFlow OnBitPackedRun(
+          ::arrow::util::BitPackedRun run) {
+        ::arrow::util::BitPackedRunDecoder<T> dec(run, bw);
+        auto want = static_cast<int32_t>(
+            std::min(static_cast<int64_t>(dec.remaining()), max_values - *idx));
+        auto count = dec.GetBatch(output + *idx, want, bw);
+        *idx += count;
+        return *idx >= max_values
+                   ? ::arrow::util::RleBitPackedParser::ControlFlow::Break
+                   : ::arrow::util::RleBitPackedParser::ControlFlow::Continue;
+      }
+    };
+    Handler handler{decoded.data(), &out_idx, num_values, bit_width};
+    parser.Parse(handler);
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+static void BM_RleBitPackDecode(benchmark::State& state, Gen32 gen) {
+  RleBitPackDecodeImpl<int32_t>(state, gen);
+}
+static void BM_RleBitPack64Decode(benchmark::State& state, Gen64 gen) {
+  RleBitPackDecodeImpl<int64_t>(state, gen);
+}
+
+// ----------------------------------------------------------------------
+// ByteStreamSplit + Codec (ZSTD or LZ4)
+
+template <typename T>
+static void BssCodecEncodeImpl(benchmark::State& state, GenT<T> gen,
+                               Compression::type codec_type) {
+  using PType = typename PqTraits<T>::PType;
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  auto descr = MakeDescriptor<T>();
+  auto encoder = MakeTypedEncoder<PType>(Encoding::BYTE_STREAM_SPLIT,
+                                         /*use_dictionary=*/false, descr.get());
+  auto codec = *Codec::Create(codec_type);
+
+  encoder->Put(values.data(), static_cast<int>(num_values));
+  auto encoded_buf = encoder->FlushValues();
+  int64_t encoded_size = encoded_buf->size();
+
+  int64_t max_comp = codec->MaxCompressedLen(encoded_size, encoded_buf->data());
+  std::vector<uint8_t> compressed(max_comp);
+
+  // Compute comp_size once for the counter
+  int64_t comp_size =
+      *codec->Compress(encoded_size, encoded_buf->data(), max_comp, compressed.data());
+
+  for (auto _ : state) {
+    encoder->Put(values.data(), static_cast<int>(num_values));
+    auto buf = encoder->FlushValues();
+    auto sz = *codec->Compress(buf->size(), buf->data(), max_comp, compressed.data());
+    benchmark::DoNotOptimize(sz);
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+
+template <typename T>
+static void BssCodecDecodeImpl(benchmark::State& state, GenT<T> gen,
+                               Compression::type codec_type) {
+  using PType = typename PqTraits<T>::PType;
+  const int64_t num_values = state.range(0);
+  auto values = gen(num_values);
+  const int64_t uncompressed_size = num_values * sizeof(T);
+
+  auto descr = MakeDescriptor<T>();
+  auto encoder = MakeTypedEncoder<PType>(Encoding::BYTE_STREAM_SPLIT,
+                                         /*use_dictionary=*/false, descr.get());
+  auto codec = *Codec::Create(codec_type);
+
+  encoder->Put(values.data(), static_cast<int>(num_values));
+  auto encoded_buf = encoder->FlushValues();
+  int64_t encoded_size = encoded_buf->size();
+
+  int64_t max_comp = codec->MaxCompressedLen(encoded_size, encoded_buf->data());
+  std::vector<uint8_t> compressed(max_comp);
+  int64_t comp_size =
+      *codec->Compress(encoded_size, encoded_buf->data(), max_comp, compressed.data());
+
+  std::vector<uint8_t> decompressed(encoded_size);
+  std::vector<T> decoded(num_values);
+  auto decoder = MakeTypedDecoder<PType>(Encoding::BYTE_STREAM_SPLIT, descr.get());
+
+  for (auto _ : state) {
+    auto result = codec->Decompress(comp_size, compressed.data(), encoded_size,
+                                    decompressed.data());
+    ARROW_CHECK_OK(result.status());
+    decoder->SetData(static_cast<int>(num_values), decompressed.data(),
+                     static_cast<int>(encoded_size));
+    decoder->Decode(decoded.data(), static_cast<int>(num_values));
+    benchmark::ClobberMemory();
+  }
+
+  state.SetBytesProcessed(state.iterations() * uncompressed_size);
+  state.SetItemsProcessed(state.iterations() * num_values);
+  state.counters["compression_ratio"] =
+      static_cast<double>(uncompressed_size) / static_cast<double>(comp_size);
+}
+
+// Wrappers for BSS+ZSTD
+static void BM_BssZstdEncode(benchmark::State& state, Gen32 gen) {
+  BssCodecEncodeImpl<int32_t>(state, gen, Compression::ZSTD);
+}
+static void BM_BssZstd64Encode(benchmark::State& state, Gen64 gen) {
+  BssCodecEncodeImpl<int64_t>(state, gen, Compression::ZSTD);
+}
+static void BM_BssZstdDecode(benchmark::State& state, Gen32 gen) {
+  BssCodecDecodeImpl<int32_t>(state, gen, Compression::ZSTD);
+}
+static void BM_BssZstd64Decode(benchmark::State& state, Gen64 gen) {
+  BssCodecDecodeImpl<int64_t>(state, gen, Compression::ZSTD);
+}
+
+// Wrappers for BSS+LZ4
+static void BM_BssLz4Encode(benchmark::State& state, Gen32 gen) {
+  BssCodecEncodeImpl<int32_t>(state, gen, Compression::LZ4_FRAME);
+}
+static void BM_BssLz464Encode(benchmark::State& state, Gen64 gen) {
+  BssCodecEncodeImpl<int64_t>(state, gen, Compression::LZ4_FRAME);
+}
+static void BM_BssLz4Decode(benchmark::State& state, Gen32 gen) {
+  BssCodecDecodeImpl<int32_t>(state, gen, Compression::LZ4_FRAME);
+}
+static void BM_BssLz464Decode(benchmark::State& state, Gen64 gen) {
+  BssCodecDecodeImpl<int64_t>(state, gen, Compression::LZ4_FRAME);
+}
+
+// ----------------------------------------------------------------------
+// Benchmark Registration
+
+static void CustomArgs(benchmark::internal::Benchmark* b) { b->Arg(102400); }
+
+// Macro to register all algorithms for a given dataset
+#define REGISTER_DATASET(Name, GenFunc)                                        \
+  BENCHMARK_CAPTURE(BM_PforEncode, Name, &GenFunc)->Apply(CustomArgs);         \
+  BENCHMARK_CAPTURE(BM_PforDecode, Name, &GenFunc)->Apply(CustomArgs);         \
+  BENCHMARK_CAPTURE(BM_DeltaBitPackEncode, Name, &GenFunc)->Apply(CustomArgs); \
+  BENCHMARK_CAPTURE(BM_DeltaBitPackDecode, Name, &GenFunc)->Apply(CustomArgs); \
+  BENCHMARK_CAPTURE(BM_PlainZstdEncode, Name, &GenFunc)->Apply(CustomArgs);    \
+  BENCHMARK_CAPTURE(BM_PlainZstdDecode, Name, &GenFunc)->Apply(CustomArgs);    \
+  BENCHMARK_CAPTURE(BM_PlainLz4Encode, Name, &GenFunc)->Apply(CustomArgs);     \
+  BENCHMARK_CAPTURE(BM_PlainLz4Decode, Name, &GenFunc)->Apply(CustomArgs);     \
+  BENCHMARK_CAPTURE(BM_RleBitPackEncode, Name, &GenFunc)->Apply(CustomArgs);   \
+  BENCHMARK_CAPTURE(BM_RleBitPackDecode, Name, &GenFunc)->Apply(CustomArgs);   \
+  BENCHMARK_CAPTURE(BM_BssZstdEncode, Name, &GenFunc)->Apply(CustomArgs);      \
+  BENCHMARK_CAPTURE(BM_BssZstdDecode, Name, &GenFunc)->Apply(CustomArgs);      \
+  BENCHMARK_CAPTURE(BM_BssLz4Encode, Name, &GenFunc)->Apply(CustomArgs);       \
+  BENCHMARK_CAPTURE(BM_BssLz4Decode, Name, &GenFunc)->Apply(CustomArgs);
+
+// Same as REGISTER_DATASET but for int64 (BIGINT) columns; benchmark names get
+// the "64" codec suffix (e.g. BM_Pfor64Encode) to distinguish them.
+#define REGISTER_DATASET64(Name, GenFunc)                                        \
+  BENCHMARK_CAPTURE(BM_Pfor64Encode, Name, &GenFunc)->Apply(CustomArgs);         \
+  BENCHMARK_CAPTURE(BM_Pfor64Decode, Name, &GenFunc)->Apply(CustomArgs);         \
+  BENCHMARK_CAPTURE(BM_DeltaBitPack64Encode, Name, &GenFunc)->Apply(CustomArgs); \
+  BENCHMARK_CAPTURE(BM_DeltaBitPack64Decode, Name, &GenFunc)->Apply(CustomArgs); \
+  BENCHMARK_CAPTURE(BM_PlainZstd64Encode, Name, &GenFunc)->Apply(CustomArgs);    \
+  BENCHMARK_CAPTURE(BM_PlainZstd64Decode, Name, &GenFunc)->Apply(CustomArgs);    \
+  BENCHMARK_CAPTURE(BM_PlainLz464Encode, Name, &GenFunc)->Apply(CustomArgs);     \
+  BENCHMARK_CAPTURE(BM_PlainLz464Decode, Name, &GenFunc)->Apply(CustomArgs);     \
+  BENCHMARK_CAPTURE(BM_RleBitPack64Encode, Name, &GenFunc)->Apply(CustomArgs);   \
+  BENCHMARK_CAPTURE(BM_RleBitPack64Decode, Name, &GenFunc)->Apply(CustomArgs);   \
+  BENCHMARK_CAPTURE(BM_BssZstd64Encode, Name, &GenFunc)->Apply(CustomArgs);      \
+  BENCHMARK_CAPTURE(BM_BssZstd64Decode, Name, &GenFunc)->Apply(CustomArgs);      \
+  BENCHMARK_CAPTURE(BM_BssLz464Encode, Name, &GenFunc)->Apply(CustomArgs);       \
+  BENCHMARK_CAPTURE(BM_BssLz464Decode, Name, &GenFunc)->Apply(CustomArgs);
+
+// ClickBench datasets
+REGISTER_DATASET(ClientIP, GenClientIP)
+REGISTER_DATASET(UrlRegionID, GenUrlRegionID)
+REGISTER_DATASET(CounterID, GenCounterID)
+REGISTER_DATASET(EventDate, GenEventDate)
+REGISTER_DATASET(EventTime, GenEventTime)
+REGISTER_DATASET(GoodEvent, GenGoodEvent)
+REGISTER_DATASET(HID, GenHID)
+REGISTER_DATASET(HitColor, GenHitColor)
+REGISTER_DATASET(IPNetworkID, GenIPNetworkID)
+REGISTER_DATASET(JavaEnable, GenJavaEnable)
+REGISTER_DATASET(OS, GenOS)
+REGISTER_DATASET(Resolution, GenResolution)
+REGISTER_DATASET(TrafficSourceID, GenTrafficSourceID)
+REGISTER_DATASET(UserAgent, GenUserAgent)
+
+// TPC-DS datasets
+REGISTER_DATASET(TpcdsSoldDateSk, GenTpcdsSoldDateSk)
+REGISTER_DATASET(TpcdsStoreSk, GenTpcdsStoreSk)
+REGISTER_DATASET(TpcdsItemSk, GenTpcdsItemSk)
+REGISTER_DATASET(TpcdsQuantity, GenTpcdsQuantity)
+REGISTER_DATASET(TpcdsCustomerSk, GenTpcdsCustomerSk)
+REGISTER_DATASET(TpcdsExtSalesPrice, GenTpcdsExtSalesPrice)
+REGISTER_DATASET(TpcdsNetProfit, GenTpcdsNetProfit)
+REGISTER_DATASET(TpcdsDYear, GenTpcdsDYear)
+// TPC-H datasets
+REGISTER_DATASET(TpchLQuantity, GenTpchLQuantity)
+REGISTER_DATASET(TpchLExtendedPrice, GenTpchLExtendedPrice)
+REGISTER_DATASET(TpchLDiscount, GenTpchLDiscount)
+REGISTER_DATASET(TpchLShipDate, GenTpchLShipDate)
+// NYC taxi datasets
+REGISTER_DATASET(TaxiPickupUnixTime, GenTaxiPickupUnixTime)
+REGISTER_DATASET(TaxiTripDistanceX100, GenTaxiTripDistanceX100)
+REGISTER_DATASET(TaxiFareCents, GenTaxiFareCents)
+// int64 / BIGINT datasets (8-byte signed values)
+REGISTER_DATASET64(TsNanos, GenTsNanos)
+REGISTER_DATASET64(OrderKey, GenOrderKey)
+REGISTER_DATASET64(PriceMicros, GenPriceMicros)
+REGISTER_DATASET64(SnowflakeId, GenSnowflakeId)
+REGISTER_DATASET64(ByteCount, GenByteCount)
+
+}  // namespace
+}  // namespace parquet

From 8cdfb528207dd8fd180569c52968c41d02550869 Mon Sep 17 00:00:00 2001
From: Prateek Gaur <prateek.gaur@snowflake.com>
Date: Sat, 3 Oct 2026 20:48:15 +0000
Subject: [PATCH 5/6] Export PFOR templates from the Arrow library

PFOR codec definitions are built into libarrow but used by Parquet and its tests. Mark the instantiated template classes for export so shared builds do not depend on ELF default visibility.
---
 cpp/src/arrow/util/pfor/pfor_internal.h         | 3 ++-
 cpp/src/arrow/util/pfor/pfor_wrapper_internal.h | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/cpp/src/arrow/util/pfor/pfor_internal.h b/cpp/src/arrow/util/pfor/pfor_internal.h
index e766f144813f..b8c9ae63a45a 100644
--- a/cpp/src/arrow/util/pfor/pfor_internal.h
+++ b/cpp/src/arrow/util/pfor/pfor_internal.h
@@ -35,6 +35,7 @@
 #include "arrow/util/endian.h"
 #include "arrow/util/pfor/pfor_constants_internal.h"
 #include "arrow/util/ubsan.h"
+#include "arrow/util/visibility.h"
 
 namespace arrow {
 namespace util {
@@ -185,7 +186,7 @@ struct BitWidthResult {
 ///
 /// \tparam T the integer type (int32_t or int64_t)
 template <typename T>
-class PforCompression {
+class ARROW_EXPORT PforCompression {
  public:
   using UnsignedT = typename PforTypeTraits<T>::UnsignedType;
 
diff --git a/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h b/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h
index b438df1c7f35..02a422e3b62e 100644
--- a/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h
+++ b/cpp/src/arrow/util/pfor/pfor_wrapper_internal.h
@@ -28,6 +28,7 @@
 #include "arrow/result.h"
 #include "arrow/status.h"
 #include "arrow/util/pfor/pfor_internal.h"
+#include "arrow/util/visibility.h"
 
 namespace arrow {
 namespace util {
@@ -57,7 +58,7 @@ namespace pfor {
 ///
 /// \tparam T the integer type (int32_t or int64_t)
 template <typename T>
-class PforWrapper {
+class ARROW_EXPORT PforWrapper {
  public:
   /// A validated view of one encoded page.  It keeps no decoded values and can
   /// therefore serve arbitrary vectors without materializing the whole page.

From 687bdc8eb6ae8b262381547ca709bb24b7aa2771 Mon Sep 17 00:00:00 2001
From: Prateek Gaur <prateek.gaur@snowflake.com>
Date: Sat, 3 Oct 2026 20:48:15 +0000
Subject: [PATCH 6/6] Document PFOR encoding selection

List the supported integer types and Preview status, and make explicit that writers use PFOR only when a column selects it.
---
 docs/source/cpp/parquet.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/source/cpp/parquet.rst b/docs/source/cpp/parquet.rst
index 1aace68626c9..a6ef43f2c24e 100644
--- a/docs/source/cpp/parquet.rst
+++ b/docs/source/cpp/parquet.rst
@@ -407,6 +407,8 @@ Encodings
 +--------------------------+----------+----------+---------+
 | DELTA_LENGTH_BYTE_ARRAY  | ✓        | ✓        |         |
 +--------------------------+----------+----------+---------+
+| PFOR                     | ✓        | ✓        | \(3)    |
++--------------------------+----------+----------+---------+
 
 * \(1) Only supported for encoding definition and repetition levels,
   and boolean values.
@@ -414,6 +416,10 @@ Encodings
 * \(2) On the write path, RLE_DICTIONARY is only enabled if Parquet format version
   2.4 or greater is selected in :func:`WriterProperties::version`.
 
+* \(3) Only supported for INT32 and INT64 values. PFOR is a Preview feature in
+  the Parquet format, so other readers may not support it. It is never selected
+  automatically: a column uses PFOR only where ``encoding()`` names it.
+
 Types
 -----