feat: add capsule replay + repro minimizer flow\n\n- add capsule artifact replay path and reproducible invocation metadata\n- introduce repro minimization helpers and new regression coverage\n- tighten witness query/filter handling and refusal guidance\n- update docs and bump crate version to 0.3.0

Author: Zac

.beads/issues.jsonl

@@ -1,6 +1,6 @@
 [package]
 name = "rvl"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2024"
 authors = ["CMD+RVL <engineering@cmdrvl.com>"]
 description = "Reveal the smallest set of numeric changes that explain what actually changed."
@@ -20,10 +20,6 @@ csv = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 blake3 = "1"
-simd-csv = { version = "0.10.3", optional = true }
-
-[features]
-simd_csv = ["simd-csv"]
 
 [dev-dependencies]
 arrow-csv = "57.2.0"

Cargo.toml

@@ -281,6 +281,7 @@ rvl <old.csv> <new.csv> [OPTIONS]
 | `--threshold <float>` | float | `0.95` | Coverage target (0 < x ≤ 1.0). The minimum fraction of total numeric change that the top contributors must explain. |
 | `--tolerance <float>` | float | `1e-9` | Per-cell noise floor (x ≥ 0). Absolute deltas ≤ this value are treated as zero. |
 | `--delimiter <delim>` | string | *(auto-detect)* | Force CSV delimiter for both files. See [Delimiter](#delimiter). |
+| `--capsule-out <dir>` | string | *(disabled)* | Write deterministic replay capsule artifacts (`manifest.json`, `old.csv`, `new.csv`, `output.txt`, `replay.sh`) to `<dir>/capsule-<id>/`. |
 | `--json` | flag | `false` | Emit a single JSON object on stdout instead of human-readable output. |
 
 Invalid `--threshold` or `--tolerance` values are CLI argument errors (exit 2).
@@ -364,6 +365,31 @@ fi
 - **Refusals have next steps** — an agent can read `.refusal.code` and decide whether to retry with different flags or escalate
 - **`shape --describe`** — prints the tool's `operator.json` contract so an agent can discover invocation, flags, and exit codes without reading docs
 
+### Capsule replay workflow (agent swarms)
+
+Use capsules when you need a deterministic handoff between agents, CI jobs, or debugging sessions:
+
+```bash
+# 1. Produce the normal verdict and write a replay capsule sidecar
+rvl old.csv new.csv --key id --json --capsule-out ./capsules > run.json
+
+# 2. Inspect generated capsule
+ls ./capsules/capsule-*/
+# manifest.json old.csv new.csv output.txt replay.sh
+
+# 3. Re-run exactly from the capsule payload
+cd ./capsules/capsule-<id>
+./replay.sh > replay.json
+```
+
+`manifest.json` includes:
+- original invocation args (`key`, `threshold`, `tolerance`, `delimiter`, `json`)
+- outcome and refusal code (if any)
+- contributor summary for REAL_CHANGE
+- replay command plus artifact hashes for integrity checks
+
+For troubleshooting, compare `run.json` vs `replay.json` outcome/refusal code first; if they differ, the environment or binary changed.
+
 ---
 
 ## Scripting Examples

README.md

@@ -23,6 +23,13 @@ struct Case {
     path: PathBuf,
 }
 
+#[derive(Debug, Clone, Copy)]
+struct CaseDialect {
+    delimiter: u8,
+    escape: EscapeMode,
+    skip_sep: bool,
+}
+
 #[derive(Debug, Clone, Copy)]
 enum ParserKind {
     Csv,
@@ -80,17 +87,18 @@ fn run_case(
 ) -> Option<f64> {
     let bytes = std::fs::read(&case.path).ok()?;
     let input = guard_input_bytes(&bytes).ok()?;
+    let dialect = choose_dialect(input, forced_delimiter)?;
 
     let mut row_count = None;
     for _ in 0..warmup {
-        row_count = parse_count(input, &case.path, forced_delimiter, parser);
+        row_count = parse_count(input, &case.path, dialect, parser);
         row_count?;
     }
 
     let mut total = Duration::ZERO;
     for _ in 0..iterations {
         let start = Instant::now();
-        row_count = parse_count(input, &case.path, forced_delimiter, parser);
+        row_count = parse_count(input, &case.path, dialect, parser);
         row_count?;
         total += start.elapsed();
     }
@@ -118,26 +126,75 @@ fn run_case(
     Some(avg_ms)
 }
 
-fn parse_count(
+fn parse_count(input: &[u8], path: &Path, dialect: CaseDialect, parser: ParserKind) -> Option<u64> {
+    let rows = pipeline_data_row_count(input, dialect.delimiter, dialect.escape, dialect.skip_sep)?;
+
+    match parser {
+        ParserKind::Csv => {
+            parse_only_csv(input, dialect.delimiter, dialect.escape, dialect.skip_sep)
+        }
+        ParserKind::SimdCsv => {
+            parse_only_simd(input, dialect.delimiter, dialect.escape, dialect.skip_sep)
+        }
+        ParserKind::Arrow => {
+            parse_only_arrow(input, dialect.delimiter, dialect.escape, dialect.skip_sep)
+        }
+        ParserKind::Polars => parse_only_polars(
+            input,
+            path,
+            dialect.delimiter,
+            dialect.escape,
+            dialect.skip_sep,
+        ),
+    }?;
+
+    Some(rows)
+}
+
+fn pipeline_data_row_count(
     input: &[u8],
-    path: &Path,
-    forced_delimiter: Option<u8>,
-    parser: ParserKind,
+    delimiter: u8,
+    escape: EscapeMode,
+    skip_sep: bool,
 ) -> Option<u64> {
-    let (delimiter, escape, skip_sep) = choose_dialect(input, forced_delimiter)?;
+    let mut reader = build_reader(Cursor::new(input), delimiter, escape);
+    let mut record = CsvByteRecord::new();
+    let mut rows = 0u64;
+    let mut skipped_sep = !skip_sep;
+    let mut header_seen = false;
 
-    match parser {
-        ParserKind::Csv => parse_count_csv(input, delimiter, escape, skip_sep),
-        ParserKind::SimdCsv => parse_count_simd(input, delimiter, escape, skip_sep),
-        ParserKind::Arrow => parse_count_arrow(input, delimiter, escape, skip_sep),
-        ParserKind::Polars => parse_count_polars(input, path, delimiter, escape, skip_sep),
+    loop {
+        match reader.read_byte_record(&mut record) {
+            Ok(true) => {
+                if !header_seen {
+                    if record.len() == 1 && is_blank_record(&record) {
+                        continue;
+                    }
+                    if !skipped_sep {
+                        skipped_sep = true;
+                        continue;
+                    }
+                    header_seen = true;
+                    continue;
+                } else if is_blank_record(&record) {
+                    continue;
+                }
+                rows += 1;
+            }
+            Ok(false) => break,
+            Err(_) => return None,
+        }
     }
+
+    if !header_seen {
+        return None;
+    }
+    Some(rows)
 }
 
-fn parse_count_csv(input: &[u8], delimiter: u8, escape: EscapeMode, skip_sep: bool) -> Option<u64> {
+fn parse_only_csv(input: &[u8], delimiter: u8, escape: EscapeMode, skip_sep: bool) -> Option<()> {
     let mut reader = build_reader(Cursor::new(input), delimiter, escape);
     let mut record = CsvByteRecord::new();
-    let mut count = 0u64;
     let mut skipped_sep = !skip_sep;
     let mut pre_header = true;
 
@@ -153,25 +210,17 @@ fn parse_count_csv(input: &[u8], delimiter: u8, escape: EscapeMode, skip_sep: bo
                         continue;
                     }
                     pre_header = false;
-                } else if is_blank_record(&record) {
-                    continue;
                 }
-                count += 1;
             }
             Ok(false) => break,
             Err(_) => return None,
         }
     }
 
-    Some(count)
+    Some(())
 }
 
-fn parse_count_simd(
-    input: &[u8],
-    delimiter: u8,
-    escape: EscapeMode,
-    skip_sep: bool,
-) -> Option<u64> {
+fn parse_only_simd(input: &[u8], delimiter: u8, escape: EscapeMode, skip_sep: bool) -> Option<()> {
     if matches!(escape, EscapeMode::Backslash) {
         return None;
     }
@@ -183,7 +232,6 @@ fn parse_count_simd(
         .has_headers(false)
         .from_reader(Cursor::new(input));
     let mut record = SimdByteRecord::new();
-    let mut count = 0u64;
     let mut skipped_sep = !skip_sep;
     let mut pre_header = true;
 
@@ -199,25 +247,17 @@ fn parse_count_simd(
                         continue;
                     }
                     pre_header = false;
-                } else if is_blank_record_simd(&record) {
-                    continue;
                 }
-                count += 1;
             }
             Ok(false) => break,
             Err(_) => return None,
         }
     }
 
-    Some(count)
+    Some(())
 }
 
-fn parse_count_arrow(
-    input: &[u8],
-    delimiter: u8,
-    escape: EscapeMode,
-    skip_sep: bool,
-) -> Option<u64> {
+fn parse_only_arrow(input: &[u8], delimiter: u8, escape: EscapeMode, skip_sep: bool) -> Option<()> {
     let input = slice_after_preface(input, skip_sep);
     let header = read_header_record(input, delimiter, escape)?;
     let schema = schema_from_header(&header);
@@ -231,26 +271,24 @@ fn parse_count_arrow(
         builder = builder.with_escape(escape_byte);
     }
     let reader = builder.build(Cursor::new(input)).ok()?;
-    let mut count = 0u64;
     for batch in reader {
-        let batch = batch.ok()?;
-        count += batch.num_rows() as u64;
+        batch.ok()?;
     }
-    Some(count + 1)
+    Some(())
 }
 
-fn parse_count_polars(
+fn parse_only_polars(
     input: &[u8],
     path: &Path,
     delimiter: u8,
     escape: EscapeMode,
     skip_sep: bool,
-) -> Option<u64> {
+) -> Option<()> {
     if matches!(escape, EscapeMode::Backslash) {
         return None;
     }
 
-    let header = read_header_record(slice_after_preface(input, skip_sep), delimiter, escape)?;
+    read_header_record(slice_after_preface(input, skip_sep), delimiter, escape)?;
     let skip_lines = count_skip_lines(input, skip_sep);
     let parse_options = CsvParseOptions::default()
         .with_separator(delimiter)
@@ -262,11 +300,11 @@ fn parse_count_polars(
         .with_parse_options(parse_options)
         .try_into_reader_with_file_path(Some(path.to_path_buf()))
         .ok()?;
-    let df = reader.finish().ok()?;
-    Some(df.height() as u64 + header_count(&header))
+    reader.finish().ok()?;
+    Some(())
 }
 
-fn choose_dialect(input: &[u8], forced_delimiter: Option<u8>) -> Option<(u8, EscapeMode, bool)> {
+fn choose_dialect(input: &[u8], forced_delimiter: Option<u8>) -> Option<CaseDialect> {
     let mut skip_sep = false;
     let mut sep_delimiter = None;
     match scan_first_non_blank_line(input.split(|byte| *byte == b'\n')) {
@@ -280,17 +318,29 @@ fn choose_dialect(input: &[u8], forced_delimiter: Option<u8>) -> Option<(u8, Esc
     if let Some(forced) = forced_delimiter {
         let mut cursor = Cursor::new(input);
         let escape = detect_escape_mode(&mut cursor, forced).ok()?;
-        return Some((forced, escape, skip_sep));
+        return Some(CaseDialect {
+            delimiter: forced,
+            escape,
+            skip_sep,
+        });
     }
 
     if let Some(delimiter) = sep_delimiter {
         let mut cursor = Cursor::new(input);
         let escape = detect_escape_mode(&mut cursor, delimiter).ok()?;
-        return Some((delimiter, escape, skip_sep));
+        return Some(CaseDialect {
+            delimiter,
+            escape,
+            skip_sep,
+        });
     }
 
     let dialect = auto_detect(input).ok()?;
-    Some((dialect.delimiter, dialect.escape, false))
+    Some(CaseDialect {
+        delimiter: dialect.delimiter,
+        escape: dialect.escape,
+        skip_sep: false,
+    })
 }
 
 fn is_blank_record_simd(record: &SimdByteRecord) -> bool {
@@ -382,10 +432,6 @@ fn schema_from_header(header: &[Vec<u8>]) -> SchemaRef {
     Arc::new(Schema::new(fields))
 }
 
-fn header_count(header: &[Vec<u8>]) -> u64 {
-    if header.is_empty() { 0 } else { 1 }
-}
-
 fn default_inputs() -> Vec<PathBuf> {
     vec![
         PathBuf::from("tests/fixtures/corpus/basic_old.csv"),

benches/bakeoff.rs

@@ -81,6 +81,7 @@ fn run_case(case: &Case, iterations: u64, warmup: u64) -> f64 {
         threshold: 0.95,
         tolerance: 1e-9,
         delimiter: None,
+        capsule_out: None,
         json: false,
         no_witness: true,
         command: None,

benches/runtime.rs

@@ -81,10 +81,31 @@ Other knobs:
 | --- | --- | --- | --- |
 | csv (baseline) | Pass (`cargo test --test corpus_parse`) | 0 | Corpus parse/REFUSAL expectations matched. |
 | simd-csv 0.10.3 | Partial | 1 | Fails `backslash_escape.csv` (no backslash-escape support). |
-| arrow-csv 57.2.0 | TBD | TBD | TBD |
-| polars 0.52.0 | TBD | TBD | TBD |
+| arrow-csv 57.2.0 | Fail | 5 | Parse-ok regressions: `extra_fields_empty.csv`, `extra_trailing_empty_fields.csv`, `ragged_rows_long_empty.csv`, `wide_row_extra_empty.csv`; refusal mismatch: `duplicate_headers.csv` parsed successfully. |
+| polars 0.52.0 | Fail | 6 | Same 5 Arrow mismatches plus `backslash_escape.csv` parse failure (no backslash-escape support in harness path). |
 | candidate B | TBD | TBD | TBD |
 
+### Compatibility Sweep (2026-02-24)
+Corpus run command (single-iteration compatibility sweep):
+
+```bash
+inputs=$(printf "%s," tests/fixtures/corpus/*.csv | sed 's/,$//')
+RVL_BAKEOFF_PARSER=arrow  RVL_BAKEOFF_INPUTS="$inputs" RVL_BAKEOFF_ITERS=1 RVL_BAKEOFF_WARMUP=0 cargo bench --bench bakeoff > /tmp/rvl_bakeoff_arrow_corpus.txt
+RVL_BAKEOFF_PARSER=polars RVL_BAKEOFF_INPUTS="$inputs" RVL_BAKEOFF_ITERS=1 RVL_BAKEOFF_WARMUP=0 cargo bench --bench bakeoff > /tmp/rvl_bakeoff_polars_corpus.txt
+```
+
+Compared against expected parse/refusal sets in `tests/corpus_parse.rs`:
+- **Arrow mismatches (5):**
+  - Expected parse-ok but skipped: `extra_fields_empty.csv`, `extra_trailing_empty_fields.csv`, `ragged_rows_long_empty.csv`, `wide_row_extra_empty.csv`
+  - Expected refusal but parsed: `duplicate_headers.csv`
+- **Polars mismatches (6):**
+  - Expected parse-ok but skipped: `backslash_escape.csv`, `extra_fields_empty.csv`, `extra_trailing_empty_fields.csv`, `ragged_rows_long_empty.csv`, `wide_row_extra_empty.csv`
+  - Expected refusal but parsed: `duplicate_headers.csv`
+
+Note on forced-delimiter fixtures:
+- `control_byte_header.csv` and `delim_0x1f.csv` are parse-ok fixtures that require forced delimiter in the corpus spec.
+- Targeted runs with `RVL_BAKEOFF_DELIMITER=0x01` and `RVL_BAKEOFF_DELIMITER=0x1f` succeed for both Arrow and Polars, so these were excluded from mismatch counts.
+
 ### Throughput / Memory
 | Parser | Rows/sec | MB/sec | Peak RSS | Notes |
 | --- | --- | --- | --- | --- |
@@ -108,7 +129,8 @@ Note: the bakeoff harness is in-memory and does not include disk I/O.
 Baseline Rust `csv` passes the corpus (0 mismatches). simd-csv is ~18.9% faster
 in the parser-only bakeoff but skips backslash-escape cases in the harness and
 does not meet the >=25% throughput gate. Arrow and Polars are both slower than
-the baseline on the same large inputs. Keep Rust `csv` for v0.
+the baseline on the same large inputs and fail corpus compatibility checks.
+Keep Rust `csv` for v0.
 
 ## Next Steps
 - If needed, evaluate Arrow/Polars CSV readers and record results.