feat(encoding): add Better compression level (zstd level 7, lazy2 strategy)

BENCHMARKS.md

@@ -35,8 +35,9 @@ encoder:
 
 - `structured-zstd::Fastest` vs `zstd` level `1`
 - `structured-zstd::Default` vs `zstd` level `3`
+- `structured-zstd::Better` vs `zstd` level `7`
 
-`Better` and `Best` are intentionally excluded until the encoder implements them.
+`Best` is intentionally excluded until the encoder implements it.
 
 Dictionary benchmarks are tracked separately with C FFI `with_dict` vs `without_dict` runs, using a
 dictionary trained from scenario samples. Pure Rust dictionary compression is still pending and is

README.md

@@ -22,7 +22,7 @@ This is a **maintained fork** of [KillingSpark/zstd-rs](https://github.com/Killi
 **Fork goals:**
 - Dictionary compression improvements (critical for per-label trained dictionaries in LSM-tree)
 - Performance parity with C zstd for decompression (currently 1.4-3.5x slower)
-- Additional compression levels (Default/Better/Best — currently only Fastest is implemented)
+- Additional compression levels (Best still pending — Fastest, Default, and Better are implemented)
 - No FFI — pure `cargo build`, no cmake/system libraries (ADR-013 compliance)
 
 **Upstream relationship:** We periodically sync with upstream but maintain an independent development trajectory focused on CoordiNode requirements.
@@ -44,7 +44,7 @@ Complete RFC 8878 implementation. Performance: ~1.4-3.5x slower than C zstd depe
 - [x] Uncompressed blocks
 - [x] Fastest (roughly level 1)
 - [x] Default (roughly level 3)
-- [ ] Better (roughly level 7)
+- [x] Better (roughly level 7)
 - [ ] Best (roughly level 11)
 - [x] Checksums
 - [x] Dictionary compression

cli/src/main.rs

@@ -40,14 +40,15 @@ enum Commands {
         /// - 0: Uncompressed
         /// - 1: Fastest
         /// - 2: Default
+        /// - 3: Better (lazy2, ~zstd level 7)
         ///
-        /// Streaming mode currently supports only levels 0..=2.
+        /// Streaming mode currently supports only levels 0..=3.
         #[arg(
             short,
             long,
             value_name = "COMPRESSION_LEVEL",
             default_value_t = 2,
-            value_parser = clap::value_parser!(u8).range(0..=2),
+            value_parser = clap::value_parser!(u8).range(0..=3),
             verbatim_doc_comment
         )]
         level: u8,
@@ -107,6 +108,7 @@ fn compress(input: PathBuf, output: PathBuf, level: u8) -> color_eyre::Result<()
         0 => CompressionLevel::Uncompressed,
         1 => CompressionLevel::Fastest,
         2 => CompressionLevel::Default,
+        3 => CompressionLevel::Better,
         _ => return Err(eyre!("unsupported compression level: {level}")),
     };
     ensure_distinct_paths(&input, &output)?;
@@ -400,7 +402,7 @@ mod tests {
 
     #[test]
     fn cli_rejects_unsupported_compression_level_at_parse_time() {
-        let parse = Cli::try_parse_from(["structured-zstd", "compress", "in.bin", "--level", "3"]);
+        let parse = Cli::try_parse_from(["structured-zstd", "compress", "in.bin", "--level", "4"]);
         assert!(parse.is_err());
     }
 

zstd/benches/support/mod.rs

@@ -70,7 +70,7 @@ pub(crate) fn benchmark_scenarios() -> Vec<Scenario> {
     scenarios
 }
 
-pub(crate) fn supported_levels() -> [LevelConfig; 2] {
+pub(crate) fn supported_levels() -> [LevelConfig; 3] {
     [
         LevelConfig {
             name: "fastest",
@@ -82,6 +82,11 @@ pub(crate) fn supported_levels() -> [LevelConfig; 2] {
             rust_level: CompressionLevel::Default,
             ffi_level: 3,
         },
+        LevelConfig {
+            name: "better",
+            rust_level: CompressionLevel::Better,
+            ffi_level: 7,
+        },
     ]
 }
 

zstd/src/encoding/frame_compressor.rs

@@ -277,10 +277,12 @@ impl<R: Read, W: Write, M: Matcher> FrameCompressor<R, W, M> {
                     header.serialize(output);
                     output.extend_from_slice(&uncompressed_data);
                 }
-                CompressionLevel::Fastest | CompressionLevel::Default => {
-                    // Default shares this fast block-encoding pipeline, but it
-                    // remains a distinct level via the matcher's dfast backend.
-                    compress_fastest(&mut self.state, last_block, uncompressed_data, output)
+                CompressionLevel::Fastest
+                | CompressionLevel::Default
+                | CompressionLevel::Better => {
+                    // All compressed levels share this block-encoding pipeline;
+                    // they differ only in the matcher backend and its parameters.
+                    compress_block_encoded(&mut self.state, last_block, uncompressed_data, output)
                 }
                 _ => {
                     unimplemented!();

zstd/src/encoding/levels/fastest.rs

@@ -6,7 +6,11 @@ use crate::{
 };
 use alloc::vec::Vec;
 
-/// Compresses a single block at [`crate::encoding::CompressionLevel::Fastest`].
+/// Compresses a single block using the shared compressed-block pipeline.
+///
+/// Used by all compressed levels (Fastest, Default, Better). The actual
+/// compression quality is determined by the matcher backend in `state`,
+/// not by this function.
 ///
 /// # Parameters
 /// - `state`: [`CompressState`] so the compressor can refer to data before
@@ -17,7 +21,7 @@ use alloc::vec::Vec;
 ///   larger input
 /// - `output`: As `uncompressed_data` is compressed, it's appended to `output`.
 #[inline]
-pub fn compress_fastest<M: Matcher>(
+pub fn compress_block_encoded<M: Matcher>(
     state: &mut CompressState<M>,
     last_block: bool,
     uncompressed_data: Vec<u8>,

zstd/src/encoding/levels/mod.rs

@@ -1,2 +1,2 @@
 mod fastest;
-pub use fastest::compress_fastest;
+pub use fastest::compress_block_encoded;