refactor(search): strip experimental scaffolding, tighten public API

Reduce the search PR to its shippable surface and make the public docs
match behaviour:

- Remove research/experiment scaffolding: the #[ignore]d experiment tests
  in src/search/mod.rs (LPM reachability, DFA dumps, first_codes
  distribution, inner-range probes), docs/SEARCH_OPTIMIZATION.md, the C++
  search_bench harness (cpp-bench/search_bench.cpp + its CMake target),
  the bench's ONPAIR_SEARCH_DUMP / TPC-H parquet-dump utilities, and the
  now-dead #[cfg(test)] debug methods on KmpAutomaton (step_from,
  boundary_state_counts, dump_dfa).
- Document SearchParts as a caller-validated view (like Parts): its public
  fields are unchecked, and search indexes codes by code_offsets without
  revalidating.
- Fix the Column::first_codes doc: Parser::parse always populates it; the
  Option exists for columns rehydrated from storage that did not persist
  it (prefix search then falls back to the per-row scan).

Public API is unchanged (Pattern, RowMask, SearchParts,
Column::as_search_parts). All lib tests pass; clippy is clean on all
targets.

Author: claude

benches/search.rs

@@ -676,59 +676,11 @@ fn first_code_per_row(bencher: Bencher) {
         });
 }
 
-/// Dump the corpus and selected needles as length-prefixed little-endian
-/// binary so the C++ harness (`search_bench.cpp`) searches byte-identical
-/// inputs. Triggered by `ONPAIR_SEARCH_DUMP=<dir>`.
-///
-/// `corpus.bin`: `u64 n_rows`, then `n_rows × u32 row_len`, then the
-/// concatenated row bytes. `needles.bin`: `u32 count`, then per needle
-/// `u8 mode (0=contains,1=prefix)`, `u8 bucket_len` + bucket, `f64 sel`,
-/// `u32 len` + needle bytes.
-fn dump_for_cpp(dir: &str) {
-    use std::io::Write;
-
-    let rows = &corpus().rows;
-    let mut cf = std::io::BufWriter::new(File::create(format!("{dir}/corpus.bin")).unwrap());
-    cf.write_all(&(rows.len() as u64).to_le_bytes()).unwrap();
-    for r in rows {
-        cf.write_all(&(r.len() as u32).to_le_bytes()).unwrap();
-    }
-    for r in rows {
-        cf.write_all(r).unwrap();
-    }
-    cf.flush().unwrap();
-
-    let needles = select_needles();
-    let mut nf = std::io::BufWriter::new(File::create(format!("{dir}/needles.bin")).unwrap());
-    nf.write_all(&(needles.len() as u32).to_le_bytes()).unwrap();
-    for n in needles {
-        let mode: u8 = match n.mode {
-            Mode::Contains => 0,
-            Mode::Prefix => 1,
-        };
-        nf.write_all(&[mode]).unwrap();
-        nf.write_all(&[n.bucket.len() as u8]).unwrap();
-        nf.write_all(n.bucket.as_bytes()).unwrap();
-        nf.write_all(&n.selectivity.to_le_bytes()).unwrap();
-        nf.write_all(&(n.bytes.len() as u32).to_le_bytes()).unwrap();
-        nf.write_all(&n.bytes).unwrap();
-    }
-    nf.flush().unwrap();
-    eprintln!(
-        "[onpair search] dumped {} rows + {} needles to {dir}",
-        rows.len(),
-        needles.len()
-    );
-}
-
 fn main() {
     // Touch corpus, column, and needles so the report prints before divan runs,
     // and cross-check the compressed-domain count against brute force.
     let _ = column();
     let rows = &corpus().rows;
-    if let Ok(dir) = env::var("ONPAIR_SEARCH_DUMP") {
-        dump_for_cpp(&dir);
-    }
     eprintln!("[onpair search] selected needles (compressed-domain vs brute-force):");
     for n in select_needles() {
         let mode = match n.mode {

benches/tpch.rs

@@ -242,40 +242,7 @@ fn decompress_all(bencher: Bencher, param: (&'static str, u8)) {
         .bench(|| divan::black_box(decompress(column.as_parts())));
 }
 
-/// EXPERIMENT #10: dump a TPC-H string column to parquet so the search bench can
-/// run prefix/contains on it.
-/// `ONPAIR_TPCH_DUMP_COL=l_comment ONPAIR_TPCH_DUMP_PATH=/tmp/tpch_lc.parquet \
-///   ONPAIR_TPCH_DUMP_PATH=/tmp/tpch_lc.parquet cargo bench --bench tpch`
-fn tpch_dump_parquet() {
-    use arrow_array::{ArrayRef, RecordBatch, StringArray};
-    use parquet::arrow::arrow_writer::ArrowWriter;
-    use std::sync::Arc;
-    let col = env::var("ONPAIR_TPCH_DUMP_COL").unwrap_or_else(|_| "l_comment".into());
-    let path = env::var("ONPAIR_TPCH_DUMP_PATH").unwrap_or_else(|_| "/tmp/tpch.parquet".into());
-    let (bytes, offsets) = generate_column(&col, scale_factor(), max_bytes());
-    let strings: Vec<&str> = offsets
-        .windows(2)
-        .map(|w| std::str::from_utf8(&bytes[w[0] as usize..w[1] as usize]).unwrap_or(""))
-        .collect();
-    let arr: ArrayRef = Arc::new(StringArray::from(strings));
-    let batch = RecordBatch::try_from_iter([(col.as_str(), arr)]).unwrap();
-    let file = std::fs::File::create(&path).unwrap();
-    let mut w = ArrowWriter::try_new(file, batch.schema(), None).unwrap();
-    w.write(&batch).unwrap();
-    w.close().unwrap();
-    eprintln!(
-        "[tpch dump] wrote {} rows of {col} to {path}",
-        offsets.len() - 1
-    );
-}
-
 fn main() {
-    // Experiment #10: if ONPAIR_TPCH_DUMP_PATH is set, dump one TPC-H string
-    // column to parquet (for the search bench) and exit instead of benchmarking.
-    if env::var_os("ONPAIR_TPCH_DUMP_PATH").is_some() {
-        tpch_dump_parquet();
-        return;
-    }
     // Pre-warm every (col, bits) combo so the source + compression-ratio lines
     // print before divan starts emitting per-bench output.
     eprintln!("\n[onpair tpch bench] === corpora + compression ratios ===");

benchmarks/onpair-bench/README.md

@@ -89,28 +89,6 @@ uv sync --extra paper   # HuggingFace datasets only
 uv sync --extra full    # both
 ```
 
-## Compressed-domain search comparison
-
-`benches/search.rs` (Rust, divan) and `cpp-bench/search_bench.cpp` (C++)
-benchmark the same `Contains` / `Prefix` searches over the same corpus and
-needles. The Rust bench's pre-pass buckets needles by selectivity (rare /
-medium / common) and, when `ONPAIR_SEARCH_DUMP=<dir>` is set, dumps
-`corpus.bin` + `needles.bin` so the C++ harness searches byte-identical
-inputs. Both count matches via a callback and cross-check against brute force.
-
-```bash
-# Rust side (+ dump shared inputs). Defaults to a synthetic URL corpus;
-# point ONPAIR_BENCH_PARQUET at a parquet file for real data.
-mkdir -p /tmp/onpair_dump
-ONPAIR_SEARCH_DUMP=/tmp/onpair_dump cargo bench --bench search
-
-# C++ side, on the dumped inputs (needs the submodule + Boost.Unordered ≥ 1.81):
-cmake -S benchmarks/onpair-bench/cpp-bench -B benchmarks/onpair-bench/cpp-bench/build \
-      -DCMAKE_BUILD_TYPE=Release
-cmake --build benchmarks/onpair-bench/cpp-bench/build --target search_bench -j
-benchmarks/onpair-bench/cpp-bench/build/search_bench /tmp/onpair_dump --bits 16
-```
-
 ## Implementations
 
 - **Rust**: `rust-bench` is a separate workspace whose `Cargo.toml` carries a

benchmarks/onpair-bench/cpp-bench/CMakeLists.txt

@@ -28,10 +28,3 @@ target_compile_options(cpp_bench PRIVATE -O3 -DNDEBUG)
 if(COMMAND onpair_apply_configured_optimizations)
   onpair_apply_configured_optimizations(cpp_bench)
 endif()
-
-add_executable(search_bench search_bench.cpp)
-target_link_libraries(search_bench PRIVATE onpair)
-target_compile_options(search_bench PRIVATE -O3 -DNDEBUG)
-if(COMMAND onpair_apply_configured_optimizations)
-  onpair_apply_configured_optimizations(search_bench)
-endif()