dirsql 0.4.2__tar.gz → 0.4.4__tar.gz

{dirsql-0.4.2 → dirsql-0.4.4}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.2"
+version = "0.4.4"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.2 → dirsql-0.4.4}/Cargo.toml

@@ -22,6 +22,18 @@ thiserror = "2"
 tokio = { version = "1", features = ["rt", "sync"] }
 futures-channel = "0.3"
 
+# Cargo's default release profile ships every binary unstripped, without
+# cross-crate optimization. The three published artifacts (CLI bin, pyo3
+# extension, napi addon) are each a statically linked copy of the whole core,
+# so the defaults cost ~31% of every download (#717).
+#
+# `panic` stays at the default `unwind`: pyo3 and napi turn Rust panics into
+# Python/JS exceptions, which requires unwinding.
+[profile.release]
+strip = "symbols"
+lto = "fat"
+codegen-units = 1
+
 [workspace.lints.rust]
 unsafe_code = "forbid"
 rust_2018_idioms = { level = "warn", priority = -1 }

{dirsql-0.4.2 → dirsql-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.2
+Version: 0.4.4
 Requires-Dist: tomli>=2 ; python_full_version < '3.11'
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.2/packages/rust → dirsql-0.4.4}/docs/reference/hooks.md

@@ -86,7 +86,7 @@ What a failure *means* differs per hook:
 
 | Hook | On failure |
 |---|---|
-| `on-file` | **Per-file isolation.** The file contributes no rows; a one-line warning naming the file and error goes to stderr; the scan continues. One bad file never aborts the scan. |
+| `on-file` | **Per-file isolation.** The file contributes no rows and is reported as skipped; the scan indexes every other file and commits. The CLI names up to ten skipped files on stderr, then `... and N more`, and exits `23` — distinct from `0` (clean) and `1` (the run failed), so a caller can tell a partial index from a complete one. A row the table rejects under `strict` counts as the same kind of failure. |
 | `pre-query` | The request returns `500 Internal Server Error` with the command's stderr tail in the JSON `error` body. |
 | `post-query` | The request returns `500 Internal Server Error` with the command's stderr tail (or, for unparseable output, `post-query did not return valid JSON: <err>`) in the JSON `error` body. |
 

{dirsql-0.4.2 → dirsql-0.4.4}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.4.2"
+version = "0.4.4"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of

dirsql-0.4.4/packages/python/changelog.d/2026-08-02-release-profile.md

@@ -0,0 +1,5 @@
+**Changed** — the wheel's compiled artifacts are now stripped and built with
+fat LTO, shrinking the `_dirsql.abi3.so` extension ~28% (6.94 MB → 4.99 MB) and
+the bundled CLI binary ~33% (9.17 MB → 6.14 MB).
+
+Build-only: no API or behavior change.

{dirsql-0.4.2 → dirsql-0.4.4}/packages/python/docs/reference/hooks.md

@@ -86,7 +86,7 @@ What a failure *means* differs per hook:
 
 | Hook | On failure |
 |---|---|
-| `on-file` | **Per-file isolation.** The file contributes no rows; a one-line warning naming the file and error goes to stderr; the scan continues. One bad file never aborts the scan. |
+| `on-file` | **Per-file isolation.** The file contributes no rows and is reported as skipped; the scan indexes every other file and commits. The CLI names up to ten skipped files on stderr, then `... and N more`, and exits `23` — distinct from `0` (clean) and `1` (the run failed), so a caller can tell a partial index from a complete one. A row the table rejects under `strict` counts as the same kind of failure. |
 | `pre-query` | The request returns `500 Internal Server Error` with the command's stderr tail in the JSON `error` body. |
 | `post-query` | The request returns `500 Internal Server Error` with the command's stderr tail (or, for unparseable output, `post-query did not return valid JSON: <err>`) in the JSON `error` body. |
 

dirsql-0.4.4/packages/python/e2e-attestations/claude-714-unify-file-failures.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1785673957,
+  "exit_code": 0,
+  "commit": "484c89828d5a512f7fd51dc8e5995d498e857c0b",
+  "branch": "claude/714-unify-file-failures"
+}

dirsql-0.4.4/packages/rust/changelog.d/2026-08-02-per-file-scan-failures.md

@@ -0,0 +1,35 @@
+**Fixed**
+
+A file the scan cannot index no longer costs the files around it, and a partial
+index is now visible at the exit code instead of passing for a complete one
+(#714).
+
+Two failure modes behaved inconsistently. A hook that exited non-zero or emitted
+malformed output was already skipped — `run_on_file` logged it and returned an
+empty row set — but a row that failed **strict** normalization aborted the whole
+scan, so one bad column cost every other file's rows. Both are now the same
+thing: the file is skipped, the scan commits what it could index, and the
+failure is recorded.
+
+- `DirSQL::scan_failures()` returns the files the scan could not index, each
+  with its root-relative path and the hook's own message. Empty for a clean
+  scan.
+- The CLI reports skips on **stderr**, at most ten by name followed by
+  `... and N more`, and exits **23** — rsync's "partial transfer due to error" —
+  when any file was skipped. stdout still carries only the query result, so
+  `dirsql "SELECT …" | jq` keeps working and can now tell a partial index from a
+  complete one. A clean scan still exits `0`; a failed run still exits `1`.
+- `run_on_file` returns `Result` rather than logging and flattening to an empty
+  row set, so a skip and a file that legitimately produced no rows are no longer
+  indistinguishable.
+
+SQLite, DDL and extension errors are unchanged: they still abort the scan and
+roll back. Only per-file hook outcomes became recoverable.
+
+A skipped file never reaches the persistent file index, so it is retried on the
+next scan — the cache is incomplete, never wrong.
+
+**Removed**
+
+`DirSqlError::OnFile` and `DirSqlError::OnFileMany`. Nothing can produce them
+now that a per-file failure is not a scan error.

dirsql-0.4.4/packages/rust/changelog.d/2026-08-02-release-profile.md

@@ -0,0 +1,7 @@
+**Changed** — release builds now strip symbols, run fat LTO, and use a single
+codegen unit, so the published `dirsql` binary is ~33% smaller (linux-x64:
+9.17 MB → 6.14 MB; 3.49 MB → 2.80 MB gzipped).
+
+Build-only: no API, CLI or behavior change. `panic` stays at the default
+`unwind`, which the pyo3 and napi bindings need to turn Rust panics into
+Python/JS exceptions. Release build time rises ~2m10s → ~2m38s.

{dirsql-0.4.2 → dirsql-0.4.4/packages/rust}/docs/reference/hooks.md

@@ -86,7 +86,7 @@ What a failure *means* differs per hook:
 
 | Hook | On failure |
 |---|---|
-| `on-file` | **Per-file isolation.** The file contributes no rows; a one-line warning naming the file and error goes to stderr; the scan continues. One bad file never aborts the scan. |
+| `on-file` | **Per-file isolation.** The file contributes no rows and is reported as skipped; the scan indexes every other file and commits. The CLI names up to ten skipped files on stderr, then `... and N more`, and exits `23` — distinct from `0` (clean) and `1` (the run failed), so a caller can tell a partial index from a complete one. A row the table rejects under `strict` counts as the same kind of failure. |
 | `pre-query` | The request returns `500 Internal Server Error` with the command's stderr tail in the JSON `error` body. |
 | `post-query` | The request returns `500 Internal Server Error` with the command's stderr tail (or, for unparseable output, `post-query did not return valid JSON: <err>`) in the JSON `error` body. |
 

dirsql-0.4.4/packages/rust/migrations.d/2026-08-02-per-file-scan-failures.md

@@ -0,0 +1,100 @@
+## Summary
+
+A per-file failure during the initial scan is no longer fatal (#714). A hook
+that fails, or that returns a row the table rejects, costs that file alone: the
+scan indexes everything else, commits, and records the failure. Previously a
+strict-mode violation aborted the scan outright — one bad column cost every
+other file's rows — while a non-zero hook exit was already silently skipped. The
+two are now consistent.
+
+The visible consequence is an exit code. A run that skipped files exits **23**
+(rsync's "partial transfer due to error") instead of `0`, so a caller can tell a
+partial index from a complete one. That distinction did not exist before, which
+is why it is a breaking change for scripts rather than a pure improvement.
+
+## Required changes
+
+**`DirSqlError::OnFile` and `DirSqlError::OnFileMany` are removed.** Nothing can
+produce them now. An exhaustive `match` on `DirSqlError` drops those arms:
+
+```rust
+// before
+match err {
+    DirSqlError::OnFile { path, message } => report(path, message),
+    DirSqlError::OnFileMany { failures } => failures.iter().for_each(report_one),
+    other => return Err(other),
+}
+
+// after — the build no longer fails for this reason; ask the database instead
+let db = DirSQL::new(root, tables)?;
+for failure in db.scan_failures() {
+    report(&failure.path, &failure.message);
+}
+```
+
+**A script that treats any non-zero exit as failure now sees `23`.** If a
+partial index should be acceptable, accept it explicitly:
+
+```sh
+# before: relied on `dirsql` exiting 0 while quietly skipping files
+dirsql "SELECT * FROM docs" | jq .
+
+# after: accept a partial index, still failing on a real error
+dirsql "SELECT * FROM docs" | jq . || [ $? -eq 23 ]
+```
+
+Under `set -e` and *without* that guard, a scan with skipped files now stops the
+script — which is the point: it previously continued against a silently
+incomplete index.
+
+## Deprecations removed
+
+_None._
+
+## Behavior changes without code changes
+
+**A strict-mode violation skips its file instead of aborting the scan.** A
+`strict` table whose hook returns an unexpected or missing column used to fail
+the build; it now yields a skipped file and a built database containing every
+other file's rows. The rejected row is still never inserted, and the column name
+still never reaches SQL — only the blast radius changed.
+
+**Skipped files are reported by the CLI, capped.** At most ten are named on
+stderr, followed by `... and N more`. Previously `run_on_file` printed one line
+per failing file with no cap, and printed nothing at all for strict violations
+(they aborted instead). Paths in these lines are now root-relative, where the
+old `run_on_file` line printed the absolute path.
+
+**A library consumer no longer gets stderr noise from the core.** `run_on_file`
+returned `Vec<Row>` and logged its own failures; it now returns `Result` and the
+scan records them. Read `DirSQL::scan_failures()` instead of scraping stderr.
+
+**The persistent cache commits partially.** A scan with failures used to roll
+back entirely; it now commits the files that parsed. The failed file never
+reaches the file index, so the next scan treats it as unknown and retries it —
+the cache is incomplete, never wrong. A caller that relied on "a failed build
+leaves the cache untouched" no longer gets that.
+
+**Watch-mode gains an error event it did not emit.** With `run_on_file` now
+returning `Result`, a command hook that fails during live watching produces an
+`error` row event, where it previously produced silence.
+
+## Verification
+
+```sh
+# a directory with one good file and two whose on-file hook exits non-zero
+dirsql "SELECT name FROM items" -c .dirsql.toml; echo "EXIT=$?"
+```
+
+Expected: the good file's rows on stdout as JSON, one `dirsql: skipping …` line
+per failed file on stderr, and `EXIT=23`. Before this change the same command
+printed the rows and `EXIT=0`.
+
+```sh
+# a `strict = true` table where one file's hook emits an unexpected column
+dirsql "SELECT name FROM items" -c strict.toml; echo "EXIT=$?"
+```
+
+Expected: every well-formed file's rows on stdout, one skip line naming the bad
+file, and `EXIT=23`. Before this change: no rows at all, a
+`Schema mismatch: extra columns` error on stderr, and `EXIT=1`.

{dirsql-0.4.2 → dirsql-0.4.4}/packages/rust/src/bin/dirsql.rs

@@ -280,6 +280,7 @@ async fn run_query(args: QueryArgs) -> ExitCode {
         }
     };
     let state = load_state(&args.common, parser);
+    let skipped = report_scan_failures(&state);
     let pre_query = load_pre_queries(&args.common);
     let post_query = load_post_queries(&args.common);
     // Same default the server binds with; the pipeline enforces it.
@@ -296,7 +297,15 @@ async fn run_query(args: QueryArgs) -> ExitCode {
     {
         Ok(value) => {
             println!("{value}");
-            ExitCode::SUCCESS
+            // The query ran and its rows are on stdout, so this is not a
+            // failure -- but the index behind them is missing files, and a
+            // caller piping into `jq` under `set -e` has no other way to find
+            // that out.
+            if skipped {
+                ExitCode::from(PARTIAL_SCAN_EXIT)
+            } else {
+                ExitCode::SUCCESS
+            }
         }
         Err(failure) => {
             eprintln!("dirsql query: {}", failure.message());
@@ -305,6 +314,38 @@ async fn run_query(args: QueryArgs) -> ExitCode {
     }
 }
 
+/// Exit code for "the scan completed, but some files were skipped" -- distinct
+/// from `1` so a script can tell a partial index from a run that failed.
+/// Follows rsync's `23` ("partial transfer due to error").
+const PARTIAL_SCAN_EXIT: u8 = 23;
+
+/// How many skipped files to name before collapsing the rest into a count. A
+/// directory of unreadable files should not bury the terminal.
+const MAX_REPORTED_FAILURES: usize = 10;
+
+/// Print the scan's skipped files to stderr, capped, and report whether there
+/// were any. stdout is left for the query result alone.
+fn report_scan_failures(state: &AppState) -> bool {
+    let AppState::Ready(db) = state else {
+        return false;
+    };
+    let failures = db.scan_failures();
+    if failures.is_empty() {
+        return false;
+    }
+    for failure in failures.iter().take(MAX_REPORTED_FAILURES) {
+        eprintln!("dirsql: skipping `{}`: {}", failure.path, failure.message);
+    }
+    if let Some(rest) = failures
+        .len()
+        .checked_sub(MAX_REPORTED_FAILURES)
+        .filter(|n| *n > 0)
+    {
+        eprintln!("dirsql: ... and {rest} more");
+    }
+    true
+}
+
 /// Synthesize the exact `POST /query` body for a positional SQL argument,
 /// so the shared pipeline's intake validation and `pre-query` hook see
 /// byte-for-byte what an HTTP client would send.

{dirsql-0.4.2 → dirsql-0.4.4}/packages/rust/src/lib.rs

@@ -129,23 +129,6 @@ pub enum DirSqlError {
     #[error("duplicate table name: {0}")]
     DuplicateTable(String),
 
-    #[error("on-file error for {path}: {message}")]
-    OnFile { path: String, message: String },
-
-    /// Several files' on-file hooks failed during one scan. A scan attempts
-    /// every matched file, so more than one can fail; reporting only the first
-    /// would make the rest invisible until it was fixed and the scan re-run.
-    #[error(
-        "{} files failed their on-file hook:\n{}",
-        .failures.len(),
-        .failures
-            .iter()
-            .map(|OnFileFailure { path, message }| format!("  {path}: {message}"))
-            .collect::<Vec<_>>()
-            .join("\n")
-    )]
-    OnFileMany { failures: Vec<OnFileFailure> },
-
     #[error("config error: {message}")]
     Config {
         message: String,
@@ -273,6 +256,8 @@ struct DirSqlInner {
     matcher: TableMatcher,
     on_file_map: HashMap<String, Arc<OnFileFn>>,
     strict_map: HashMap<String, bool>,
+    /// Files the initial scan could not index. Empty for a clean scan.
+    scan_failures: Vec<OnFileFailure>,
     watcher: Mutex<Option<Watcher>>,
     /// Locks out [`DirSQL::watch`] once [`DirSQL::poll_events`] has run:
     /// both would drain the same underlying watcher.
@@ -735,6 +720,18 @@ impl DirSQL {
         })
     }
 
+    /// The files the initial scan could not index, in scan order — each with
+    /// the path relative to the root and the hook's own error.
+    ///
+    /// A hook that fails, or returns a row the table rejects, costs that file
+    /// and no other: the scan indexes everything else and records the failure
+    /// here. Empty for a clean scan, which is the signal a caller checks —
+    /// non-empty means the index is *incomplete*, not wrong, and the missing
+    /// files are retried on the next scan.
+    pub fn scan_failures(&self) -> &[OnFileFailure] {
+        &self.inner.scan_failures
+    }
+
     /// Split-phase construction — part 2. Consumes the intermediate state from
     /// [`prepare_resolved`](Self::prepare_resolved): creates the SQLite
     /// database (or wires up the persistent on-disk one), runs each table's
@@ -873,9 +870,29 @@ impl DirSQL {
                 db.delete_rows_by_file(&table_name, &rel_path)
                     .map_err(map_db_error)?;
             }
-            for (row_index, raw_row) in raw_rows.iter().enumerate() {
-                let row = db.normalize_row(&table_name, raw_row, strict)?;
-                db.insert_row(&table_name, &row, &rel_path, row_index)
+            // Normalize every row before inserting any: a row the hook got
+            // wrong is that file's failure, and half-inserting a file would
+            // leave rows behind for a file the scan reports as skipped.
+            let mut normalized = Vec::with_capacity(raw_rows.len());
+            let mut rejected = None;
+            for raw_row in &raw_rows {
+                match db.normalize_row(&table_name, raw_row, strict) {
+                    Ok(row) => normalized.push(row),
+                    Err(e) => {
+                        rejected = Some(e.to_string());
+                        break;
+                    }
+                }
+            }
+            if let Some(message) = rejected {
+                on_file_failures.push(OnFileFailure {
+                    path: rel_path.clone(),
+                    message,
+                });
+                continue;
+            }
+            for (row_index, row) in normalized.iter().enumerate() {
+                db.insert_row(&table_name, row, &rel_path, row_index)
                     .map_err(map_db_error)?;
             }
 
@@ -904,26 +921,12 @@ impl DirSQL {
             write_meta(db.conn(), meta).map_err(DirSqlError::sqlite)?;
         }
 
-        // Returning before the commit drops `_tx`, so a scan with failures
-        // still leaves the cache exactly as it was -- the pre-existing
-        // behavior. The single-failure case keeps its original error verbatim;
-        // only the multi-failure case reports more than it used to. Whether a
-        // partial index should commit instead is dirsql#697.
-        match on_file_failures.len() {
-            0 => {}
-            1 => {
-                let only = on_file_failures.remove(0);
-                return Err(DirSqlError::OnFile {
-                    path: only.path,
-                    message: only.message,
-                });
-            }
-            _ => {
-                return Err(DirSqlError::OnFileMany {
-                    failures: on_file_failures,
-                });
-            }
-        }
+        // A per-file failure no longer cancels the scan: what could be indexed
+        // is committed, and the failures ride on the built database for the
+        // caller to report (`scan_failures`). A file that failed never reached
+        // `upsert_file`, so it is absent from the cache index and is retried on
+        // the next scan -- the cache is incomplete, never wrong. SQLite, DDL
+        // and extension errors still propagate above, unchanged.
 
         // Commit the ingest transaction.
         _tx.commit().map_err(DirSqlError::sqlite)?;
@@ -940,6 +943,7 @@ impl DirSQL {
                 matcher,
                 on_file_map,
                 strict_map,
+                scan_failures: on_file_failures,
                 watcher: Mutex::new(None),
                 poll_used: AtomicBool::new(false),
                 watch_thread_started: AtomicBool::new(false),
@@ -1548,10 +1552,9 @@ fn build_tables_from_config(
         let command = table_cfg.on_file.clone();
         let config_dir = config_dir.to_path_buf();
         let root = root.to_path_buf();
-        // `Table::new` (infallible): `run_on_file` isolates its own errors to an
-        // empty row set so one bad file never aborts the scan (the scan aborts
-        // on an on_file `Err`).
-        let mut table = Table::new(
+        // `Table::try_new`: a hook failure is the scan's to record, not this
+        // closure's to hide. The scan skips the file and reports it.
+        let mut table = Table::try_new(
             table_cfg.ddl.clone(),
             table_cfg.glob.clone(),
             move |abs_path: &str| run_on_file(&command, abs_path, &config_dir, &root, timeout),
@@ -1575,38 +1578,33 @@ fn build_tables_from_config(
 /// config lives outside the index still resolves it. A template that omits a
 /// placeholder simply never receives its value — nothing is appended.
 ///
-/// Per-file isolation: any failure — a spawn/exit/timeout error from
-/// [`command::run_command`], or output that is not a JSON array of objects —
-/// is logged to stderr and yields no rows (`vec![]`). Returning `Err` here
-/// would abort the whole scan, so it never does. `timeout` bounds the run —
-/// the table's configured value, or the shared default.
+/// Any failure — a spawn/exit/timeout error from [`command::run_command`], or
+/// output that is not a JSON array of objects — is returned to the caller. The
+/// scan turns it into a skipped file rather than a scan error, and needs the
+/// `Err` to tell a skip apart from a file that legitimately produced no rows.
+/// `timeout` bounds the run — the table's configured value, or the shared
+/// default.
 fn run_on_file(
     command: &str,
     abs_path: &str,
     config_dir: &Path,
     root: &Path,
     timeout: Duration,
-) -> Vec<Row> {
+) -> std::result::Result<Vec<Row>, BoxError> {
     let placeholders = [
         Placeholder::new("path", abs_path),
         Placeholder::new("root", root.to_string_lossy().into_owned()),
     ];
 
-    match command::run_command(command, &placeholders, config_dir, timeout, None) {
-        Ok(output) => match parse_command_rows(&output.payload) {
-            Ok(rows) => rows,
-            Err(message) => {
-                eprintln!(
-                    "dirsql: skipping `{abs_path}`: on-file output was not a JSON array of rows: {message}"
-                );
-                Vec::new()
-            }
-        },
-        Err(error) => {
-            eprintln!("dirsql: skipping `{abs_path}`: on-file command failed: {error}");
-            Vec::new()
-        }
-    }
+    // Errors travel to the caller rather than being logged and flattened to an
+    // empty row set here. Swallowing them made a skip indistinguishable from a
+    // file that legitimately produced no rows, so the scan could not count what
+    // it dropped, cap the report, or exit differently.
+    let output = command::run_command(command, &placeholders, config_dir, timeout, None)
+        .map_err(|error| -> BoxError { format!("on-file command failed: {error}").into() })?;
+    parse_command_rows(&output.payload).map_err(|message| -> BoxError {
+        format!("on-file output was not a JSON array of rows: {message}").into()
+    })
 }
 
 /// Parse an `on-file` command's stdout payload — a JSON array of row objects —
@@ -3206,7 +3204,8 @@ mod internal_tests {
             dir.path(),
             dir.path(),
             command::DEFAULT_COMMAND_TIMEOUT,
-        );
+        )
+        .expect("a well-formed payload parses");
         assert_eq!(rows.len(), 1);
         assert_eq!(rows[0]["n"], Value::Integer(1));
     }
@@ -3225,7 +3224,8 @@ mod internal_tests {
             dir.path(),
             dir.path(),
             command::DEFAULT_COMMAND_TIMEOUT,
-        );
+        )
+        .expect("a well-formed payload parses");
         assert_eq!(rows.len(), 1);
         assert_eq!(rows[0]["q"], Value::Text("{abspath}".into()));
     }
@@ -3245,7 +3245,8 @@ mod internal_tests {
             dir.path(),
             dir.path(),
             command::DEFAULT_COMMAND_TIMEOUT,
-        );
+        )
+        .expect("a well-formed payload parses");
         assert_eq!(rows.len(), 1);
         assert_eq!(
             rows[0]["p"],
@@ -3253,31 +3254,41 @@ mod internal_tests {
         );
     }
 
-    /// A command that cannot be spawned yields no rows (per-file isolation).
+    /// A command that cannot be spawned is an error the caller records, not an
+    /// empty row set: a skip and a file that legitimately produced no rows must
+    /// stay distinguishable.
     #[test]
-    fn run_on_file_returns_no_rows_on_spawn_failure() {
+    fn run_on_file_errors_on_spawn_failure() {
         let dir = TempDir::new().unwrap();
-        let rows = run_on_file(
+        let error = run_on_file(
             "definitely-not-a-real-binary-xyzzy",
             "/outside/f.txt",
             dir.path(),
             dir.path(),
             command::DEFAULT_COMMAND_TIMEOUT,
+        )
+        .expect_err("an unspawnable command is a failure");
+        assert!(
+            error.to_string().contains("on-file command failed"),
+            "the error names the stage: {error}"
         );
-        assert!(rows.is_empty());
     }
 
     #[test]
-    fn run_on_file_returns_no_rows_on_non_json_output() {
+    fn run_on_file_errors_on_non_json_output() {
         let dir = TempDir::new().unwrap();
-        let rows = run_on_file(
+        let error = run_on_file(
             "echo not-json",
             "/outside/f.txt",
             dir.path(),
             dir.path(),
             command::DEFAULT_COMMAND_TIMEOUT,
+        )
+        .expect_err("a non-JSON payload is a failure");
+        assert!(
+            error.to_string().contains("not a JSON array of rows"),
+            "the error names the stage: {error}"
         );
-        assert!(rows.is_empty());
     }
 
     #[tokio::test]