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.

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.md
index 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 include
an `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 limit
on `hash_n_degree_quads` calls, so the cost was factorial: a 7-node
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 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 reasoning
open-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 tokenizer
diff --git a/docs/reasoning.md b/docs/reasoning.md
index 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 reads
By default, all of them: the default graph and every named graph, flattened.
diff --git a/src/main.rs b/src/main.rs
index 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.rs
new file mode 100644
index 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}");
+}