Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
A one-shot reason runs on the budgets config.toml sets, and a flag can override them for one run
FABIOTESSd6b32b1319ca
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ad73c3aa..b027b315 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -44,8 +44,39 @@ All notable changes to Open Ontologies are documented here.`tests/shacl_validation_report_w3c_test.rs` with their causes, which includean `sh:or` false negative on IRI and ill-typed values.+- **`reason --phase-timeout-ms` and `--classify-timeout-ms`** (#339). They set+ the two `owl-dl` wall clocks for one run, in milliseconds, with `0` meaning+ no limit, as in `config.toml`. The precedence is the flag, then `[reasoner]`+ in `<data-dir>/config.toml`, then the default (10 000 and 180 000). No+ environment variable sets either clock. The `budget` block reports the+ values in force. A daemon fixes its clocks when it starts, and it serves+ every client from one process. For that reason a `reason` that carries+ either flag is never proxied. While a daemon is up, the command exits 1 and+ names `--no-connect`, because a local run would read a different store from+ the graph the daemon holds. In memory mode, that local store is empty.+### Fixed+- **One-shot CLI commands honour `[reasoner]` and the rest of+ `<data-dir>/config.toml`** (#339). `setup()` loaded the file and kept only+ `[storage]`. `runtime::init_from_config` ran only in `serve`, `serve-http`+ and `serve-unix`. So `reason --profile owl-dl` always ran with a 10 000 ms+ phase budget and a 180 000 ms ceiling, whatever the file said. Its `budget`+ block then reported those defaults as the configuration. `setup()` now calls+ `init_from_config` with the config it already loads. That function only+ stores atomics, and it overwrites them, so it loads no model and can safely+ run again. The same change applies `[cache]`, `[feedback]`, `[repo]`,+ `[imports]`, `[webhook]` and `[language]` to one-shot commands and `batch`.+ The servers already applied them. MEASURED with+ `tests/cli_reasoner_config_test.rs`: on main 9e73d951, a config of+ `tableaux_test_timeout_ms = 200` reported `phase_timeout_ms: 10000`. It now+ reports 200. A proxied run is unchanged, because `daemon start` passes+ `<data-dir>/config.toml` to `serve-http`. Measured on this branch, a+ proxied run reported 200 and 60 000 from the file. One committed artifact+ shows the bug: `docs/assets/hqdm/owl-dl.json` names+ `tableaux_test_timeout_ms = 120000` in its `source`, but its `budget` block+ reports 10000 and 180000.+- **`diff` and `drift` no longer hang on a symmetric blank-node graph** (#293).Both canonicalised blank nodes through oxrdf's RDFC-1.0, which sets no limiton `hash_n_degree_quads` calls, so the cost was factorial: a 7-nodediff --git a/docs/quickstart.md b/docs/quickstart.mdindex c645bc86..97ca67c5 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -54,6 +54,8 @@ open-ontologies query "SELECT ?class WHERE { ?class a owl:Class }" --pretty# Run SHIQ tableaux reasoningopen-ontologies reason --profile owl-dl+# ...with a 30 s budget per phase for this run (overrides [reasoner] in config.toml)+open-ontologies reason --profile owl-dl --phase-timeout-ms 30000# Semantic search (requires a build with --features embeddings)open-ontologies init # on an embeddings build, downloads a 448 MB ONNX model and a 16 MB tokenizerdiff --git a/docs/reasoning.md b/docs/reasoning.mdindex 0d28e362..dfe3154c 100644--- a/docs/reasoning.md+++ b/docs/reasoning.md@@ -62,6 +62,33 @@ measurements are in| `onto_dl_explain` | Explain why a class is unsatisfiable (clash trace) || `onto_dl_check` | Check if one class is subsumed by another |+## Time budgets for `owl-dl`++An `owl-dl` run has two wall clocks. The phase budget bounds each of its five+phases (consistency, satisfiability, subsumption, ABox, explanation). The+ceiling bounds the whole run. `0` means no limit for either clock. Every+`owl-dl` report carries a `budget` block. It gives the values in force and+names the bound that actually stops the run.++| Setting | CLI flag (`reason`) | `[reasoner]` key in `config.toml` | Default |+| ------- | ------------------- | --------------------------------- | ------- |+| Phase budget | `--phase-timeout-ms` | `tableaux_test_timeout_ms` | 10000 |+| Ceiling | `--classify-timeout-ms` | `classify_timeout_ms` | 180000 |++The precedence is the flag, then the config file, then the default. No+environment variable sets either clock. One-shot CLI commands read+`<data-dir>/config.toml`, and the servers read the file given to `--config`.+Before #339, one-shot commands ignored `[reasoner]` and always reported the+defaults.++A running daemon fixes both clocks when it starts, from the `config.toml` in its+data directory. A proxied `reason` uses those values. A request cannot change+them, because the clocks are process-wide and the daemon serves every client.+For that reason, a `reason` that carries either flag is never proxied. If a+daemon is running, that command is refused. Pass `--no-connect` to run it+against the data directory's own store, or change `[reasoner]` and restart the+daemon.+## Which graphs a run readsBy default, all of them: the default graph and every named graph, flattened.diff --git a/src/main.rs b/src/main.rsindex 9b2c2c31..a7185d49 100644--- a/src/main.rs+++ b/src/main.rs@@ -142,6 +142,9 @@ data_dir = "~/.open-ontologies"# cannot be the bound that fires: 5 x 10000 = 50000, well under 180000. Lower it# below that to make it the binding one. Every `owl-dl` run reports which of the# two is binding, in `budget.binding_bound`, with a sentence saying why.+# One-shot CLI commands read this section from <data-dir>/config.toml, and+# `reason --phase-timeout-ms` / `--classify-timeout-ms` override it for one run+# (CLI > config > default; no env var). A daemon reads it once, at start.# [feedback]# Lint / enforce self-calibration thresholds (number of dismissals before@@ -538,6 +541,20 @@ enum Commands {/// refused together with --valid-at or --as-of.#[arg(long)]all_versions: bool,+ /// `owl-dl` only: wall-clock budget for one PHASE of the run, in+ /// milliseconds. `0` means no limit. CLI > `[reasoner]+ /// tableaux_test_timeout_ms` in `<data-dir>/config.toml` > 10000. No+ /// environment variable sets it. The run's `budget` block reports the+ /// value in force. Never proxied: a running daemon fixes its budgets+ /// at start, so with one up this is refused unless --no-connect.+ #[arg(long, value_name = "MS")]+ phase_timeout_ms: Option<usize>,+ /// `owl-dl` only: wall-clock CEILING for the whole run, in+ /// milliseconds. `0` means no ceiling. CLI > `[reasoner]+ /// classify_timeout_ms` in `<data-dir>/config.toml` > 180000. No+ /// environment variable sets it. Never proxied, as --phase-timeout-ms.+ #[arg(long, value_name = "MS")]+ classify_timeout_ms: Option<usize>,},/// Export the loaded ontology as first-order logic, for a prover or a model finder///@@ -1085,7 +1102,16 @@ impl Commands {valid_at,as_of,all_versions,+ phase_timeout_ms,+ classify_timeout_ms,} => {+ // The reasoner clocks are process-wide, and the daemon serves+ // every client from one process. A per-request budget would leak+ // into concurrent and later runs, so the batch handler takes+ // none, and the command stays local (see `daemon_refuses`).+ if phase_timeout_ms.is_some() || classify_timeout_ms.is_some() {+ return None;+ }let mut a = vec!["--profile".into(), profile.clone()];if let Some(c) = certificate {a.push("--certificate".into());@@ -1453,18 +1479,52 @@ impl Commands {/// false — so there is one copy now, and one place where the decision to proxy/// is made.async fn proxy_if_daemon(ctx: &ProxyCtx, input: &str, bail: bool) -> anyhow::Result<Option<i32>> {- if ctx.no_connect {- return Ok(None);- }- let Some(info) = open_ontologies::daemon::read_daemon_info(&ctx.data_dir) else {+ let Some(info) = live_daemon(ctx) else {return Ok(None);};+ open_ontologies::connect::proxy_batch(&info, input, bail, json_mode(), ctx.pretty).await+}++/// The daemon a proxy-able command would be sent to, if any: `None` under+/// `--no-connect`, with no daemon.json, or when the recorded PID is dead.+fn live_daemon(ctx: &ProxyCtx) -> Option<open_ontologies::daemon::DaemonInfo> {+ if ctx.no_connect {+ return None;+ }+ let info = open_ontologies::daemon::read_daemon_info(&ctx.data_dir)?;if !open_ontologies::daemon::is_daemon_alive(info.pid) {// Stale daemon.json — clean up silently and fall through to local.open_ontologies::daemon::remove_daemon_info(&ctx.data_dir);- return Ok(None);+ return None;+ }+ Some(info)+}++/// Why a command that is normally proxied cannot be run while `info`'s daemon+/// is up, or `None` when it can be run (proxied or locally).+///+/// `to_batch_command` keeps a command local when it carries a flag the batch+/// handler cannot honour. For most commands that is enough. For `reason` it is+/// not: the graph the caller loaded lives in the daemon, so a local run reads a+/// different store (an empty one in memory mode) and answers about the wrong+/// data while looking like a success. Refusing says so instead.+fn daemon_refuses(cmd: &Commands, info: &open_ontologies::daemon::DaemonInfo) -> Option<String> {+ match cmd {+ Commands::Reason { phase_timeout_ms, classify_timeout_ms, .. }+ if phase_timeout_ms.is_some() || classify_timeout_ms.is_some() =>+ {+ Some(format!(+ "reason --phase-timeout-ms / --classify-timeout-ms cannot be sent to the running \+ daemon (pid {}). Its reasoner budgets are fixed when it starts, from [reasoner] in \+ its data directory's config.toml, and one request may not change them for every \+ other client. A local run would read this process's own store, not the graph the \+ daemon holds. Pass --no-connect to reason over the local store, or set [reasoner] \+ and restart the daemon.",+ info.pid+ ))+ }+ _ => None,}- open_ontologies::connect::proxy_batch(&info, input, bail, json_mode(), ctx.pretty).await}/// The parts of `Cli` the proxy needs, taken before `cli.command` is matched by@@ -1517,11 +1577,21 @@ fn setup(data_dir: &str) -> anyhow::Result<(StateDb, Arc<GraphStore>)> {// server modes (loaded from `<data_dir>/config.toml` if present). This is// what makes `open-ontologies load foo.ttl` + `open-ontologies query ...`// share state when persistence is enabled.+ //+ // The rest of the file applies too (#339). Only `[storage]` used to be kept,+ // and `runtime::init_from_config` ran in the three server modes alone, so a+ // one-shot `reason --profile owl-dl` ran on the default reasoner budgets+ // whatever `[reasoner]` said, and its `budget` block reported those defaults+ // as though they were the configuration. `init_from_config` only stores+ // atomics (reasoner caps and clocks, cache prefix, feedback thresholds, repo+ // list limit, imports policy, webhook timeout, preferred languages): it loads+ // no model and opens nothing, so it is as cheap here as at server start, and+ // it overwrites rather than latches, so calling it on every one-shot command+ // is safe.let cfg_path = data_path.join("config.toml");- let storage_cfg = open_ontologies::config::Config::load(&cfg_path)- .map(|c| c.storage)- .unwrap_or_default();- let graph = build_main_graph(&storage_cfg, data_path)?;+ let cfg = open_ontologies::config::Config::load(&cfg_path).unwrap_or_default();+ open_ontologies::runtime::init_from_config(&cfg);+ let graph = build_main_graph(&cfg.storage, data_path)?;Ok((db, graph))}@@ -1933,6 +2003,11 @@ async fn async_main() -> anyhow::Result<()> {if let Some(code) = proxy_if_daemon(&proxy_ctx, &payload, false).await? {std::process::exit(code);}+ } else if let Some(info) = live_daemon(&proxy_ctx)+ && let Some(why) = daemon_refuses(&cli.command, &info)+ {+ output_result_checked(&serde_json::json!({ "error": why }).to_string(), cli.pretty);+ return Ok(());}match cli.command {@@ -3314,9 +3389,21 @@ async fn async_main() -> anyhow::Result<()> {valid_at,as_of,all_versions,+ phase_timeout_ms,+ classify_timeout_ms,} => {use open_ontologies::reason::{InferenceTarget, Reasoner};+ // `setup` applies `[reasoner]` from config.toml; a flag then wins+ // over it, the same CLI > config > default order as --storage-mode+ // (neither clock has an environment variable). The `budget` block+ // reads these same globals, so it reports what is in force.let (_db, graph) = setup(&cli.data_dir)?;+ if let Some(ms) = phase_timeout_ms {+ open_ontologies::runtime::set_tableaux_test_timeout_ms(ms);+ }+ if let Some(ms) = classify_timeout_ms {+ open_ontologies::runtime::set_classify_timeout_ms(ms);+ }let request = match open_ontologies::temporal::ScopeRequest::from_args(valid_at.as_deref(),as_of.as_deref(),@@ -4115,6 +4202,36 @@ mod proxy_serialization_tests {assert!(without.to_batch_command().is_some());}+ #[test]+ fn a_reasoner_budget_flag_is_never_proxied_and_a_live_daemon_refuses_it() {+ // #339. The clocks are process-wide in the daemon, so a per-request+ // budget cannot be honoured there; and a local run would read a+ // different store from the one the caller loaded into the daemon.+ let reason = |phase: Option<usize>, ceiling: Option<usize>| Commands::Reason {+ profile: "owl-dl".into(),+ certificate: None,+ rules: None,+ valid_at: None,+ as_of: None,+ all_versions: false,+ phase_timeout_ms: phase,+ classify_timeout_ms: ceiling,+ };+ let info = open_ontologies::daemon::DaemonInfo {+ pid: 4242,+ url: "http://127.0.0.1:8080".into(),+ token: None,+ };+ for cmd in [reason(Some(200), None), reason(None, Some(0)), reason(Some(1), Some(2))] {+ assert!(cmd.to_batch_command().is_none());+ let why = daemon_refuses(&cmd, &info).expect("a live daemon must refuse it");+ assert!(why.contains("--no-connect") && why.contains("4242"), "{why}");+ }+ let plain = reason(None, None);+ assert!(plain.to_batch_command().is_some());+ assert!(daemon_refuses(&plain, &info).is_none());+ }+/// One instance of every variant `to_batch_command` will proxy. If a new/// proxy-able command is added and not listed here it simply goes uncovered;/// nothing here passes falsely because of it.@@ -4126,11 +4243,11 @@ mod proxy_serialization_tests {Commands::Stats,Commands::Query { query: "SELECT ?s WHERE { ?s ?p ?o }".into() },Commands::Lint { input: "x.ttl".into() },- Commands::Reason { profile: "rdfs".into(), certificate: None, rules: None, valid_at: None, as_of: None, all_versions: false },+ Commands::Reason { profile: "rdfs".into(), certificate: None, rules: None, valid_at: None, as_of: None, all_versions: false, phase_timeout_ms: None, classify_timeout_ms: None },// The scoped form proxies too: a daemon-backed `reason --valid-at`// that silently dropped the flag would run over every version and// report a snapshot it did not have.- Commands::Reason { profile: "rdfs".into(), certificate: None, rules: None, valid_at: Some("2026-01-01".into()), as_of: None, all_versions: false },+ Commands::Reason { profile: "rdfs".into(), certificate: None, rules: None, valid_at: Some("2026-01-01".into()), as_of: None, all_versions: false, phase_timeout_ms: None, classify_timeout_ms: None },Commands::Fol { out: "/tmp/fol".into(), format: "tptp".into(), smt_domain: None, clif_dialect: "iso".into(), clif_comments: "standalone".into(), goals: None, goals_skip_columns: 0 },Commands::FolModel { out: "/tmp/folmodel".into(), solver: "z3".into(), max_domain: 16, timeout_secs: 30, unbounded_probe: true, goals: None, goals_skip_columns: 0, checker: None },Commands::FolProve { out: Some("/tmp/folprove".into()), prover: "vampire".into(), timeout_secs: 30, goals: None, goals_skip_columns: 0, problem: None, proof: None },diff --git a/tests/cli_reasoner_config_test.rs b/tests/cli_reasoner_config_test.rsnew file mode 100644index 00000000..4503a7ec--- /dev/null+++ b/tests/cli_reasoner_config_test.rs@@ -0,0 +1,123 @@+//! One-shot CLI commands honour `[reasoner]` in `<data-dir>/config.toml` (#339).+//!+//! `setup()` loaded `config.toml` and kept only its `[storage]` section, and+//! `runtime::init_from_config` was called by the three server modes alone. So+//! `open-ontologies reason --profile owl-dl` ran with the default budgets whatever+//! the file said, and its `budget` block reported those defaults as though they+//! were the configuration. The same file passed to `serve --config` was honoured.+//!+//! These tests read the `budget` block of a real `owl-dl` run, because that block+//! is what a reader is told is in force.++mod common;++use std::path::Path;+use std::process::Command;++const ONTOLOGY: &str = r#"+@prefix owl: <http://www.w3.org/2002/07/owl#> .+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .+@prefix ex: <http://ex.org/> .+ex:Animal a owl:Class .+ex:Dog a owl:Class ; rdfs:subClassOf ex:Animal .+"#;++/// Every invocation shares one persistent store under `dir/data`, so the `load`+/// in one process is what the next process reasons over. `--no-connect` keeps a+/// developer's running daemon out of it.+fn run(dir: &Path, args: &[&str]) -> (i32, String) {+ let out = {+ let _gate = common::exec_gate();+ Command::new(env!("CARGO_BIN_EXE_open-ontologies"))+ .env("OPEN_ONTOLOGIES_STORAGE_MODE", "persistent")+ .arg("--data-dir")+ .arg(dir.join("data"))+ .arg("--no-connect")+ .args(args)+ .output()+ .expect("binary should run")+ };+ let text = format!(+ "{}{}",+ String::from_utf8_lossy(&out.stdout),+ String::from_utf8_lossy(&out.stderr)+ );+ (out.status.code().unwrap_or(-1), text)+}++/// A store whose config.toml carries `reasoner` as its `[reasoner]` section, with+/// the small ontology above already loaded.+fn loaded_store(reasoner: &str) -> tempfile::TempDir {+ let d = tempfile::tempdir().unwrap();+ let data = d.path().join("data");+ std::fs::create_dir_all(&data).unwrap();+ std::fs::write(+ data.join("config.toml"),+ format!("[storage]\nmode = 'persistent'\n\n[reasoner]\n{reasoner}"),+ )+ .unwrap();+ let ttl = d.path().join("o.ttl");+ std::fs::write(&ttl, ONTOLOGY).unwrap();+ let (code, out) = run(d.path(), &["load", ttl.to_str().unwrap()]);+ assert_eq!(code, 0, "load must succeed: {out}");+ d+}++/// The `budget` block of an `owl-dl` run with `extra` appended to the command.+fn budget(dir: &Path, extra: &[&str]) -> serde_json::Value {+ let mut args = vec!["reason", "--profile", "owl-dl"];+ args.extend_from_slice(extra);+ let (code, out) = run(dir, &args);+ assert_eq!(code, 0, "reason must succeed: {out}");+ let line = out+ .lines()+ .find(|l| l.trim_start().starts_with('{'))+ .unwrap_or_else(|| panic!("no JSON in the output: {out}"));+ let v: serde_json::Value = serde_json::from_str(line).expect("reason prints JSON");+ v.get("budget")+ .cloned()+ .unwrap_or_else(|| panic!("owl-dl output has no budget block: {v}"))+}++#[test]+fn reason_reports_the_budgets_set_in_config_toml() {+ let d = loaded_store("tableaux_test_timeout_ms = 200\nclassify_timeout_ms = 60000\n");+ let b = budget(d.path(), &[]);+ assert_eq!(b["phase_timeout_ms"], 200, "config phase budget ignored: {b}");+ assert_eq!(b["classify_timeout_ms"], 60000, "config ceiling ignored: {b}");+ // 5 phases x 200 ms = 1000 ms, under the 60 000 ms ceiling.+ assert_eq!(b["phase_worst_case_ms"], 1000, "{b}");+ assert_eq!(b["binding_bound"], "phase", "{b}");+}++#[test]+fn reason_flags_override_config_toml() {+ let d = loaded_store("tableaux_test_timeout_ms = 200\nclassify_timeout_ms = 60000\n");++ let b = budget(+ d.path(),+ &["--phase-timeout-ms", "300", "--classify-timeout-ms", "700"],+ );+ assert_eq!(b["phase_timeout_ms"], 300, "flag must beat config: {b}");+ assert_eq!(b["classify_timeout_ms"], 700, "flag must beat config: {b}");+ // 5 x 300 = 1500 > 700, so the ceiling is now the bound that fires.+ assert_eq!(b["binding_bound"], "global", "{b}");++ // One flag alone leaves the other at its configured value, not the default.+ let b = budget(d.path(), &["--phase-timeout-ms", "400"]);+ assert_eq!(b["phase_timeout_ms"], 400, "{b}");+ assert_eq!(b["classify_timeout_ms"], 60000, "unflagged ceiling must stay configured: {b}");++ // 0 means no limit, as it does in config.toml.+ let b = budget(d.path(), &["--phase-timeout-ms", "0"]);+ assert!(b["phase_timeout_ms"].is_null(), "0 must mean no phase limit: {b}");+ assert_eq!(b["classify_timeout_ms"], 60000, "{b}");+}++#[test]+fn reason_without_config_or_flags_reports_the_defaults() {+ let d = loaded_store("");+ let b = budget(d.path(), &[]);+ assert_eq!(b["phase_timeout_ms"], 10_000, "{b}");+ assert_eq!(b["classify_timeout_ms"], 180_000, "{b}");+}