Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

72.4 KB
Raw Blame
//! Batch mode — run multiple CLI commands against a single shared graph store.
//!
//! Reads commands from a file or stdin (one per line, or JSON array),
//! executes them sequentially with shared state, and outputs NDJSON.

use std::sync::Arc;
use serde_json::{json, Value};

use crate::graph::GraphStore;
use crate::state::StateDb;

/// Holds shared state across batch commands.
pub struct BatchRunner {
    db: StateDb,
    graph: Arc<GraphStore>,
    pretty: bool,
}

/// A parsed batch command with its arguments.
#[derive(Debug)]
struct BatchCmd {
    name: String,
    args: Vec<String>,
}

impl BatchRunner {
    pub fn new(db: StateDb, graph: Arc<GraphStore>, pretty: bool) -> Self {
        Self { db, graph, pretty }
    }

    /// Parse input (auto-detect line vs JSON format) and run all commands,
    /// printing each result as it completes.
    /// Returns the process exit code (0 = success, 1 = at least one error).
    pub async fn run(&self, input: &str, bail: bool) -> i32 {
        self.run_each(input, bail, |line| self.print_json(line)).await
    }

    /// Run all commands and collect results into a Vec instead of printing.
    /// Returns (results, exit_code).
    pub async fn run_collect(&self, input: &str, bail: bool) -> (Vec<Value>, i32) {
        let mut results = Vec::new();
        let code = self
            .run_each(input, bail, |line| results.push(line.clone()))
            .await;
        (results, code)
    }

    /// The one driver behind `run` and `run_collect`. They differ only in what
    /// they do with each result, so that is the only thing they pass in: keeping
    /// two copies of the loop meant keeping the envelope, the bail handling and
    /// the exit code in step by hand. A sink rather than a returned Vec because
    /// `run` prints as it goes, and a batch of a hundred loads should not go
    /// silent until the last one finishes.
    async fn run_each<F: FnMut(&Value)>(&self, input: &str, bail: bool, mut on_result: F) -> i32 {
        let commands = match parse_input(input) {
            Ok(cmds) => cmds,
            Err(e) => {
                on_result(&json!({"seq": 0, "command": "parse", "error": e}));
                return 1;
            }
        };

        let mut exit_code = 0;
        for (seq, cmd) in commands.iter().enumerate() {
            let result = self.execute(cmd).await;
            let has_error = result.get("error").is_some();
            // A STOP-THE-LINE disagreement is not an `error`: the command ran
            // and answered. It must still fail the run, because it means a
            // verified checker and the thing it was checking disagree, and a
            // pipeline that treated that as a normal result would be a
            // pipeline in which the check never has to pass. This is the same
            // rule `tools/shacl_differential.py` applies to a FALSE_CLEAN,
            // which exits 1 while every other verdict exits 0. Keyed on the
            // field rather than on the command name so that a later command
            // reporting the same thing inherits it. See decision 0006.
            let stopped = result
                .get("stop_the_line")
                .and_then(Value::as_u64)
                .unwrap_or(0)
                > 0;
            on_result(&json!({
                "seq": seq,
                "command": cmd.name,
                "result": result,
            }));

            // A command that reports its own `exit_code` keeps it through the
            // batch. `preserve` and `closure-diff` are the only ones with more
            // than two outcomes: clean, something was lost, and a stop-the-line
            // disagreement that means a defect in the engine or in this code.
            // Without this the exit code was invisible in the ONLY path these
            // commands can realistically run through, since the store is
            // in-memory per process, and a stop-the-line would have exited 0.
            if let Some(c) = result.get("exit_code").and_then(|c| c.as_i64())
                && c > exit_code as i64
            {
                exit_code = c as i32;
            }

            // `|| stopped` is ours and postdates their branch point. Their side
            // dropped it, which would have stopped a halted batch reporting failure.
            if has_error || stopped {
                exit_code = exit_code.max(1);
                if bail {
                    break;
                }
            }
        }
        exit_code
    }

    fn print_json(&self, value: &Value) {
        if self.pretty {
            println!("{}", serde_json::to_string_pretty(value).unwrap());
        } else {
            println!("{}", value);
        }
    }

    async fn execute(&self, cmd: &BatchCmd) -> Value {
        match cmd.name.as_str() {
            "load" => self.exec_load(&cmd.args),
            "save" => self.exec_save(&cmd.args),
            "clear" => self.exec_clear(),
            "stats" => self.exec_stats(),
            "query" => self.exec_query(&cmd.args),
            "validate" => self.exec_validate(&cmd.args),
            "lint" => self.exec_lint(&cmd.args),
            "defects" => self.exec_defects(&cmd.args),
            "reason" => self.exec_reason(&cmd.args),
            "certificate-check" | "certificate_check" => self.exec_certificate_check(&cmd.args),
            "fol" => self.exec_fol(&cmd.args),
            "rules-import" | "rules_import" => self.exec_rules_import(&cmd.args),
            "fol-model" | "fol_model" => self.exec_fol_model(&cmd.args),
            "fol-prove" | "fol_prove" => self.exec_fol_prove(&cmd.args),
            "preserve" => self.exec_preserve(&cmd.args),
            "closure-diff" | "closure_diff" => self.exec_closure_diff(&cmd.args),
            "trace-label" | "trace_label" => self.exec_trace_label(&cmd.args),
            "shacl" => self.exec_shacl(&cmd.args),
            // The CLI subcommand is spelled with a hyphen and this arm accepted
            // only the underscore, so every documented invocation was rejected
            // as an unknown batch command while the implementation sat unused.
            "vocab-check" | "vocab_check" => self.exec_vocab_check(&cmd.args),
            "diff" => self.exec_diff(&cmd.args),
            "convert" => self.exec_convert(&cmd.args),
            "enforce" => self.exec_enforce(&cmd.args),
            "unpack" => self.exec_unpack(&cmd.args),
            "plan" => self.exec_plan(&cmd.args),
            "apply" => self.exec_apply(&cmd.args),
            "version" => self.exec_version(&cmd.args),
            "history" => self.exec_history(),
            "rollback" => self.exec_rollback(&cmd.args),
            "status" => self.exec_status(),
            "pull" => self.exec_pull(&cmd.args).await,
            "push" => self.exec_push(&cmd.args).await,
            "ingest" => self.exec_ingest(&cmd.args),
            "induce" => self.exec_induce(&cmd.args),
            "crosswalk-certify" | "crosswalk_certify" => Self::exec_crosswalk(&cmd.args),
            "crosswalk-probe" | "crosswalk_probe" | "contradiction-probe" | "contradiction_probe" => {
                Self::exec_crosswalk_probe(&cmd.args)
            }
            "modules" | "distributed" => Self::exec_modules(&cmd.args),
            "matcert" => Self::exec_matcert(&cmd.args),
            "drift" => self.exec_drift(&cmd.args),
            "lock" => self.exec_lock(&cmd.args),
            "monitor" => self.exec_monitor(),
            "monitor-clear" => self.exec_monitor_clear(),
            "marketplace" => self.exec_marketplace(&cmd.args).await,
            _ => json!({"error": format!("unknown batch command: '{}'", cmd.name)}),
        }
    }

    // ─── Command implementations ─────────────────────────────────────

    /// `push` was serialized by the proxy and had no arm here, so it was the one
    /// proxy-able command that could not run: it fell through to
    /// `unknown batch command` and exited 1 whenever a daemon was up. Running it
    /// locally instead would be worse than an error, because the store holding
    /// the triples worth pushing is the daemon's.
    async fn exec_push(&self, args: &[String]) -> Value {
        let endpoint = match args.first() {
            Some(e) => e,
            None => return json!({"error": "push requires an endpoint"}),
        };
        let content = match self.graph.serialize("ntriples") {
            Ok(c) => c,
            Err(e) => return json!({"error": e.to_string()}),
        };
        match GraphStore::push_sparql(endpoint, &content).await {
            Ok(msg) => json!({"ok": true, "message": msg}),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_load(&self, args: &[String]) -> Value {
        let path = match args.first() {
            Some(p) => p,
            None => return json!({"error": "load requires a file path"}),
        };
        match self.graph.load_file(path) {
            Ok(count) => json!({"ok": true, "triples_loaded": count, "path": path}),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_save(&self, args: &[String]) -> Value {
        let path = match args.first() {
            Some(p) => p,
            None => return json!({"error": "save requires a file path"}),
        };
        let format = Self::flag_value(args, "--format").unwrap_or("turtle".to_string());
        match self.graph.save_file(path, &format) {
            Ok(_) => json!({"ok": true, "path": path, "format": format}),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_clear(&self) -> Value {
        match self.graph.clear() {
            Ok(_) => json!({"ok": true, "message": "Store cleared"}),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_stats(&self) -> Value {
        match self.graph.get_stats() {
            Ok(s) => serde_json::from_str(&s).unwrap_or(json!({"raw": s})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_query(&self, args: &[String]) -> Value {
        if args.is_empty() {
            return json!({"error": "query requires a SPARQL string. Accepted forms: \
                a line such as `query SELECT ?s WHERE { ?s ?p ?o }`, or JSON \
                {\"command\":\"query\",\"args\":\"SELECT ...\"}, or \
                {\"command\":\"query\",\"args\":[\"SELECT ...\"]}"});
        }
        // Defensive: if a caller supplies a query already split across arguments,
        // rejoin it rather than silently running the first fragment.
        let joined;
        let query = if args.len() == 1 {
            &args[0]
        } else {
            joined = args.join(" ");
            &joined
        };
        match self.graph.sparql_select(query) {
            Ok(s) => serde_json::from_str(&s).unwrap_or(json!({"raw": s})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_validate(&self, args: &[String]) -> Value {
        let input = match args.first() {
            Some(p) => p,
            None => return json!({"error": "validate requires a file path"}),
        };
        match GraphStore::validate_file(input) {
            Ok(counts) => json!({
                "ok": true,
                "triples": counts.triples,
                "statements": counts.statements,
            }),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_lint(&self, args: &[String]) -> Value {
        use crate::ontology::OntologyService;
        let input = match args.first() {
            Some(p) => p,
            None => return json!({"error": "lint requires a file path"}),
        };
        match crate::graph::GraphStore::read_as_turtle(input) {
            Ok(content) => {
                let result = OntologyService::lint_with_feedback(&content, Some(&self.db))
                    .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
                serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
            }
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// `defects [path] [--limit N]`. With a path, the file is checked alone,
    /// as the CLI subcommand checks it; without one, the batch's own store is,
    /// so `load x.ttl` then `defects` checks what was loaded. The CLI proxies
    /// `defects` here when a daemon is up, and there was no arm, so it answered
    /// `unknown batch command` and exited 1 (#336).
    fn exec_defects(&self, args: &[String]) -> Value {
        use crate::defects::Defects;
        let limit = match Self::flag_value(args, "--limit") {
            None => Defects::MAX_PER_KIND,
            Some(v) => match v.parse::<usize>() {
                Ok(n) => n,
                Err(_) => return json!({"error": format!("--limit takes a whole number, got '{v}'")}),
            },
        };
        let mut skip_next = false;
        let path = args.iter().find(|a| {
            if std::mem::take(&mut skip_next) {
                return false;
            }
            if a.as_str() == "--limit" {
                skip_next = true;
                return false;
            }
            !a.starts_with("--")
        });
        let graph = match path {
            None => self.graph.clone(),
            Some(p) => {
                let content = match crate::graph::GraphStore::read_as_turtle(p) {
                    Ok(c) => c,
                    Err(e) => return json!({"error": e.to_string()}),
                };
                let g = Arc::new(GraphStore::new());
                if let Err(e) = g.load_turtle(&content, None) {
                    return json!({"error": e.to_string()});
                }
                g
            }
        };
        match Defects::check_with_limit(&graph, limit) {
            Ok(result) => serde_json::from_str(&result).unwrap_or(json!({"raw": result})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_reason(&self, args: &[String]) -> Value {
        use crate::reason::{InferenceTarget, Reasoner};
        let profile = Self::flag_value(args, "--profile")
            .or_else(|| args.first().filter(|a| !a.starts_with("--")).cloned())
            .unwrap_or("rdfs".to_string());
        let certificate = Self::flag_value(args, "--certificate");
        let rules = Self::flag_value(args, "--rules");
        // #108. Batch is the only entry point that can load and certify in one
        // process, so it is the one a certified run over a versioned store
        // actually uses. A batch runner that did not understand these flags
        // would leave the gate with no way through on the path that needs it
        // most.
        let request = match crate::temporal::ScopeRequest::from_args(
            Self::flag_value(args, "--valid-at").as_deref(),
            Self::flag_value(args, "--as-of").as_deref(),
            args.iter().any(|a| a == "--all-versions"),
        ) {
            Ok(r) => r,
            Err(e) => return json!({"error": e.to_string()}),
        };
        // Nothing may be written into a versioned store, so passing any
        // temporal scope argument makes the run a DRY one rather than a
        // refusal on every scoped invocation. A run with no such argument
        // keeps the historical `true` and is refused before it can write.
        let materialize = matches!(request, crate::temporal::ScopeRequest::Unscoped);
        // `--rules FILE` evaluates a SUPPLIED Horn table instead of a built-in
        // profile and writes a certificate `oo-horn check` can verify. It needs
        // somewhere to put that certificate: a run over rules nobody has
        // checked reports nothing about what it proved, so without the
        // certificate there would be nothing to check and the counts would
        // stand on the engine's word alone.
        let result = match (rules.as_deref(), certificate.as_deref()) {
            (Some(rules_path), Some(dir)) => Reasoner::run_horn_scoped(
                &self.graph,
                std::path::Path::new(rules_path),
                std::path::Path::new(dir),
                &request,
            )
            .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string()),
            (Some(_), None) => json!({
                "error": "reason --rules needs --certificate DIR. A run over a supplied rule \
                          table states no verdict of its own: the certificate is the output, and \
                          `lake exe oo-horn check` is what pronounces on it"
            })
            .to_string(),
            (None, cert) => Reasoner::run_scoped(
                &self.graph,
                &profile,
                materialize,
                InferenceTarget::DefaultGraph,
                cert.map(std::path::Path::new),
                &request,
            )
            .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string()),
        };
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    /// First-order export. The store is in-memory per process, so this is the
    /// only way to load and export in one run, exactly as for `reason
    /// --certificate`.
    fn exec_fol(&self, args: &[String]) -> Value {
        let Some(out) = Self::flag_value(args, "--out") else {
            return json!({"error": "fol requires --out DIR"});
        };
        let format = Self::flag_value(args, "--format").unwrap_or("tptp".to_string());
        let dialect = Self::flag_value(args, "--clif-dialect");
        let comments = Self::flag_value(args, "--clif-comments");
        let domain = Self::flag_value(args, "--smt-domain").and_then(|v| v.parse::<u32>().ok());
        let syntax = match crate::tptp::Syntax::parse(
            &format,
            dialect.as_deref(),
            comments.as_deref(),
            domain,
        ) {
            Ok(s) => s,
            Err(e) => return json!({"error": e.to_string()}),
        };
        let goals = Self::flag_value(args, "--goals");
        let skip: usize = Self::flag_value(args, "--goals-skip-columns")
            .and_then(|v| v.parse().ok())
            .unwrap_or(0);
        let result = crate::tptp::export(
            &self.graph,
            std::path::Path::new(&out),
            syntax,
            goals.as_deref().map(std::path::Path::new),
            skip,
        )
        .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string());
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    /// In-process for the reason `reason --certificate` is: the store is
    /// in-memory per process, so loading and labelling have to happen in one
    /// run.
    fn exec_trace_label(&self, args: &[String]) -> Value {
        let Some(trace) = Self::flag_value(args, "--trace") else {
            return json!({"error": "trace-label requires --trace FILE (oo-trace/1)"});
        };
        let Some(out) = Self::flag_value(args, "--out") else {
            return json!({
                "error": "trace-label requires --out DIR: the per-step certificates are the \
                          output, and the Lean checker is what pronounces"
            });
        };
        let text = match std::fs::read_to_string(&trace) {
            Ok(t) => t,
            Err(e) => return json!({"error": format!("cannot read {trace}: {e}")}),
        };
        let steps = match crate::trace_label::parse_trace(&text) {
            Ok(s) => s,
            Err(e) => return json!({"error": e.to_string()}),
        };
        let opts = crate::trace_label::Opts {
            profile: Self::flag_value(args, "--profile").unwrap_or_else(|| "owl-rl".into()),
            rules: Self::flag_value(args, "--rules").map(std::path::PathBuf::from),
            work_dir: std::path::PathBuf::from(&out),
            checker: Self::flag_value(args, "--checker").map(std::path::PathBuf::from),
            require_checker: args.iter().any(|a| a == "--require-checker"),
        };
        match crate::trace_label::label_trace(&self.graph, &steps, &opts) {
            Ok(r) => serde_json::to_value(&r).unwrap_or_else(|e| json!({"error": e.to_string()})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// `--from swrl` with no `--file` reads the loaded graph, which is why
    /// this command is proxied to the daemon rather than run locally.
    fn exec_rules_import(&self, args: &[String]) -> Value {
        let Some(from) = Self::flag_value(args, "--from") else {
            return json!({
                "error": "rules-import needs --from: 'swrl' (SWRL rules encoded in RDF) or 'rif' \
                          (RIF Core, XML syntax)"
            });
        };
        let file = Self::flag_value(args, "--file");
        let out = Self::flag_value(args, "--out");
        let allow_partial = args.iter().any(|a| a == "--allow-partial");
        let result = crate::rulesyntax::run_import(
            &self.graph,
            &from,
            file.as_deref().map(std::path::Path::new),
            out.as_deref().map(std::path::Path::new),
            allow_partial,
        )
        .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string());
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    /// Run a prover and re-check the derivation it prints. In-process for the
    /// same reason `fol` is: the store is per process, so loading and proving
    /// have to happen in one run.
    ///
    /// The check-only pair (`--problem` with `--proof`) is here too, because a
    /// pipeline that already holds both files should not have to start a
    /// second process to get a verdict on them.
    fn exec_fol_prove(&self, args: &[String]) -> Value {
        use crate::tstp::{ProveOptions, Prover, check_files, prove_export};
        if let (Some(problem), Some(proof)) =
            (Self::flag_value(args, "--problem"), Self::flag_value(args, "--proof"))
        {
            let result =
                check_files(std::path::Path::new(&problem), std::path::Path::new(&proof))
                    .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string());
            return serde_json::from_str(&result).unwrap_or(json!({"raw": result}));
        }
        let Some(out) = Self::flag_value(args, "--out") else {
            return json!({"error":
                "fol-prove requires --out DIR, or --problem FILE with --proof FILE"});
        };
        let prover = match Prover::parse(
            &Self::flag_value(args, "--prover").unwrap_or("vampire".to_string()),
        ) {
            Ok(p) => p,
            Err(e) => return json!({"error": e.to_string()}),
        };
        let opts = ProveOptions {
            prover,
            timeout_secs: Self::flag_value(args, "--timeout-secs")
                .and_then(|v| v.parse().ok())
                .unwrap_or(30),
        };
        let goals = Self::flag_value(args, "--goals");
        let skip: usize = Self::flag_value(args, "--goals-skip-columns")
            .and_then(|v| v.parse().ok())
            .unwrap_or(0);
        let result = prove_export(
            &self.graph,
            std::path::Path::new(&out),
            &opts,
            goals.as_deref().map(std::path::Path::new),
            skip,
        )
        .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string());
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    /// The certifying pipeline. In-process for the same reason `fol` is: the
    /// store is per process, so loading and solving have to happen in one run.
    fn exec_fol_model(&self, args: &[String]) -> Value {
        use crate::fol_solve::{SolveOptions, Solver, solve_export};
        let Some(out) = Self::flag_value(args, "--out") else {
            return json!({"error": "fol-model requires --out DIR"});
        };
        let solver = match Solver::parse(
            &Self::flag_value(args, "--solver").unwrap_or("z3".to_string()),
        ) {
            Ok(s) => s,
            Err(e) => return json!({"error": e.to_string()}),
        };
        let opts = SolveOptions {
            solver,
            max_domain: Self::flag_value(args, "--max-domain")
                .and_then(|v| v.parse().ok())
                .unwrap_or(16),
            timeout_secs: Self::flag_value(args, "--timeout-secs")
                .and_then(|v| v.parse().ok())
                .unwrap_or(30),
            unbounded_probe: Self::flag_value(args, "--unbounded-probe")
                .map(|v| v != "false")
                .unwrap_or(true),
            checker: Self::flag_value(args, "--checker").map(std::path::PathBuf::from),
        };
        let goals = Self::flag_value(args, "--goals");
        let skip: usize = Self::flag_value(args, "--goals-skip-columns")
            .and_then(|v| v.parse().ok())
            .unwrap_or(0);
        let result = solve_export(
            &self.graph,
            std::path::Path::new(&out),
            &opts,
            goals.as_deref().map(std::path::Path::new),
            skip,
        )
        .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string());
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    /// Entailment preservation over a supplied goal set.
    ///
    /// Needed here for the same reason `reason --certificate` is: the store is
    /// in-memory per process, so `batch` is the only way to load a source and
    /// then ask about a slice of it in one run.
    fn exec_preserve(&self, args: &[String]) -> Value {
        use crate::projection_entailment as pe;
        let Some(goals_path) = Self::flag_value(args, "--goals") else {
            return json!({"error": "preserve requires --goals FILE"});
        };
        let Some(out) = Self::flag_value(args, "--out") else {
            return json!({"error": "preserve requires --out DIR"});
        };
        let ttl_path = Self::flag_value(args, "--projection");
        let graph_name = Self::flag_value(args, "--projection-graph");
        if ttl_path.is_some() == graph_name.is_some() {
            return json!({"error":
                "preserve needs exactly one of --projection FILE and --projection-graph IRI. A \
                 named graph of the loaded store keeps blank node identity, so P ⊆ G can be \
                 verified over every triple rather than over ground triples only"});
        }
        let goals_text = match std::fs::read_to_string(&goals_path) {
            Ok(t) => t,
            Err(e) => return json!({"error": format!("cannot read {goals_path}: {e}")}),
        };
        let skip: usize = Self::flag_value(args, "--goals-skip-columns")
            .and_then(|v| v.parse().ok())
            .unwrap_or(0);
        // A TSV is asked for by --goals-skip-columns or by a .tsv name; Turtle
        // otherwise. The goal document goes through the store's OWN parser
        // either way, which is the only thing that makes a caller's spelling of
        // a term comparable with the interner's.
        let parsed = if skip > 0 || goals_path.ends_with(".tsv") {
            pe::parse_goals_tsv(&goals_text, skip)
        } else {
            pe::parse_goals_turtle(&goals_text)
        };
        let (goals, refused) = match parsed {
            Ok(v) => v,
            Err(e) => return json!({"error": e.to_string()}),
        };
        let opts = pe::Opts {
            profile: Self::flag_value(args, "--profile").unwrap_or("owl-rl".into()),
            rules: Self::flag_value(args, "--rules").map(std::path::PathBuf::from),
            work_dir: std::path::PathBuf::from(&out),
            checker: Self::flag_value(args, "--checker").map(std::path::PathBuf::from),
            require_checker: args.iter().any(|a| a == "--require-checker"),
            seed_iris: Self::flag_values(args, "--seed"),
        };
        let projection_ttl;
        let projection = match (&ttl_path, &graph_name) {
            (Some(p), _) => match std::fs::read_to_string(p) {
                Ok(t) => {
                    projection_ttl = t;
                    pe::Projection::Turtle(&projection_ttl)
                }
                Err(e) => return json!({"error": format!("cannot read {p}: {e}")}),
            },
            (_, Some(g)) => pe::Projection::NamedGraph(g),
            _ => unreachable!("checked above"),
        };
        match pe::check_entailment_preservation(&self.graph, projection, &goals, &refused, &opts) {
            Ok(r) => serde_json::to_value(r).unwrap_or_else(|e| json!({"error": e.to_string()})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// The goal-free form: which conclusions a projection preserves.
    fn exec_closure_diff(&self, args: &[String]) -> Value {
        use crate::closure_diff as cd;
        let Some(proj) = Self::flag_value(args, "--projection") else {
            return json!({"error": "closure-diff requires --projection FILE"});
        };
        let Some(out) = Self::flag_value(args, "--out") else {
            return json!({"error": "closure-diff requires --out DIR"});
        };
        let ttl = match std::fs::read_to_string(&proj) {
            Ok(t) => t,
            Err(e) => return json!({"error": format!("cannot read {proj}: {e}")}),
        };
        let opts = cd::DiffOptions {
            profile: Self::flag_value(args, "--profile").unwrap_or("owl-rl-ext".into()),
            out: std::path::PathBuf::from(&out),
            checker: Self::flag_value(args, "--checker").map(std::path::PathBuf::from),
            skolemise_source: Self::flag_value(args, "--skolemise-source")
                .map(|v| v != "false")
                .unwrap_or(true),
            max_rows: Self::flag_value(args, "--max-rows")
                .and_then(|v| v.parse().ok())
                .unwrap_or(200),
            seed_iris: Self::flag_values(args, "--seed"),
        };
        match cd::closure_diff(&self.graph, &ttl, &opts) {
            Ok(r) => serde_json::to_value(r).unwrap_or_else(|e| json!({"error": e.to_string()})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// SHACL, on either of the two evaluators.
    ///
    /// `--verified` runs `oo-shacl`, whose agreement with the Recommendation is
    /// the machine-checked theorem `Shacl.validate_spec`. Until this flag
    /// existed that evaluator was reachable from the MCP tool `onto_shacl` and
    /// from nothing else, so a user of the command line could not obtain the
    /// repository's strongest SHACL answer at all (#203).
    ///
    /// The two are NOT the same question and the reports say so: the verified
    /// one carries a `verified` key that the unverified one never emits, and
    /// `undetermined` is a first-class answer there rather than a silent
    /// omission from a `skipped_constraints` list.
    fn exec_shacl(&self, args: &[String]) -> Value {
        use crate::shacl::ShaclValidator;
        let shapes_path = match args.first() {
            Some(p) => p,
            None => return json!({"error": "shacl requires a shapes file path"}),
        };
        // A batch result is a JSON value, so an RDF report has nowhere to go.
        // The CLI keeps such an invocation local for that reason; one written
        // into a batch file by hand is refused rather than answered in JSON.
        if let Some(f) = Self::flag_value(args, "--report-format")
            && f != "json"
        {
            return json!({"error": format!(
                "--report-format {f} is not available in a batch: batch results are JSON. \
                 Run `shacl --report-format {f}` directly."
            )});
        }
        if args.iter().any(|a| a == "--verified") {
            // Refused rather than ignored, the same answer `onto_shacl` gives.
            // The verified evaluator reads one N-Triples dump of the store and
            // has no notion of a temporal scope, so honouring the argument is
            // impossible and dropping it would answer a different question
            // from the one that was asked.
            if Self::flag_value(args, "--valid-at").is_some()
                || Self::flag_value(args, "--as-of").is_some()
                || args.iter().any(|a| a == "--all-versions")
            {
                return json!({"error":
                    "--verified cannot be combined with --valid-at, --as-of or \
                     --all-versions. The verified evaluator reads the whole store and has \
                     no temporal scope, so the scope would be silently dropped. Run the \
                     scoped question without --verified, or the verified question without \
                     a scope."});
            }
            return match std::fs::read_to_string(shapes_path) {
                Ok(shapes) => crate::shacl_verified::validate_verified(&self.graph, &shapes)
                    .unwrap_or_else(|e| json!({"error": e.to_string()})),
                Err(e) => json!({"error": e.to_string()}),
            };
        }
        let request = match crate::temporal::ScopeRequest::from_args(
            Self::flag_value(args, "--valid-at").as_deref(),
            Self::flag_value(args, "--as-of").as_deref(),
            args.iter().any(|a| a == "--all-versions"),
        ) {
            Ok(r) => r,
            Err(e) => return json!({"error": e.to_string()}),
        };
        match std::fs::read_to_string(shapes_path) {
            Ok(shapes_content) => {
                let result =
                    ShaclValidator::validate_scoped(&self.graph, &shapes_content, &request)
                        .unwrap_or_else(|e| json!({"error": e.to_string()}).to_string());
                serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
            }
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// Certify a crosswalk's match types against what the two ontologies entail.
    ///
    /// Takes its own two stores rather than the loaded one, because the whole
    /// point is that each side is reasoned INDEPENDENTLY: merging them into
    /// one graph would let each side's axioms answer the other's questions,
    /// which is the comparison this is supposed to make, not an input to it.
    fn exec_crosswalk(args: &[String]) -> Value {
        let pos: Vec<&String> = args.iter().filter(|a| !a.starts_with("--")).collect();
        if pos.len() < 3 {
            return json!({"error": "crosswalk-certify needs SOURCE TARGET MAPPINGS.tsv"});
        }
        match crate::crosswalk::certify_files(pos[0], pos[1], pos[2]) {
            Ok((rep, tsv)) => {
                if let Some(out) = Self::flag_value(args, "--sssom") {
                    if let Err(e) = std::fs::write(&out, &tsv) {
                        return json!({"error": format!("could not write {out}: {e}")});
                    }
                    let mut r = rep;
                    r["sssom_written"] = json!(out);
                    return r;
                }
                rep
            }
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// Carry a crosswalk's claims into the target and look for a clash.
    ///
    /// The sharper question beside `crosswalk-certify`: not whether the two
    /// sides differ in granularity but whether the target's own axioms DENY
    /// something the mapping carries in. Its own stores, for the same reason
    /// as `crosswalk-certify`. Reports `exit_code: 1` when the mapping adds a
    /// clash, so a batch that runs it fails on a contradiction.
    fn exec_crosswalk_probe(args: &[String]) -> Value {
        let pos: Vec<&String> = args.iter().filter(|a| !a.starts_with("--")).collect();
        if pos.len() < 3 {
            return json!({"error": "crosswalk-probe needs SOURCE TARGET MAPPINGS.tsv"});
        }
        crate::crosswalk::probe_files(pos[0], pos[1], pos[2])
            .unwrap_or_else(|e| json!({"error": e.to_string()}))
    }

    /// Reason each module alone, then promote what k of n agree on.
    ///
    /// Modules are `NAME=FILE` pairs. Separate arguments rather than one
    /// merged graph, because the entire point is that no module's axioms
    /// answer another's questions.
    fn exec_modules(args: &[String]) -> Value {
        let k: usize = match Self::flag_value(args, "--threshold").map(|v| v.parse()) {
            Some(Ok(k)) => k,
            Some(Err(_)) => return json!({"error": "--threshold takes a whole number"}),
            None => return json!({"error": "modules needs --threshold k"}),
        };
        // `--threshold 2` is TWO arguments, so a naive "not a flag" filter reads
        // the 2 as a module name. Skip the value that follows a flag which
        // takes one.
        let mut positional: Vec<&String> = Vec::new();
        let mut skip = false;
        for a in args {
            if skip {
                skip = false;
                continue;
            }
            if a == "--threshold" {
                skip = true;
                continue;
            }
            if a.starts_with("--") {
                continue;
            }
            positional.push(a);
        }
        let mut mods = Vec::new();
        for a in positional {
            let Some((name, path)) = a.split_once('=') else {
                return json!({"error": format!("expected NAME=FILE, found {a}")});
            };
            match crate::graph::GraphStore::read_as_turtle(path) {
                Ok(ttl) => mods.push(crate::modules::Module {
                    name: name.to_string(),
                    ttl,
                }),
                Err(e) => return json!({"error": format!("{path}: {e}")}),
            }
        }
        match crate::modules::distributed(&mods, k) {
            Ok(v) => v,
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// Check a numeric claim. `matcert CERT.matcert` runs the Lean checker
    /// over a certificate somebody else wrote.
    fn exec_matcert(args: &[String]) -> Value {
        let Some(path) = args.iter().find(|a| !a.starts_with("--")) else {
            return json!({"error": "matcert needs a CERT.matcert path"});
        };
        let Some(bin) = crate::matcert::find_checker() else {
            return json!({
                "error": "oo-matcert was not found",
                "install": "run `lake build oo-matcert` in lean/, or set $OO_MATCERT",
                "means": "a missing checker is never an acceptance",
            });
        };
        let out = std::process::Command::new(&bin).arg(path).output();
        match out {
            Ok(o) => {
                let text = String::from_utf8_lossy(&o.stdout).to_string();
                serde_json::from_str(&text).unwrap_or_else(|_| json!({
                    "exit": o.status.code(),
                    "raw": text,
                }))
            }
            Err(e) => json!({"error": format!("{} could not be run: {e}", bin.display())}),
        }
    }

    /// Closed-world vocabulary check against the loaded ontology.
    ///
    /// This function existed and was never reachable: no arm of the dispatch
    /// match called it, so `batch` rejected `vocab-check` as an unknown command.
    /// That mattered more than an ordinary gap, because the check needs a loaded
    /// ontology, `load` does not persist in the default memory storage mode, and
    /// `batch` is the only way to load and then operate in one process. The
    /// command was therefore unreachable in its intended mode.
    fn exec_vocab_check(&self, args: &[String]) -> Value {
        let data_path = match args.iter().find(|a| !a.starts_with("--")) {
            Some(p) => p,
            None => return json!({"error": "vocab-check requires a data file path"}),
        };
        let extra: Vec<String> = Self::flag_value(args, "--namespaces")
            .map(|v| v.split(',').map(|s| s.trim().to_string()).collect())
            .unwrap_or_default();
        match crate::graph::GraphStore::read_as_turtle(data_path) {
            Ok(data) => {
                let result = crate::vocab_check::check_data_vocab(&self.graph, &data, &extra)
                    .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
                serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
            }
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_diff(&self, args: &[String]) -> Value {
        use crate::ontology::OntologyService;
        if args.len() < 2 {
            return json!({"error": "diff requires two file paths"});
        }
        let old = match std::fs::read_to_string(&args[0]) {
            Ok(s) => s,
            Err(e) => return json!({"error": format!("reading {}: {}", args[0], e)}),
        };
        let new = match std::fs::read_to_string(&args[1]) {
            Ok(s) => s,
            Err(e) => return json!({"error": format!("reading {}: {}", args[1], e)}),
        };
        let result = OntologyService::diff(&old, &new)
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    fn exec_convert(&self, args: &[String]) -> Value {
        if args.len() < 2 {
            return json!({"error": "convert requires: <path> --to <format> [--output <path>]"});
        }
        let path = &args[0];
        let to = Self::flag_value(args, "--to").unwrap_or_else(|| {
            if args.len() > 1 { args[1].clone() } else { "turtle".to_string() }
        });
        let output = Self::flag_value(args, "--output");
        if crate::ofn_writer::is_ofn_format(&to) {
            return match crate::ofn_writer::convert_file(path) {
                Ok(out) => {
                    let mut report = out.report_json();
                    if let Some(out_path) = output {
                        if let Err(e) = std::fs::write(&out_path, &out.text) {
                            return json!({"error": e.to_string()});
                        }
                        report["path"] = json!(out_path);
                    } else {
                        report["content_length"] = json!(out.text.len());
                    }
                    report["ok"] = json!(true);
                    report
                }
                Err(e) => json!({"error": e.to_string()}),
            };
        }
        let store = GraphStore::new();
        match store.load_file(path) {
            Ok(_) => match store.serialize(&to) {
                Ok(content) => {
                    if let Some(out_path) = output {
                        match std::fs::write(&out_path, &content) {
                            Ok(_) => json!({"ok": true, "path": out_path, "format": to}),
                            Err(e) => json!({"error": e.to_string()}),
                        }
                    } else {
                        json!({"ok": true, "format": to, "content_length": content.len()})
                    }
                }
                Err(e) => json!({"error": e.to_string()}),
            },
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_enforce(&self, args: &[String]) -> Value {
        let pack = args.first().map(|s| s.as_str()).unwrap_or("generic");
        let enforcer = crate::enforce::Enforcer::new(self.db.clone(), self.graph.clone());
        let result = enforcer.enforce_with_feedback(pack, Some(&self.db))
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    /// `unpack PATH [--verify-only] [--no-check] [--checker P] [--certificate-out D]
    /// [--load-even-if-refused]`
    ///
    /// Present so a batch script reaches the same verify-and-refuse loop the
    /// MCP tool does. `web/try/api/index.py` drives the engine in batch mode,
    /// so a route that exists only under MCP is a route that demo cannot show.
    /// `pack` has no arm here: the sender is already in a session, and the
    /// receiver is the party this feature is for.
    fn exec_unpack(&self, args: &[String]) -> Value {
        let Some(path) = args.first() else {
            return json!({"error": "unpack requires a pack path"});
        };
        let flag = |name: &str| args.iter().any(|a| a == name);
        let value = |name: &str| {
            args.iter()
                .position(|a| a == name)
                .and_then(|i| args.get(i + 1))
                .cloned()
        };
        let opts = crate::pack::UnpackOptions {
            verify_only: flag("--verify-only"),
            check_certificate: !flag("--no-check"),
            checker: value("--checker").map(std::path::PathBuf::from),
            certificate_out_dir: value("--certificate-out").map(std::path::PathBuf::from),
            load_even_if_refused: flag("--load-even-if-refused"),
        };
        match crate::pack::Packer::new(self.graph.clone()).unpack(path, &opts) {
            Ok(result) => serde_json::from_str(&result).unwrap_or(json!({"raw": result})),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_plan(&self, args: &[String]) -> Value {
        let file = match args.first() {
            Some(p) => p,
            None => return json!({"error": "plan requires a file path"}),
        };
        match std::fs::read_to_string(file) {
            Ok(turtle) => {
                let planner = crate::plan::Planner::new(self.db.clone(), self.graph.clone());
                // Conservativity ON by default, matching `onto_plan` and the
                // `plan` subcommand. There were THREE plan entry points and
                // flipping the default on one of them left the other two
                // answering a different question from the same word, which is
                // worse than leaving it off everywhere.
                let opts = (!args.iter().any(|a| a == "--no-conservativity")).then(|| {
                    crate::conservativity::ConservativityOptions {
                        mode: crate::conservativity::ExtensionMode::Replacement,
                        profile: "owl-rl".to_string(),
                        out: std::env::temp_dir()
                            .join(format!("oo-plan-conservativity-{}", std::process::id())),
                        scan_rows: 10_000,
                        max_rows: 1_000_000,
                    }
                });
                // The logic check (#336) is on by default for the same reason.
                let checks = crate::plan::PlanChecks {
                    conservativity: opts,
                    logic: !args.iter().any(|a| a == "--no-logic-check"),
                };
                let result = planner.plan_with(&turtle, checks)
                    .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
                serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
            }
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_apply(&self, args: &[String]) -> Value {
        let plan_id = Self::flag_value(args, "--plan-id");
        let mode = args
            .iter()
            .find(|a| !a.starts_with("--") && Some(a.as_str()) != plan_id.as_deref())
            .map(|s| s.as_str())
            .unwrap_or("safe");
        let planner = crate::plan::Planner::new(self.db.clone(), self.graph.clone());
        let result = planner.apply_plan(plan_id.as_deref(), mode)
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    fn exec_version(&self, args: &[String]) -> Value {
        use crate::ontology::OntologyService;
        let label = match args.first() {
            Some(l) => l,
            None => return json!({"error": "version requires a label"}),
        };
        let result = OntologyService::save_version(&self.db, &self.graph, label)
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    fn exec_history(&self) -> Value {
        use crate::ontology::OntologyService;
        let result = OntologyService::list_versions(&self.db)
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    fn exec_rollback(&self, args: &[String]) -> Value {
        use crate::ontology::OntologyService;
        let label = match args.first() {
            Some(l) => l,
            None => return json!({"error": "rollback requires a label"}),
        };
        let result = OntologyService::rollback_version(&self.db, &self.graph, label)
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    fn exec_status(&self) -> Value {
        json!({
            "status": "ok",
            "version": env!("CARGO_PKG_VERSION"),
            "triples_loaded": self.graph.triple_count(),
        })
    }

    async fn exec_pull(&self, args: &[String]) -> Value {
        let url = match args.first() {
            Some(u) => u,
            None => return json!({"error": "pull requires a URL"}),
        };
        let is_sparql = args.iter().any(|a| a == "--sparql");
        let content = if is_sparql {
            let q = Self::flag_value(args, "--query")
                .unwrap_or("CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }".to_string());
            match GraphStore::fetch_sparql(url, &q).await {
                Ok(c) => c,
                Err(e) => return json!({"error": e.to_string()}),
            }
        } else {
            match GraphStore::fetch_url(url).await {
                Ok(c) => c,
                Err(e) => return json!({"error": e.to_string()}),
            }
        };
        match self.graph.load_turtle(&content, None) {
            Ok(count) => json!({"ok": true, "triples_loaded": count, "source": url}),
            Err(e) => json!({"error": format!("Parse error: {}", e)}),
        }
    }

    fn exec_ingest(&self, args: &[String]) -> Value {
        use crate::ingest::DataIngester;
        use crate::mapping::MappingConfig;
        let path = match args.first() {
            Some(p) => p,
            None => return json!({"error": "ingest requires a data file path"}),
        };
        let base = Self::flag_value(args, "--base-iri")
            .unwrap_or("http://example.org/data/".to_string());
        let mapping_path = Self::flag_value(args, "--mapping");

        let rows = match DataIngester::parse_file(path) {
            Ok(r) => r,
            Err(e) => return json!({"error": e.to_string()}),
        };
        if rows.is_empty() {
            return json!({"ok": true, "triples_loaded": 0, "warnings": ["No data rows found"]});
        }

        let mapping_config = if let Some(ref mp) = mapping_path {
            match std::fs::read_to_string(mp) {
                Ok(content) => match serde_json::from_str::<MappingConfig>(&content) {
                    Ok(mc) => mc,
                    Err(e) => return json!({"error": format!("bad mapping: {}", e)}),
                },
                Err(e) => return json!({"error": e.to_string()}),
            }
        } else {
            let headers = DataIngester::extract_headers(&rows);
            MappingConfig::from_headers(&headers, &base, &format!("{}Thing", base))
        };

        let ntriples = mapping_config.rows_to_ntriples(&rows);
        match self.graph.load_ntriples(&ntriples) {
            Ok(count) => json!({"ok": true, "triples_loaded": count, "rows": rows.len()}),
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    /// `induce FILE [--base-iri B] [--class NAME] [--out DIR] [--no-load]`:
    /// one sheet in, one ontology out. Writes `ontology.ttl`, `shapes.ttl`,
    /// `mapping.json` and `induced.json` under `--out` when given, loads the
    /// ontology, the shapes and the rows into the store unless `--no-load`,
    /// and returns the report with the Turtle inline.
    fn exec_induce(&self, args: &[String]) -> Value {
        use crate::ingest::DataIngester;
        let path = match args.first().filter(|a| !a.starts_with("--")) {
            Some(p) => p.clone(),
            None => return json!({"error": "induce requires a data file path"}),
        };
        let base = Self::flag_value(args, "--base-iri").unwrap_or("http://example.org/data/".to_string());
        let source_stem = std::path::Path::new(&path).file_stem()
            .and_then(|s| s.to_str()).unwrap_or("Row").to_string();
        let stem = Self::flag_value(args, "--class").unwrap_or_else(|| source_stem.clone());
        let rows = match DataIngester::parse_file(&path) {
            Ok(r) => r,
            Err(e) => return json!({"error": e.to_string()}),
        };
        if rows.is_empty() {
            return json!({"error": "no data rows found; nothing to induce from"});
        }
        let headers = DataIngester::headers_in_order(&path, &rows);
        let induced = crate::induce::induce_with_source(&rows, &headers, &stem, &source_stem, &base);
        if let Some(out) = Self::flag_value(args, "--out") {
            let dir = std::path::Path::new(&out);
            if let Err(e) = std::fs::create_dir_all(dir)
                .and_then(|_| std::fs::write(dir.join("ontology.ttl"), &induced.ontology_ttl))
                .and_then(|_| std::fs::write(dir.join("shapes.ttl"), &induced.shapes_ttl))
                .and_then(|_| std::fs::write(dir.join("mapping.json"), serde_json::to_string_pretty(&induced.mapping).unwrap_or_default()))
                .and_then(|_| std::fs::write(dir.join("induced.json"), serde_json::to_string_pretty(&induced).unwrap_or_default()))
            {
                return json!({"error": format!("cannot write {out}: {e}")});
            }
        }
        let mut v = serde_json::to_value(&induced).unwrap_or_else(|e| json!({"error": e.to_string()}));
        if !args.iter().any(|a| a == "--no-load") {
            let loaded = self
                .graph
                .load_turtle(&induced.ontology_ttl, None)
                .and_then(|a| self.graph.load_turtle(&induced.shapes_ttl, None).map(|b| a + b))
                .and_then(|ab| self.graph.load_ntriples(&induced.instance_ntriples(&rows)).map(|c| (ab, c)));
            match loaded {
                Ok((schema, data)) => {
                    v["loaded"] = json!({"schema_triples": schema, "instance_triples": data});
                }
                Err(e) => return json!({"error": format!("induced, but loading failed: {e}")}),
            }
        }
        v["ok"] = json!(true);
        v
    }

    /// `certificate-check DIR [--valid-at T] [--as-of T] [--all-versions]`:
    /// is the certificate in DIR about the graph in this store?
    ///
    /// Issue #158. `oo-cert` verifies that the derivations follow from the
    /// assertions listed in the certificate. It cannot verify that those
    /// assertions are the ones in your database, because nothing in
    /// `asserted.tsv` says where the triples came from. This recomputes the
    /// digest of the assertions the loaded store yields and compares it with
    /// the one the run recorded.
    fn exec_certificate_check(&self, args: &[String]) -> Value {
        let dir = match args.first().filter(|a| !a.starts_with("--")) {
            Some(d) => d.clone(),
            None => return json!({"error": "certificate-check requires a certificate directory"}),
        };
        let request = match crate::temporal::ScopeRequest::from_args(
            Self::flag_value(args, "--valid-at").as_deref(),
            Self::flag_value(args, "--as-of").as_deref(),
            args.iter().any(|a| a == "--all-versions"),
        ) {
            Ok(r) => r,
            Err(e) => return json!({"error": e.to_string()}),
        };
        match crate::reason::certificate_binds_to_store(
            &self.graph,
            std::path::Path::new(&dir),
            &request,
        ) {
            Ok(mut v) => {
                v["dir"] = json!(dir);
                v["ok"] = json!(v["matches"].as_bool().unwrap_or(false));
                v
            }
            Err(e) => json!({"error": e.to_string()}),
        }
    }

    fn exec_drift(&self, args: &[String]) -> Value {
        if args.len() < 2 {
            return json!({"error": "drift requires two file paths"});
        }
        let v1 = match std::fs::read_to_string(&args[0]) {
            Ok(s) => s,
            Err(e) => return json!({"error": format!("reading {}: {}", args[0], e)}),
        };
        let v2 = match std::fs::read_to_string(&args[1]) {
            Ok(s) => s,
            Err(e) => return json!({"error": format!("reading {}: {}", args[1], e)}),
        };
        let detector = crate::drift::DriftDetector::new(self.db.clone());
        let result = detector.detect(&v1, &v2)
            .unwrap_or_else(|e| format!(r#"{{"error":"{}"}}"#, e));
        serde_json::from_str(&result).unwrap_or(json!({"raw": result}))
    }

    fn exec_lock(&self, args: &[String]) -> Value {
        if args.is_empty() {
            return json!({"error": "lock requires at least one IRI"});
        }
        let reason = Self::flag_value(args, "--reason").unwrap_or("locked".to_string());
        let planner = crate::plan::Planner::new(self.db.clone(), self.graph.clone());
        let iris: Vec<&str> = args.iter()
            .filter(|a| !a.starts_with("--") && *a != &reason)
            .map(|s| s.as_str())
            .collect();
        for iri in &iris {
            planner.lock_iri(iri, &reason);
        }
        json!({"ok": true, "locked": iris, "reason": reason})
    }

    fn exec_monitor(&self) -> Value {
        let monitor = crate::monitor::Monitor::new(self.db.clone(), self.graph.clone());
        let result = monitor.run_watchers();
        serde_json::to_value(&result).unwrap_or(json!({"error": "serialization failed"}))
    }

    fn exec_monitor_clear(&self) -> Value {
        let monitor = crate::monitor::Monitor::new(self.db.clone(), self.graph.clone());
        monitor.clear_blocked();
        json!({"ok": true, "message": "Monitor block cleared"})
    }

    async fn exec_marketplace(&self, args: &[String]) -> Value {
        use crate::marketplace;
        let action = match args.first() {
            Some(a) => a.as_str(),
            None => return json!({"error": "marketplace requires 'list' or 'install'"}),
        };
        match action {
            "list" => {
                let domain = Self::flag_value(args, "--domain");
                let (items, community_error) = marketplace::cli_list(domain.as_deref()).await;
                json!({
                    "count": items.len(),
                    "ontologies": items,
                    "community_registry_error": community_error,
                })
            }
            "install" => {
                let id = match Self::flag_value(args, "--id") {
                    Some(id) => id,
                    None => return json!({"error": "marketplace install requires --id"}),
                };
                let pack = match marketplace::cli_resolve(&id).await {
                    Ok(p) => p,
                    Err(e) => return json!({"error": e}),
                };
                let content = match crate::graph::GraphStore::fetch_url(&pack.url).await {
                    Ok(c) => c,
                    Err(e) => return json!({"error": e.to_string()}),
                };
                match self.graph.load_content_with_base(&content, pack.format, Some(&pack.url)) {
                    Ok(count) => {
                        let stats = self.graph.get_stats().unwrap_or_default();
                        json!({
                            "ok": true,
                            "installed": pack.id,
                            "name": pack.name,
                            "triples_loaded": count,
                            "stats": serde_json::from_str::<serde_json::Value>(&stats).unwrap_or_default(),
                        })
                    }
                    Err(e) => json!({"error": format!("Parse error: {}", e)}),
                }
            }
            _ => json!({"error": format!("Unknown marketplace action: '{}'. Use 'list' or 'install'.", action)}),
        }
    }

    // ─── Helpers ─────────────────────────────────────────────────────

    /// Extract --flag value from args (e.g. --format turtle → Some("turtle"))
    fn flag_value(args: &[String], flag: &str) -> Option<String> {
        args.iter()
            .position(|a| a == flag)
            .and_then(|i| args.get(i + 1).cloned())
    }

    /// Every value of a repeatable flag, in order (e.g. `--seed A --seed B`).
    ///
    /// `flag_value` returns the FIRST, which silently drops the rest. A seed
    /// list that lost all but its first element would produce a coverage proxy
    /// over one seed while the report said it was over twenty.
    fn flag_values(args: &[String], flag: &str) -> Vec<String> {
        args.iter()
            .enumerate()
            .filter(|(_, a)| a.as_str() == flag)
            .filter_map(|(i, _)| args.get(i + 1).cloned())
            .collect()
    }
}

/// Parse batch input — auto-detects JSON array vs line-per-command format.
fn parse_input(input: &str) -> Result<Vec<BatchCmd>, String> {
    let trimmed = input.trim();
    if trimmed.starts_with('[') {
        parse_json(trimmed)
    } else {
        parse_lines(trimmed)
    }
}

fn parse_json(input: &str) -> Result<Vec<BatchCmd>, String> {
    let arr: Vec<Value> = serde_json::from_str(input)
        .map_err(|e| format!("invalid JSON: {}", e))?;
    let mut cmds = Vec::new();
    for item in arr {
        let name = item["command"].as_str()
            .ok_or_else(|| "each JSON object must have a \"command\" field".to_string())?
            .to_string();
        // A bare string is the single positional argument. Without this the only
        // object form available was the flag-flattening branch below, which turns
        // {"args":{"path":"x.ttl"}} into ["--path","x.ttl"] and hands "--path" to a
        // command expecting a path. That broke every positional-argument command,
        // not only query.
        let args = if let Some(s) = item["args"].as_str() {
            vec![s.to_string()]
        } else if let Some(obj) = item["args"].as_object() {
            let mut flat = Vec::new();
            for (k, v) in obj {
                if v.is_boolean() {
                    if v.as_bool().unwrap_or(false) {
                        flat.push(format!("--{}", k));
                    }
                } else if let Some(s) = v.as_str() {
                    flat.push(format!("--{}", k));
                    flat.push(s.to_string());
                } else {
                    flat.push(format!("--{}", k));
                    flat.push(v.to_string());
                }
            }
            flat
        } else if let Some(arr) = item["args"].as_array() {
            arr.iter().filter_map(|v| v.as_str().map(|s| s.to_string())).collect()
        } else {
            Vec::new()
        };
        cmds.push(BatchCmd { name, args });
    }
    Ok(cmds)
}

/// Split a batch line into a command and its arguments.
///
/// Deliberately not `shell_words::split`. POSIX escaping treats `\` as an
/// escape character everywhere, which silently consumed every separator in a
/// Windows path: `plan C:\onto\proposed.ttl` arrived as `C:ontoproposed.ttl`,
/// the file was never found, and the failure surfaced somewhere else entirely
/// — `apply` reporting "No plan found" because the `plan` before it could not
/// read its input.
///
/// In a batch file a backslash is a path separator far more often than an
/// escape, so here it is literal outside quotes, and an escape only inside
/// double quotes and only before `"` or `\`. Single quotes are literal
/// throughout. Quoting still groups arguments containing spaces.
fn split_command_line(line: &str) -> Result<Vec<String>, String> {
    let mut words = Vec::new();
    let mut word = String::new();
    let mut started = false;
    let mut chars = line.chars().peekable();

    while let Some(c) = chars.next() {
        if c.is_whitespace() {
            if started {
                words.push(std::mem::take(&mut word));
                started = false;
            }
            continue;
        }
        started = true;
        match c {
            '\'' => loop {
                match chars.next() {
                    Some('\'') => break,
                    Some(c) => word.push(c),
                    None => return Err("unterminated single quote".to_string()),
                }
            },
            '"' => loop {
                match chars.next() {
                    Some('"') => break,
                    Some('\\') => match chars.peek() {
                        Some('"') | Some('\\') => word.push(chars.next().unwrap()),
                        _ => word.push('\\'),
                    },
                    Some(c) => word.push(c),
                    None => return Err("unterminated double quote".to_string()),
                }
            },
            c => word.push(c),
        }
    }

    if started {
        words.push(word);
    }
    Ok(words)
}

/// Commands whose argument is free text rather than a path or a flag. When such an
/// argument is not quoted it is taken from the line verbatim, because tokenising it
/// destroys it: an unquoted SPARQL query split on whitespace into a dozen fragments
/// and only the first, the bare word "SELECT", ever reached the engine. A quoted
/// argument still goes through the tokeniser, which has always handled it correctly.
const VERBATIM_ARG_COMMANDS: &[&str] = &["query"];

fn parse_lines(input: &str) -> Result<Vec<BatchCmd>, String> {
    let mut cmds = Vec::new();
    for line in input.lines() {
        let line = line.trim();
        if line.is_empty() || line.starts_with('#') {
            continue;
        }
        // Verbs whose single argument is free text must not be tokenised. A SPARQL
        // query splits on whitespace into a dozen useless fragments, and taking the
        // first of them handed the engine the bare word "SELECT". For these, the
        // remainder of the line after the verb is the argument, verbatim.
        let (verb, rest) = match line.find(char::is_whitespace) {
            Some(i) => (&line[..i], line[i..].trim()),
            None => (line, ""),
        };
        // A quoted argument was always handled correctly by the tokeniser, and
        // several tests pin that behaviour, so only an UNQUOTED remainder takes the
        // verbatim path. That is the case that was broken: an unquoted query was
        // split on whitespace and only its first fragment reached the engine.
        let rest_is_quoted = rest.starts_with('"') || rest.starts_with('\'');
        if VERBATIM_ARG_COMMANDS.contains(&verb) && !rest.is_empty() && !rest_is_quoted {
            cmds.push(BatchCmd {
                name: verb.to_string(),
                args: vec![rest.to_string()],
            });
            continue;
        }

        let words = split_command_line(line)
            .map_err(|e| format!("bad quoting on line '{}': {}", line, e))?;
        if words.is_empty() {
            continue;
        }
        cmds.push(BatchCmd {
            name: words[0].clone(),
            args: words[1..].to_vec(),
        });
    }
    Ok(cmds)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_lines() {
        let input = r#"
# comment
load my-ontology.ttl
stats
reason --profile owl-rl
query "SELECT (COUNT(*) AS ?c) WHERE { ?s ?p ?o }"
"#;
        let cmds = parse_lines(input).unwrap();
        assert_eq!(cmds.len(), 4);
        assert_eq!(cmds[0].name, "load");
        assert_eq!(cmds[0].args, vec!["my-ontology.ttl"]);
        assert_eq!(cmds[1].name, "stats");
        assert!(cmds[1].args.is_empty());
        assert_eq!(cmds[2].name, "reason");
        assert_eq!(cmds[2].args, vec!["--profile", "owl-rl"]);
        assert_eq!(cmds[3].name, "query");
        assert_eq!(cmds[3].args[0], "SELECT (COUNT(*) AS ?c) WHERE { ?s ?p ?o }");
    }

    #[test]
    fn a_windows_absolute_path_keeps_its_separators() {
        // `shell_words::split` applies POSIX escaping, so every backslash in a
        // Windows path was consumed before the file was ever opened: `oo batch`
        // could not load, plan against, or apply any absolute path on Windows.
        let cmds = parse_lines(r"plan C:\Users\runneradmin\Temp\ttl\proposed.ttl").unwrap();
        assert_eq!(cmds[0].name, "plan");
        assert_eq!(
            cmds[0].args,
            vec![r"C:\Users\runneradmin\Temp\ttl\proposed.ttl"]
        );
    }

    #[test]
    fn a_quoted_argument_keeps_its_spaces() {
        let cmds = parse_lines(r#"load "my ontology.ttl""#).unwrap();
        assert_eq!(cmds[0].args, vec!["my ontology.ttl"]);
    }

    #[test]
    fn a_quoted_windows_path_with_spaces_survives_both_hazards() {
        let cmds = parse_lines(r#"load "C:\Program Files\onto\my file.ttl""#).unwrap();
        assert_eq!(cmds[0].args, vec![r"C:\Program Files\onto\my file.ttl"]);
    }

    #[test]
    fn a_backslash_escapes_a_quote_inside_a_quoted_argument() {
        let cmds = parse_lines(r#"query "he said \"hi\"""#).unwrap();
        assert_eq!(cmds[0].args, vec![r#"he said "hi""#]);
    }

    #[test]
    fn single_quotes_take_their_contents_literally() {
        let cmds = parse_lines(r#"query 'C:\x\y "quoted"'"#).unwrap();
        assert_eq!(cmds[0].args, vec![r#"C:\x\y "quoted""#]);
    }

    #[test]
    fn an_unterminated_quote_is_an_error() {
        let err = parse_lines(r#"load "unfinished"#).unwrap_err();
        assert!(err.contains("quot"), "unexpected error: {err}");
    }

    #[test]
    fn test_parse_json() {
        let input = r#"[
            {"command": "load", "args": {"path": "test.ttl"}},
            {"command": "stats"},
            {"command": "reason", "args": {"profile": "owl-rl"}}
        ]"#;
        let cmds = parse_json(input).unwrap();
        assert_eq!(cmds.len(), 3);
        assert_eq!(cmds[0].name, "load");
        assert_eq!(cmds[1].name, "stats");
        assert_eq!(cmds[2].name, "reason");
    }

    #[test]
    fn test_auto_detect_json() {
        let json_input = r#"[{"command": "stats"}]"#;
        let line_input = "stats\nquery \"SELECT * WHERE { ?s ?p ?o }\"";
        assert!(parse_input(json_input).unwrap()[0].name == "stats");
        assert!(parse_input(line_input).unwrap()[0].name == "stats");
    }

    #[test]
    fn test_flag_value() {
        let args: Vec<String> = vec!["file.ttl", "--format", "ntriples", "--output", "out.nt"]
            .into_iter().map(String::from).collect();
        assert_eq!(BatchRunner::flag_value(&args, "--format"), Some("ntriples".to_string()));
        assert_eq!(BatchRunner::flag_value(&args, "--output"), Some("out.nt".to_string()));
        assert_eq!(BatchRunner::flag_value(&args, "--missing"), None);
    }
}

#[cfg(test)]
mod batch_query_parsing_tests {
    use super::*;

    // Regression tests for issue #100: a SPARQL query could not be executed in any
    // accepted batch input form.

    #[test]
    fn line_form_keeps_the_query_verbatim() {
        let cmds = parse_lines("query SELECT (COUNT(?s) AS ?n) WHERE { ?s ?p ?o }").unwrap();
        assert_eq!(cmds.len(), 1);
        assert_eq!(cmds[0].name, "query");
        assert_eq!(cmds[0].args.len(), 1, "the query must arrive as one argument, not tokenised");
        assert_eq!(cmds[0].args[0], "SELECT (COUNT(?s) AS ?n) WHERE { ?s ?p ?o }");
    }

    #[test]
    fn line_form_preserves_quotes_and_braces_inside_a_query() {
        let q = r#"SELECT ?s WHERE { ?s <http://example.org/p> "a literal with spaces" }"#;
        let cmds = parse_lines(&format!("query {}", q)).unwrap();
        assert_eq!(cmds[0].args[0], q);
    }

    #[test]
    fn json_string_args_is_a_single_positional() {
        let cmds = parse_json(r#"[{"command":"query","args":"SELECT ?s WHERE { ?s ?p ?o }"}]"#).unwrap();
        assert_eq!(cmds[0].args, vec!["SELECT ?s WHERE { ?s ?p ?o }".to_string()]);
    }

    #[test]
    fn json_string_args_works_for_paths_too() {
        // The object form flattens to --key value, which handed "--path" to load.
        let cmds = parse_json(r#"[{"command":"load","args":"data/graph.ttl"}]"#).unwrap();
        assert_eq!(cmds[0].args, vec!["data/graph.ttl".to_string()]);
    }

    #[test]
    fn json_array_args_still_works() {
        let cmds = parse_json(r#"[{"command":"query","args":["SELECT ?s WHERE { ?s ?p ?o }"]}]"#).unwrap();
        assert_eq!(cmds[0].args, vec!["SELECT ?s WHERE { ?s ?p ?o }".to_string()]);
    }

    #[test]
    fn non_verbatim_commands_are_still_tokenised() {
        // Only free-text verbs bypass tokenisation; paths and flags must not.
        let cmds = parse_lines("lint ontology.ttl --strict").unwrap();
        assert_eq!(cmds[0].name, "lint");
        assert_eq!(cmds[0].args, vec!["ontology.ttl".to_string(), "--strict".to_string()]);
    }

    #[test]
    fn windows_paths_survive_as_before() {
        // Guards the backslash behaviour documented on split_command_line.
        let cmds = parse_lines(r"plan C:\onto\proposed.ttl").unwrap();
        assert_eq!(cmds[0].args[0], r"C:\onto\proposed.ttl");
    }

    #[test]
    fn bare_query_verb_yields_a_helpful_error_not_a_panic() {
        let cmds = parse_lines("query").unwrap();
        assert_eq!(cmds[0].name, "query");
        assert!(cmds[0].args.is_empty());
    }
}