docs: investigation notes + reproducible benchmark

Investigation doc records the full arc: Wuffs audit, structural
rewrite, experiments tried/failed, real-world corpora results.

strategy_compare bench (zenbench): Classic vs Streaming across 8
workloads (random, palette, RLE, solid, photo-predicted; LSB + MSB
TIFF). Self-contained, no external files needed.

Run: cargo bench --bench strategy_compare

Author: lilith

Cargo.toml

@@ -24,6 +24,7 @@ features = ["std"]
 
 [dev-dependencies]
 criterion = "0.3.1"
+zenbench = "0.1.3"
 [dev-dependencies.tokio]
 version = "1"
 default-features = false
@@ -60,6 +61,11 @@ name = "msb8"
 harness = false
 required-features = ["std"]
 
+[[bench]]
+name = "strategy_compare"
+harness = false
+required-features = ["alloc"]
+
 [[example]]
 name = "lzw-compress"
 required-features = ["std"]
@@ -88,5 +94,9 @@ required-features = ["std"]
 name = "end_of_buffer"
 required-features = ["alloc"]
 
+[[test]]
+name = "streaming_parity"
+required-features = ["alloc"]
+
 [package.metadata.docs.rs]
 all-features = true

benches/strategy_compare.rs

@@ -0,0 +1,179 @@
+//! Benchmark comparing Classic vs Streaming decode strategies across
+//! workload types. Run with: `cargo bench --bench strategy_compare`
+//!
+//! Generates LZW data inline — no external corpus needed.
+
+use std::sync::Arc;
+use weezl::{
+    decode::{Configuration, TableStrategy},
+    encode::Encoder,
+    BitOrder, LzwStatus,
+};
+use zenbench::prelude::*;
+
+fn decode_all(
+    encoded: &[u8],
+    out: &mut [u8],
+    order: BitOrder,
+    tiff: bool,
+    strategy: TableStrategy,
+) -> usize {
+    let config = if tiff {
+        Configuration::with_tiff_size_switch(order, 8)
+    } else {
+        Configuration::new(order, 8)
+    };
+    let mut dec = config.with_table_strategy(strategy).build();
+    let mut inp = encoded;
+    let mut cursor = out;
+    let mut written = 0;
+    loop {
+        let r = dec.decode_bytes(inp, cursor);
+        inp = &inp[r.consumed_in..];
+        written += r.consumed_out;
+        cursor = &mut std::mem::take(&mut cursor)[r.consumed_out..];
+        match r.status {
+            Ok(LzwStatus::Done | LzwStatus::NoProgress) => return written,
+            Ok(LzwStatus::Ok) => {
+                if inp.is_empty() && cursor.is_empty() {
+                    return written;
+                }
+            }
+            Err(_) => return written,
+        }
+    }
+}
+
+// --- Data generators ---
+
+fn gen_random(len: usize, seed: u32) -> Vec<u8> {
+    let mut state = seed | 1;
+    (0..len)
+        .map(|_| {
+            state ^= state << 13;
+            state ^= state >> 17;
+            state ^= state << 5;
+            (state >> 8) as u8
+        })
+        .collect()
+}
+
+fn gen_palette16(len: usize) -> Vec<u8> {
+    (0..len).map(|i| (i % 16) as u8).collect()
+}
+
+fn gen_rle(len: usize) -> Vec<u8> {
+    let mut out = Vec::with_capacity(len);
+    let mut val = 0u8;
+    while out.len() < len {
+        let run = 32 + (val as usize % 33);
+        for _ in 0..run.min(len - out.len()) {
+            out.push(val);
+        }
+        val = val.wrapping_add(7);
+    }
+    out
+}
+
+fn gen_solid(len: usize) -> Vec<u8> {
+    vec![42u8; len]
+}
+
+fn gen_photo_predicted(len: usize) -> Vec<u8> {
+    let mut state = 0x12345678u32;
+    (0..len)
+        .map(|_| {
+            state ^= state << 13;
+            state ^= state >> 17;
+            state ^= state << 5;
+            let r = (state >> 8) as u8;
+            if r < 200 {
+                r & 0x0F
+            } else {
+                r
+            }
+        })
+        .collect()
+}
+
+struct Workload {
+    name: &'static str,
+    encoded: Arc<Vec<u8>>,
+    decoded_size: usize,
+    order: BitOrder,
+    tiff: bool,
+}
+
+fn make_workload(name: &'static str, data: &[u8], order: BitOrder, tiff: bool) -> Workload {
+    let encoded = if tiff {
+        Encoder::with_tiff_size_switch(order, 8)
+            .encode(data)
+            .unwrap()
+    } else {
+        Encoder::new(order, 8).encode(data).unwrap()
+    };
+    // Determine actual decoded size
+    let mut scratch = vec![0u8; data.len() + 4096];
+    let decoded_size = decode_all(&encoded, &mut scratch, order, tiff, TableStrategy::Classic);
+    Workload {
+        name,
+        encoded: Arc::new(encoded),
+        decoded_size,
+        order,
+        tiff,
+    }
+}
+
+fn bench_workload(g: &mut BenchGroup, w: &Workload) {
+    g.throughput(Throughput::Bytes(w.decoded_size as u64));
+    let out_cap = w.decoded_size + 4096;
+
+    for &(label, strategy) in &[
+        ("classic", TableStrategy::Classic),
+        ("streaming", TableStrategy::Streaming),
+    ] {
+        let enc = Arc::clone(&w.encoded);
+        let order = w.order;
+        let tiff = w.tiff;
+        g.bench(label, move |b| {
+            let enc = Arc::clone(&enc);
+            let mut out = vec![0u8; out_cap];
+            b.iter(move || {
+                let n = decode_all(&enc, &mut out, order, tiff, strategy);
+                black_box(&out[..n]);
+                n
+            });
+        });
+    }
+}
+
+fn bench_strategies(suite: &mut Suite) {
+    let size = 256 * 1024; // 256 KiB
+
+    let random = gen_random(size, 0xDEADBEEF);
+    let palette = gen_palette16(size);
+    let rle = gen_rle(size);
+    let solid = gen_solid(size);
+    let photo = gen_photo_predicted(size);
+
+    let workloads = vec![
+        // LSB (GIF-style)
+        make_workload("random", &random, BitOrder::Lsb, false),
+        make_workload("palette16", &palette, BitOrder::Lsb, false),
+        make_workload("rle", &rle, BitOrder::Lsb, false),
+        make_workload("solid", &solid, BitOrder::Lsb, false),
+        // MSB + TIFF (image-tiff style)
+        make_workload("random", &random, BitOrder::Msb, true),
+        make_workload("photo-pred", &photo, BitOrder::Msb, true),
+        make_workload("rle", &rle, BitOrder::Msb, true),
+        make_workload("solid", &solid, BitOrder::Msb, true),
+    ];
+
+    for w in &workloads {
+        let mode = if w.tiff { "msb-tiff" } else { "lsb" };
+        let group_name = format!("{}/{}", mode, w.name);
+        suite.group(group_name, |g| bench_workload(g, w));
+    }
+}
+
+zenbench::main!(bench_strategies);