feat: add witness query subcommand (bd-ogo)

Add `rvl witness query/last/count` subcommands for reading the
append-only witness ledger. Uses clap's subcommand_negates_reqs
so `rvl <old.csv> <new.csv>` remains the default behavior.

New modules: witness/reader.rs (LedgerReader), witness/query.rs
(QueryFilter + human/JSON formatters). Filters: --tool, --since,
--until, --outcome, --input-hash, --limit. Bump version to 0.2.0.

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

Author: Zac

.beads/issues.jsonl

@@ -1,6 +1,6 @@
 [package]
 name = "rvl"
-version = "0.1.1"
+version = "0.2.0"
 edition = "2024"
 authors = ["CMD+RVL <engineering@cmdrvl.com>"]
 description = "Reveal the smallest set of numeric changes that explain what actually changed."
@@ -19,6 +19,7 @@ clap = { version = "4", features = ["derive"] }
 csv = "1"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+blake3 = "1"
 simd-csv = { version = "0.10.3", optional = true }
 
 [features]
@@ -27,6 +28,8 @@ simd_csv = ["simd-csv"]
 [dev-dependencies]
 arrow-csv = "57.2.0"
 arrow-schema = "57.2.0"
+blake3 = "1"
+jsonschema = "0.42"
 polars = { version = "0.52.0", default-features = false, features = ["csv"] }
 simd-csv = "0.10.3"
 

Cargo.lock

@@ -75,13 +75,15 @@ fn main() {
 
 fn run_case(case: &Case, iterations: u64, warmup: u64) -> f64 {
     let args = Args {
-        old: case.old.clone(),
-        new: case.new.clone(),
+        old: Some(case.old.clone()),
+        new: Some(case.new.clone()),
         key: case.key.clone(),
         threshold: 0.95,
         tolerance: 1e-9,
         delimiter: None,
         json: false,
+        no_witness: true,
+        command: None,
     };
 
     for _ in 0..warmup {

Cargo.toml

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cmdrvl.com/schemas/witness.v0.schema.json",
+  "title": "Witness Record v0",
+  "description": "Append-only audit record for a tool invocation, content-addressed via BLAKE3.",
+  "type": "object",
+  "required": [
+    "id",
+    "tool",
+    "version",
+    "binary_hash",
+    "inputs",
+    "params",
+    "outcome",
+    "exit_code",
+    "output_hash",
+    "prev",
+    "ts"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^blake3:[0-9a-f]{64}$",
+      "description": "Content-addressed record ID: blake3 hash of the canonical JSON with id blanked."
+    },
+    "tool": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the tool that produced this record."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+",
+      "description": "Semantic version of the tool."
+    },
+    "binary_hash": {
+      "type": "string",
+      "pattern": "^blake3:[0-9a-f]{64}$",
+      "description": "BLAKE3 hash of the tool binary at invocation time."
+    },
+    "inputs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["path", "hash", "bytes"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "File path as provided to the tool."
+          },
+          "hash": {
+            "type": "string",
+            "pattern": "^blake3:[0-9a-f]{64}$",
+            "description": "BLAKE3 hash of the file contents."
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "File size in bytes."
+          }
+        }
+      },
+      "description": "Input files consumed by the tool invocation."
+    },
+    "params": {
+      "type": "object",
+      "description": "Tool-specific parameters (additionalProperties allowed)."
+    },
+    "outcome": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Tool-specific outcome label (e.g. REAL_CHANGE, NO_REAL_CHANGE, REFUSAL)."
+    },
+    "exit_code": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 255,
+      "description": "Process exit code."
+    },
+    "output_hash": {
+      "type": "string",
+      "pattern": "^blake3:[0-9a-f]{64}$",
+      "description": "BLAKE3 hash of the tool's output text."
+    },
+    "prev": {
+      "oneOf": [
+        {
+          "type": "string",
+          "pattern": "^blake3:[0-9a-f]{64}$"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "ID of the previous record in the ledger chain, or null for the first record."
+    },
+    "ts": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "ISO 8601 UTC timestamp of the invocation."
+    }
+  }
+}

benches/runtime.rs

@@ -1,6 +1,6 @@
 use std::path::PathBuf;
 
-use clap::Parser;
+use clap::{Parser, Subcommand};
 
 use super::delimiter::parse_delimiter_arg;
 
@@ -12,16 +12,17 @@ const DEFAULT_TOLERANCE: f64 = 1e-9;
 #[command(
     name = "rvl",
     about = "Reveal the smallest set of numeric changes that explain what actually changed.",
-    override_usage = "rvl <old.csv> <new.csv> [--key <column>] [--threshold <float>] [--tolerance <float>] [--delimiter <delim>] [--json]"
+    override_usage = "rvl <old.csv> <new.csv> [OPTIONS]\n       rvl witness <query|last|count> [OPTIONS]",
+    subcommand_negates_reqs = true
 )]
 pub struct Args {
     /// Old CSV path.
     #[arg(value_name = "OLD_CSV")]
-    pub old: PathBuf,
+    pub old: Option<PathBuf>,
 
     /// New CSV path.
     #[arg(value_name = "NEW_CSV")]
-    pub new: PathBuf,
+    pub new: Option<PathBuf>,
 
     /// Align rows by this key column (otherwise align by row order).
     #[arg(long, value_name = "COLUMN")]
@@ -52,6 +53,70 @@ pub struct Args {
     /// Emit JSON output (single object).
     #[arg(long)]
     pub json: bool,
+
+    /// Suppress witness ledger recording.
+    #[arg(long)]
+    pub no_witness: bool,
+
+    #[command(subcommand)]
+    pub command: Option<RvlCommand>,
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum RvlCommand {
+    /// Query the witness ledger.
+    Witness {
+        #[command(subcommand)]
+        action: WitnessAction,
+    },
+}
+
+#[derive(Debug, Clone, Subcommand)]
+pub enum WitnessAction {
+    /// Search witness records with filters.
+    Query(WitnessQueryArgs),
+    /// Show the most recent witness record.
+    Last(WitnessLastArgs),
+    /// Count matching witness records.
+    Count(WitnessQueryArgs),
+}
+
+#[derive(Debug, Clone, clap::Args)]
+pub struct WitnessQueryArgs {
+    /// Filter by tool name.
+    #[arg(long)]
+    pub tool: Option<String>,
+
+    /// Filter records on or after this ISO 8601 timestamp.
+    #[arg(long)]
+    pub since: Option<String>,
+
+    /// Filter records on or before this ISO 8601 timestamp.
+    #[arg(long)]
+    pub until: Option<String>,
+
+    /// Filter by outcome (REAL_CHANGE, NO_REAL_CHANGE, REFUSAL).
+    #[arg(long)]
+    pub outcome: Option<String>,
+
+    /// Filter by input file hash (substring match).
+    #[arg(long)]
+    pub input_hash: Option<String>,
+
+    /// Maximum number of records to return (default: 20).
+    #[arg(long, default_value_t = 20)]
+    pub limit: usize,
+
+    /// Emit JSON output.
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Debug, Clone, clap::Args)]
+pub struct WitnessLastArgs {
+    /// Emit JSON output.
+    #[arg(long)]
+    pub json: bool,
 }
 
 impl Args {
@@ -70,15 +135,27 @@ impl Args {
         json: bool,
     ) -> Self {
         Self {
-            old,
-            new,
+            old: Some(old),
+            new: Some(new),
             key,
             threshold,
             tolerance,
             delimiter,
             json,
+            no_witness: false,
+            command: None,
         }
     }
+
+    /// Get the old path, panics if not set (only valid in comparison mode).
+    pub fn old_path(&self) -> &PathBuf {
+        self.old.as_ref().expect("old path required for comparison")
+    }
+
+    /// Get the new path, panics if not set (only valid in comparison mode).
+    pub fn new_path(&self) -> &PathBuf {
+        self.new.as_ref().expect("new path required for comparison")
+    }
 }
 
 fn parse_threshold(raw: &str) -> Result<f64, String> {