fix: show key value in refusals and add verdict line

In key mode, refusal examples now show the key value (e.g., key "B")
instead of a record number. All refusal bodies now begin with "Cannot
produce a verdict." so the output is self-contained even without the
RVL ERROR banner.

Closes #8, closes #9

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: saltmachine

src/numeric/missingness.rs

@@ -17,6 +17,7 @@ pub fn build_missingness_refusal(
         record: error.row_id,
         column: error.column,
         value: error.present_value,
+        key_value: None,
     };
     RefusalDetail::with_default_next(kind, paths)
 }

src/orchestrator.rs

@@ -85,6 +85,7 @@ struct RefusalContext<'a> {
 struct RowRef {
     old_record: u64,
     new_record: u64,
+    key: Option<Vec<u8>>,
 }
 
 impl RowRef {
@@ -389,6 +390,7 @@ fn run_diff(
                     RowRef {
                         old_record: row.old.record_number,
                         new_record: row.new.record_number,
+                        key: Some(row.key.clone()),
                     },
                     row.old.fields.as_slice(),
                     row.new.fields.as_slice(),
@@ -416,6 +418,7 @@ fn run_diff(
                         RowRef {
                             old_record: record,
                             new_record: record,
+                            key: None,
                         },
                         old_row.as_slice(),
                         new_row.as_slice(),
@@ -960,13 +963,15 @@ fn map_column_error(err: ColumnTypingError<RowRef>, paths: RerunPaths<'_>) -> Re
                 ColumnSide::Old => FileSide::Old,
                 ColumnSide::New => FileSide::New,
             };
+            let key_value = detail.row_id.key.clone();
             RefusalPayload::with_default_next(
                 RefusalCode::MixedTypes,
                 RefusalKind::MixedTypes {
                     file,
                     record: detail.row_id.record_for(detail.side),
                     column: detail.column,
                     value: detail.value,
+                    key_value,
                 },
                 paths,
             )
@@ -980,13 +985,15 @@ fn map_column_error(err: ColumnTypingError<RowRef>, paths: RerunPaths<'_>) -> Re
                 ColumnSide::Old => FileSide::Old,
                 ColumnSide::New => FileSide::New,
             };
+            let key_value = detail.row_id.key.clone();
             RefusalPayload::with_default_next(
                 RefusalCode::Missingness,
                 RefusalKind::Missingness {
                     file,
                     record: detail.row_id.record_for(present_side),
                     column: detail.column,
                     value: detail.present_value,
+                    key_value,
                 },
                 paths,
             )
@@ -1574,24 +1581,38 @@ fn refusal_detail_json(detail: &RefusalDetail) -> Value {
             record,
             column,
             value,
-        } => json!({
-            "file": file.as_str(),
-            "record": record,
-            "column": encode_identifier_json(column),
-            "value": encode_identifier_json(value),
-        }),
+            key_value,
+        } => {
+            let mut obj = json!({
+                "file": file.as_str(),
+                "record": record,
+                "column": encode_identifier_json(column),
+                "value": encode_identifier_json(value),
+            });
+            if let Some(key) = key_value {
+                obj["key"] = json!(encode_identifier_json(key));
+            }
+            obj
+        }
         RefusalKind::NoNumeric => json!({}),
         RefusalKind::Missingness {
             file,
             record,
             column,
             value,
-        } => json!({
-            "file": file.as_str(),
-            "record": record,
-            "column": encode_identifier_json(column),
-            "value": encode_identifier_json(value),
-        }),
+            key_value,
+        } => {
+            let mut obj = json!({
+                "file": file.as_str(),
+                "record": record,
+                "column": encode_identifier_json(column),
+                "value": encode_identifier_json(value),
+            });
+            if let Some(key) = key_value {
+                obj["key"] = json!(encode_identifier_json(key));
+            }
+            obj
+        }
         RefusalKind::Diffuse {
             top_k_coverage,
             threshold,

src/output/human/refusal.rs

@@ -14,7 +14,8 @@ pub struct RefusalBody<'a> {
 }
 
 pub fn render_refusal_body(ctx: &RefusalBody<'_>) -> Vec<String> {
-    let mut lines = Vec::with_capacity(3);
+    let mut lines = Vec::with_capacity(4);
+    lines.push("Cannot produce a verdict.".to_string());
     lines.push(format!("Reason ({}): {}.", ctx.code, ctx.code.reason()));
     lines.push(render_example_line(ctx.detail, ctx.old_name, ctx.new_name));
     lines.push(format!("Next: {}", ctx.detail.next));
@@ -148,29 +149,45 @@ fn render_example_line(detail: &RefusalDetail, old_name: &str, new_name: &str) -
             record,
             column,
             value,
+            key_value,
         } => {
-            let file = file_label(*file, old_name, new_name);
             let column = render_identifier_human(column);
             let value = render_identifier_human(value);
-            format!(
-                "Example: {file} data record {} column \"{column}\" has non-numeric value \"{value}\".",
-                format_count_u64(*record)
-            )
+            if let Some(key) = key_value {
+                let key = render_identifier_human(key);
+                format!(
+                    "Example: key \"{key}\" column \"{column}\" has non-numeric value \"{value}\"."
+                )
+            } else {
+                let file = file_label(*file, old_name, new_name);
+                format!(
+                    "Example: {file} data record {} column \"{column}\" has non-numeric value \"{value}\".",
+                    format_count_u64(*record)
+                )
+            }
         }
         RefusalKind::NoNumeric => "Example: no numeric columns in common.".to_string(),
         RefusalKind::Missingness {
             file,
             record,
             column,
             value,
+            key_value,
         } => {
-            let file = file_label(*file, old_name, new_name);
             let column = render_identifier_human(column);
             let value = render_identifier_human(value);
-            format!(
-                "Example: {file} data record {} column \"{column}\" has numeric value \"{value}\" while the other side is missing.",
-                format_count_u64(*record)
-            )
+            if let Some(key) = key_value {
+                let key = render_identifier_human(key);
+                format!(
+                    "Example: key \"{key}\" column \"{column}\" has numeric value \"{value}\" while the other side is missing."
+                )
+            } else {
+                let file = file_label(*file, old_name, new_name);
+                format!(
+                    "Example: {file} data record {} column \"{column}\" has numeric value \"{value}\" while the other side is missing.",
+                    format_count_u64(*record)
+                )
+            }
         }
         RefusalKind::Diffuse {
             top_k_coverage,
@@ -253,12 +270,13 @@ mod tests {
             new_name: "new.csv",
         };
         let lines = render_refusal_body(&ctx);
-        assert_eq!(lines[0], "Reason (E_KEY_DUP): duplicate key values.");
+        assert_eq!(lines[0], "Cannot produce a verdict.");
+        assert_eq!(lines[1], "Reason (E_KEY_DUP): duplicate key values.");
         assert_eq!(
-            lines[1],
+            lines[2],
             "Example: old.csv data record 184 duplicates key \"A123\"."
         );
-        assert!(lines[2].starts_with("Next:"));
+        assert!(lines[3].starts_with("Next:"));
     }
 
     #[test]
@@ -277,11 +295,12 @@ mod tests {
             new_name: "new.csv",
         };
         let lines = render_refusal_body(&ctx);
+        assert_eq!(lines[0], "Cannot produce a verdict.");
         assert_eq!(
-            lines[0],
+            lines[1],
             "Reason (E_DIFFUSE): diffuse change below coverage threshold."
         );
-        assert_eq!(lines[1], "Example: top_k_coverage=80.0% threshold=95.0%.");
+        assert_eq!(lines[2], "Example: top_k_coverage=80.0% threshold=95.0%.");
     }
 
     #[test]
@@ -306,7 +325,7 @@ mod tests {
         };
         let lines = render_refusal_body(&ctx);
         assert_eq!(
-            lines[1],
+            lines[2],
             "Example: old.csv delimiter ambiguous among [comma, tab]."
         );
     }

src/refusal/details.rs

@@ -102,13 +102,15 @@ pub enum RefusalKind {
         record: u64,
         column: Vec<u8>,
         value: Vec<u8>,
+        key_value: Option<Vec<u8>>,
     },
     NoNumeric,
     Missingness {
         file: FileSide,
         record: u64,
         column: Vec<u8>,
         value: Vec<u8>,
+        key_value: Option<Vec<u8>>,
     },
     Diffuse {
         top_k_coverage: f64,

tests/fixtures/regression/README.md

@@ -11,5 +11,14 @@ Each case has expected human and JSON outputs checked by `tests/regression.rs`.
   - `basic.human.txt`
   - `basic.json`
 
+## missingness_key
+- Files: `missingness_key_old.csv`, `missingness_key_new.csv`
+- Mode: key (`--key id`)
+- Change: old has numeric value, new has missing value — triggers `E_MISSINGNESS`
+- Verifies key value (not record number) appears in the refusal example
+- Expected outputs:
+  - `missingness_key.human.txt`
+  - `missingness_key.json`
+
 Notes
 - Paths in the golden outputs are relative (e.g., `tests/fixtures/regression/basic_old.csv`) to keep tests stable across machines.

tests/fixtures/regression/missingness_key.human.txt

@@ -0,0 +1,12 @@
+RVL ERROR (E_MISSINGNESS)
+
+Compared: missingness_key_old.csv -> missingness_key_new.csv
+Alignment: key=id
+Dialect(old): delimiter=, quote=" escape=none
+Dialect(new): delimiter=, quote=" escape=none
+Settings: threshold=95.0% tolerance=1e-9
+
+Cannot produce a verdict.
+Reason (E_MISSINGNESS): missing value vs numeric value.
+Example: key "B" column "amount" has numeric value "200.75" while the other side is missing.
+Next: fill missing values or remove the column, then rerun

tests/fixtures/regression/missingness_key.json

@@ -0,0 +1 @@
+{"version":"rvl.v0","outcome":"REFUSAL","files":{"old":"tests/fixtures/regression/missingness_key_old.csv","new":"tests/fixtures/regression/missingness_key_new.csv"},"alignment":{"mode":"key","key_column":"u8:id"},"dialect":{"old":{"delimiter":",","quote":"\"","escape":null},"new":{"delimiter":",","quote":"\"","escape":null}},"threshold":0.95,"tolerance":1e-9,"counts":{"rows_old":null,"rows_new":null,"rows_aligned":null,"columns_old":null,"columns_new":null,"columns_common":null,"columns_old_only":null,"columns_new_only":null,"numeric_columns":null,"numeric_cells_checked":null,"numeric_cells_changed":null},"metrics":{"total_change":null,"max_abs_delta":null,"top_k_coverage":null},"limits":{"max_contributors":25},"contributors":[],"refusal":{"code":"E_MISSINGNESS","message":"missing value vs numeric value","detail":{"column":"u8:amount","file":"old","key":"u8:B","record":2,"value":"u8:200.75"}}}

tests/fixtures/regression/missingness_key_new.csv

@@ -0,0 +1,3 @@
+id,amount
+A,100.50
+B,

tests/fixtures/regression/missingness_key_old.csv

@@ -0,0 +1,3 @@
+id,amount
+A,100.50
+B,200.75

tests/fixtures/regression/no_numeric.human.txt

@@ -6,6 +6,7 @@ Dialect(old): delimiter=, quote=" escape=none
 Dialect(new): delimiter=, quote=" escape=none
 Settings: threshold=95.0% tolerance=1e-9
 
+Cannot produce a verdict.
 Reason (E_NO_NUMERIC): no numeric columns in common.
 Example: no numeric columns in common.
 Next: ensure common numeric columns exist (or adjust inputs) and rerun