Add full operator.v0 contract and --describe flag

Creates operator.json with all 18 refusal codes, CLI surface,
witness subcommands, and pipeline position. Wires --describe
to emit it via include_str!.

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

Author: Zac

operator.json

@@ -0,0 +1,112 @@
+{
+  "schema_version": "operator.v0",
+  "name": "rvl",
+  "version": "0.4.0",
+  "description": "Numeric change explainer — finds the smallest set of cell-level changes that account for the difference between two CSV files",
+  "repository": "https://github.com/cmdrvl/rvl",
+  "license": "MIT",
+  "agent_guide": "https://github.com/cmdrvl/.github/blob/main/profile/AGENT_PROMPT.md",
+
+  "invocation": {
+    "binary": "rvl",
+    "usage": [
+      "rvl <old.csv> <new.csv> [OPTIONS]",
+      "rvl witness <query|last|count> [OPTIONS]"
+    ],
+    "output_mode": "report",
+    "output_schema": "rvl.v0",
+    "json_flag": "--json"
+  },
+
+  "arguments": [
+    { "name": "old", "type": "file_path", "required": true, "position": 0, "description": "Old CSV file" },
+    { "name": "new", "type": "file_path", "required": true, "position": 1, "description": "New CSV file" }
+  ],
+
+  "options": [
+    { "name": "key", "flag": "--key", "type": "string", "description": "Align rows by this key column (otherwise align by row order)" },
+    { "name": "threshold", "flag": "--threshold", "type": "float", "default": 0.95, "description": "Coverage target: 0 < x <= 1" },
+    { "name": "tolerance", "flag": "--tolerance", "type": "float", "default": 1e-9, "description": "Per-cell noise floor: x >= 0" },
+    { "name": "delimiter", "flag": "--delimiter", "type": "string", "description": "Force CSV delimiter (comma/tab/semicolon/pipe/caret, 0xNN, or single ASCII byte)" },
+    { "name": "profile", "flag": "--profile", "type": "file_path", "description": "Use profile YAML at this path for key derivation and column scoping" },
+    { "name": "profile_id", "flag": "--profile-id", "type": "string", "description": "Resolve profile by ID from ~/.epistemic/profiles/*.yaml (or direct path)" },
+    { "name": "capsule_out", "flag": "--capsule-out", "type": "directory_path", "description": "Write deterministic repro capsule artifacts to this directory (default: disabled)" },
+    { "name": "json", "flag": "--json", "type": "flag", "description": "Emit JSON output (single object)" },
+    { "name": "no_witness", "flag": "--no-witness", "type": "flag", "description": "Suppress witness ledger recording" },
+    { "name": "describe", "flag": "--describe", "type": "flag", "description": "Print compiled operator.json and exit 0 without positional args" }
+  ],
+
+  "subcommands": [
+    {
+      "name": "witness",
+      "description": "Witness ledger query commands",
+      "status": "available",
+      "actions": [
+        {
+          "name": "query",
+          "usage": "rvl witness query [--tool <name>] [--since <iso8601>] [--until <iso8601>] [--outcome <REAL_CHANGE|NO_REAL_CHANGE|REFUSAL>] [--input-hash <substring>] [--limit <n>] [--json]"
+        },
+        {
+          "name": "last",
+          "usage": "rvl witness last [--json]"
+        },
+        {
+          "name": "count",
+          "usage": "rvl witness count [--tool <name>] [--since <iso8601>] [--until <iso8601>] [--outcome <REAL_CHANGE|NO_REAL_CHANGE|REFUSAL>] [--input-hash <substring>] [--json]"
+        }
+      ],
+      "current_runtime_behavior": {
+        "success_exit_code": 0,
+        "no_match_exit_code": 1,
+        "error_exit_code": 2,
+        "ledger_path_resolution": [
+          "EPISTEMIC_WITNESS",
+          "~/.epistemic/witness.jsonl"
+        ]
+      }
+    }
+  ],
+
+  "exit_codes": {
+    "0": { "meaning": "NO_REAL_CHANGE", "domain": "positive" },
+    "1": { "meaning": "REAL_CHANGE", "domain": "negative" },
+    "2": { "meaning": "REFUSAL / CLI error", "domain": "error" }
+  },
+
+  "refusals": [
+    { "code": "E_IO", "message": "Cannot read input file", "action": "escalate" },
+    { "code": "E_ENCODING", "message": "Unsupported text encoding (UTF-16/32 BOM or NUL bytes)", "action": "escalate" },
+    { "code": "E_CSV_PARSE", "message": "CSV parse failure", "action": "escalate" },
+    { "code": "E_HEADERS", "message": "Invalid or duplicate headers", "action": "escalate" },
+    { "code": "E_NO_KEY", "message": "Key column missing from file", "action": "retry_with_flag", "flag": "--key" },
+    { "code": "E_KEY_EMPTY", "message": "Empty key value in row", "action": "escalate" },
+    { "code": "E_KEY_DUP", "message": "Duplicate key values (non-unique)", "action": "escalate" },
+    { "code": "E_KEY_MISMATCH", "message": "Key sets differ between files", "action": "escalate" },
+    { "code": "E_ROWCOUNT", "message": "Row count mismatch and no key provided", "action": "retry_with_flag", "flag": "--key" },
+    { "code": "E_NEED_KEY", "message": "Cannot deterministically align without a key", "action": "retry_with_flag", "flag": "--key" },
+    { "code": "E_DIALECT", "message": "Delimiter ambiguous or undetectable", "action": "retry_with_flag", "flag": "--delimiter" },
+    { "code": "E_AMBIGUOUS_PROFILE", "message": "Both --profile and --profile-id were provided", "action": "adjust_input" },
+    { "code": "E_PROFILE_NOT_FOUND", "message": "Profile could not be resolved from ID", "action": "escalate" },
+    { "code": "E_KEY_CONFLICT", "message": "--key flag conflicts with profile-defined key", "action": "adjust_input" },
+    { "code": "E_MIXED_TYPES", "message": "Mixed numeric and non-numeric values in column", "action": "escalate" },
+    { "code": "E_NO_NUMERIC", "message": "No numeric columns in common", "action": "escalate" },
+    { "code": "E_MISSINGNESS", "message": "Numeric-vs-missing mismatch", "action": "escalate" },
+    { "code": "E_DIFFUSE", "message": "Diffuse change below coverage threshold", "action": "retry_with_flag", "flag": "--threshold" }
+  ],
+
+  "capabilities": {
+    "formats": ["csv"],
+    "profile_aware": true,
+    "streaming": false,
+    "witness": {
+      "ambient_recording": "enabled_by_default",
+      "query_subcommands": "available",
+      "no_witness_flag": "suppresses_recording"
+    }
+  },
+
+  "pipeline": {
+    "upstream": ["shape", "profile"],
+    "downstream": ["pack"]
+  }
+}

src/cli/args.rs

@@ -70,6 +70,10 @@ pub struct Args {
     #[arg(long)]
     pub no_witness: bool,
 
+    /// Print compiled operator.json and exit 0.
+    #[arg(long)]
+    pub describe: bool,
+
     #[command(subcommand)]
     pub command: Option<RvlCommand>,
 }
@@ -166,6 +170,7 @@ impl Args {
             capsule_out: None,
             json,
             no_witness: false,
+            describe: false,
             command: None,
         }
     }

src/lib.rs

@@ -14,6 +14,8 @@ pub mod refusal;
 pub mod repro;
 pub mod witness;
 
+const OPERATOR_JSON: &str = include_str!("../operator.json");
+
 /// Run the rvl pipeline. Returns exit code (0, 1, or 2).
 pub fn run() -> Result<u8, Box<dyn std::error::Error>> {
     let args = match cli::args::Args::parse() {
@@ -24,6 +26,11 @@ pub fn run() -> Result<u8, Box<dyn std::error::Error>> {
         }
     };
 
+    if args.describe {
+        println!("{OPERATOR_JSON}");
+        return Ok(0);
+    }
+
     if let Some(ref cmd) = args.command {
         return run_witness(cmd);
     }

tests/capsule_replay.rs

@@ -47,6 +47,7 @@ fn run_with_capsule(
         capsule_out: Some(capsule_root.to_path_buf()),
         json: true,
         no_witness: true,
+        describe: false,
         command: None,
     };
 
@@ -115,6 +116,7 @@ fn replay_from_manifest(manifest: &Value, capsule_dir: &Path) -> Value {
             .and_then(Value::as_bool)
             .expect("manifest.args.json"),
         no_witness: true,
+        describe: false,
         command: None,
     };
 

tests/profile_integration.rs

@@ -45,6 +45,7 @@ fn make_args(old: &PathBuf, new: &PathBuf) -> Args {
         capsule_out: None,
         json: true,
         no_witness: true,
+        describe: false,
         command: None,
     }
 }

tests/regression.rs

@@ -21,6 +21,7 @@ fn run_case(old: &str, new: &str, key: Option<&str>, json: bool) -> String {
         capsule_out: None,
         json,
         no_witness: true,
+        describe: false,
         command: None,
     };
     orchestrator::run(&args)