PivCoHuffman implementation

CMakeLists.txt

@@ -256,6 +256,15 @@ if (PIXIE_TESTS)
                 PRIVATE ${sdsl_lite_SOURCE_DIR}/include)
     endif ()
 
+    add_executable(pivco_huffman_tests
+            src/tests/pivco_huffman_tests.cpp)
+    target_include_directories(pivco_huffman_tests
+            PUBLIC include)
+    target_link_libraries(pivco_huffman_tests
+            gtest
+            gtest_main
+            ${PIXIE_DIAGNOSTICS_LIBS})
+
     set(PIXIE_TEST_TARGETS
             bit_algorithms_unittests
             rank_select_unittests
@@ -267,7 +276,8 @@ if (PIXIE_TESTS)
             storage_tests
             excess_positions_tests
             excess_record_lows_tests
-            rmq_tests)
+            rmq_tests
+            pivco_huffman_tests)
     foreach (test_target IN LISTS PIXIE_TEST_TARGETS)
         gtest_discover_tests(${test_target}
                 DISCOVERY_MODE PRE_TEST
@@ -399,6 +409,15 @@ if (PIXIE_BENCHMARKS)
             benchmark
             benchmark_main
             ${PIXIE_DIAGNOSTICS_LIBS})
+
+    add_executable(pivco_huffman_benchmarks
+            src/benchmarks/pivco_huffman_benchmarks.cpp)
+    target_include_directories(pivco_huffman_benchmarks
+            PUBLIC include)
+    target_link_libraries(pivco_huffman_benchmarks
+            benchmark
+            benchmark_main
+            ${PIXIE_DIAGNOSTICS_LIBS})
 endif ()
 
 # ---------------------------------------------------------------------------

include/pixie/huffman.h

@@ -0,0 +1,89 @@
+#pragma once
+
+/**
+ * @file huffman.h
+ * @brief Common CRTP contract for Huffman entropy codecs.
+ *
+ * PivCo-Huffman ("Pivot-Coded Huffman") reuses the wavelet-tree "tree of
+ * bitmaps" layout to turn sequential, bit-by-bit Huffman-tree traversals into
+ * vectorizable operations. A codec encodes a byte sequence into a compressed
+ * stream by building a Huffman-shaped tree of per-node bitmaps, and decodes it
+ * back by traversing that tree. Concrete implementations live under
+ * `<pixie/huffman/implementations.h>`.
+ *
+ * @see Marcin Zukowski, "PivCo-Huffman", v1.0 (2026).
+ */
+
+#include <cstddef>
+#include <cstdint>
+#include <span>
+#include <vector>
+
+namespace pixie {
+
+/**
+ * @brief CRTP facade for Huffman entropy codecs.
+ *
+ * The contract is the source of truth for observable codec semantics. Each
+ * concrete implementation inherits `HuffmanBase<Impl>` and supplies the
+ * required `*_impl()` extension points. There is no virtual dispatch: the
+ * facade delegates statically through CRTP, mirroring the other Pixie families.
+ *
+ * Range and ownership conventions:
+ *  - Symbol sequences are zero-based byte streams (`symbol_type`).
+ *  - Compressed streams are byte-oriented views (`std::byte`).
+ *  - The caller keeps any non-owning view alive for the codec lifetime.
+ *
+ * @tparam Impl Concrete codec type implementing the `*_impl()` contract.
+ *
+ * @see `<pixie/huffman/implementations.h>` for the available concrete
+ *      implementations.
+ */
+template <class Impl>
+class HuffmanBase {
+ public:
+  /** @brief Symbol type handled by the codec: one byte per symbol. */
+  using symbol_type = std::uint8_t;
+
+  /**
+   * @brief Number of symbols in the original (uncompressed) stream.
+   * @return Logical uncompressed symbol count.
+   */
+  std::size_t uncompressed_size() const {
+    return impl().uncompressed_size_impl();
+  }
+
+  /**
+   * @brief Number of bytes in the compressed representation.
+   * @return Compressed stream size in bytes.
+   */
+  std::size_t compressed_size() const { return impl().compressed_size_impl(); }
+
+  /**
+   * @brief Check whether the codec holds no data.
+   * @return `true` when `uncompressed_size() == 0`.
+   */
+  bool empty() const { return uncompressed_size() == 0; }
+
+  /**
+   * @brief Read-only view of the compressed byte stream.
+   * @return Span over the serialized representation.
+   *
+   * @note The returned view is invalidated by codec destruction.
+   */
+  std::span<const std::byte> compressed_data() const {
+    return impl().compressed_data_impl();
+  }
+
+  /**
+   * @brief Reconstruct the original symbol sequence.
+   * @return Decoded symbols of length `uncompressed_size()`.
+   */
+  std::vector<symbol_type> decode() const { return impl().decode_impl(); }
+
+ private:
+  /** @brief Return this facade as its concrete CRTP implementation. */
+  const Impl& impl() const { return static_cast<const Impl&>(*this); }
+};
+
+}  // namespace pixie

include/pixie/huffman/implementations.h

@@ -0,0 +1,12 @@
+#pragma once
+
+/**
+ * @file implementations.h
+ * @brief All Huffman codec implementations provided by Pixie.
+ *
+ * - `PivCoHuffman`: simple scalar reference codec storing a Huffman-shaped
+ *   tree of per-node routing bitmaps as packed 64-bit words.
+ */
+
+#include <pixie/huffman.h>
+#include <pixie/huffman/pivco_huffman.h>