Merge branch 'fix/336-341-plan-defects' into land/oo-2026-10-28

# Conflicts:
#	CHANGELOG.md

Author: fabio-rovai

CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to Open Ontologies are documented here.
 
 ### Added
 
+- **A plan says whether the change breaks the ontology, and scores it `high`
+  when it does** (#336, reported by @jpsanchezcalypso). `risk_score` came from
+  removal counts alone, so a change that made a named class unsatisfiable (R1:
+  `Manager ⊑ Person ⊑ Agent`, `Manager ⊥ Agent`) or the ABox inconsistent (R2:
+  `Machine ⊥ Person`, `alice a Machine` where `alice a Person`) removed nothing
+  and scored `low`. `plan`, `batch` `plan` and `onto_plan` now carry a `logic`
+  block through one function (`Planner::plan_with`): `new_defects`, the
+  `defects` findings the store did not have, and `abox_consistent`, the owl-dl
+  tableaux on the proposed graph under the `[reasoner]` budget, with
+  `abox_consistent_before` for the store when the proposed graph is
+  inconsistent. A new error- or warning-severity defect, or an inconsistency
+  the store was not proven to have, sets `risk_score` to `high`, and the new
+  `risk_reasons` says why. A check that ran out of budget, or a graph using a
+  construct the tableaux does not model, reports `abox_consistent: null` with
+  the reason, never `true`. On by default; `--no-logic-check` (CLI, `batch`) or
+  `check_logic: false` (`onto_plan`) skips it and the block says
+  `not_checked`. `apply` is unchanged and does not gate on the verdict, and the
+  exit code of `plan` is unchanged (1 on an error only), as it already was for
+  a `high` score from removals; `docs/lifecycle.md` says so. R1 and R2 now plan
+  `high` on all four entry points; the benign control stays `low`.
+- **`defects` says how many classes are affected, and its 50-a-kind listing
+  can be lifted** (#341). `defect_count` counts findings, one per query row,
+  and for `inherited_disjoint` a row is a (class, disjoint pair), so a class
+  under two disjoint pairs counted twice and the headline ran higher than the
+  reasoner's list of unsatisfiable classes with nothing saying why. The report
+  now carries `affected_classes` and `affected_properties` (distinct subjects)
+  beside it, and `kind_counts` gives `findings` and the affected count for each
+  of the eight kinds. `defects --limit N` on the CLI and `limit` on
+  `onto_defects` set the per-kind listing bound (default 50, `0` lists every
+  row), and `truncated` names a kind only when the bound in force cut it. On
+  the issue's reproduction: `defect_count` 2, `affected_classes` 1; with 80
+  classes under one disjoint pair, `--limit 0` lists all 80.
 - **`onto_convert`, the CLI `convert` and `batch` `convert` write OWL 2
   functional syntax (`--to ofn`)** (requested by @noahgift in #322). #311 gave
   the engine an OFN reader and no writer, so handing an ontology to the OWL
@@ -141,6 +173,17 @@ All notable changes to Open Ontologies are documented here.
   sites and cannot error. W3C `core/property/or-datatypes-001` reports 3 of 3
   violations where it reported 1: full-tuple column 51 to 52 PASS, report
   match 48 to 49 of 56, gated column unchanged at 61.
+
+- **`batch` runs `defects`** (#336). It had no arm, so `batch` answered
+  `{"error":"unknown batch command: 'defects'"}`, and so did the CLI `defects`
+  whenever a daemon was up, since the CLI proxies it there. `defects [path]
+  [--limit N]` checks the file alone, or the batch's own store when no path is
+  given. The proxy coverage test now lists `defects`. The local CLI `defects`
+  checked its file inside the main store, so under persistent storage it
+  judged the file together with whatever the store held and left the file's
+  triples behind in it; it now uses a store of its own, as the proxied form
+  does. No other MCP-only check (`onto_dlp_boundary`, `onto_dl_check`) is a CLI
+  command, so none is proxied and none was given a batch arm.
 - **`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

README.md

@@ -118,8 +118,9 @@ the part that survives examination.
 > **This is not an ontology editor.** Use Protégé to draw class hierarchies. You
 > run Open Ontologies on the change, before the change goes to production.
 >
-> **The tool is like Terraform, and this is on purpose. But the plan is semantic,
-> not syntactic.** A text diff is `git diff`, and you have `git diff` already.
+> **The tool is like Terraform, and this is on purpose. But the plan checks what a
+> change means and what it breaks, not only its text.** A text diff is `git diff`,
+> and you have `git diff` already.
 
 You do not need a JVM. You do not need Protégé. The engine speaks MCP to Claude,
 to Cursor, and to other clients of that protocol.

README.zh-CN.md

@@ -110,7 +110,7 @@ new consequences      901          rule table owl-rl, in 0.04s
 > **这不是一个本体编辑器。**要绘制类层次结构，请使用 Protégé。你在变更进入生产环境之前，
 > 对这次变更运行 Open Ontologies。
 >
-> **本工具在风格上类似 Terraform，这是刻意为之。但是这里的计划是语义层面的，不是语法层面的。**
+> **本工具在风格上类似 Terraform，这是刻意为之。但是这里的计划检查变更的含义以及它会破坏什么，而不只是检查文本。**
 > 文本差异就是 `git diff`，而你已经有 `git diff` 了。
 
 你不需要 JVM。你不需要 Protégé。引擎通过 MCP 与 Claude、Cursor 以及该协议的其他客户端通信。

docs/lifecycle.md

@@ -33,24 +33,55 @@ therefore survive the process that computed them: `plan` and `apply` are
 separate CLI invocations and separate MCP calls, and neither shares memory with
 the other. The 100 most recent plans are retained.
 
-### Conservativity: the one part of a plan that is about meaning
+### Conservativity: what the change means
 
 Everything above is about SHAPE. A change that adds one `rdfs:domain` triple adds
 no class, removes nothing, has a blast radius of zero and scores `low`, while
-retyping every existing individual of that property. Pass
-`check_conservativity: true` and the plan also reports whether the change alters
-any consequence over the names the store already uses, with the rule and the
-premises the base lacked behind every row.
-
-It is opt-in because it reasons both graphs to a fixpoint, and when it is off the
-`conservativity` block is still there and reads `ran: false` with the reason: a
-missing block and a clean block look the same to a dashboard. It is never fatal;
-a check that cannot run leaves `conservativity.skipped` set and the plan is still
-returned. The verdict is a WORD rather than a boolean, and it is conservativity
-with respect to a Horn rule table rather than in a description logic, which
+retyping every existing individual of that property. The `conservativity` block
+reports whether the change alters any consequence over the names the store
+already uses, with the rule and the premises the base lacked behind every row.
+
+It is on by default since #196 and costs a fixpoint over both graphs; skip it with
+`--no-conservativity` (CLI and `batch`) or `check_conservativity: false`
+(`onto_plan`). When it is off the `conservativity` block is still there and reads
+`ran: false` with the reason: a missing block and a clean block look the same to a
+dashboard. It is never fatal; a check that cannot run leaves
+`conservativity.skipped` set and the plan is still returned. The verdict is a WORD
+rather than a boolean, and it is conservativity with respect to a Horn rule table
+rather than in a description logic, which
 [docs/modules-and-conservativity.md](modules-and-conservativity.md) states in
 full.
 
+### Logic: what the change breaks
+
+Conservativity does not see a change that breaks the ontology. Adding
+`Manager rdfs:subClassOf Person` and `Manager owl:disjointWith Agent`, where
+every `Person` is an `Agent`, leaves `Manager` with no possible instance; adding
+`Machine owl:disjointWith Person` and `alice a Machine`, where `alice` is a
+`Person`, makes the ABox inconsistent. Both remove nothing and both used to score
+`low` (#336). The `logic` block answers this, relative to the store, so a defect
+the store already had is never charged to the change:
+
+| field | meaning |
+|---|---|
+| `new_defects` | findings of the eight `defects` kinds in the proposed graph that the store did not have; `null` if the check could not run |
+| `new_defects_by_severity`, `new_defect_findings` | the same, by severity, and listed (at most 50) |
+| `abox_consistent` | the owl-dl tableaux on the proposed graph: `false` on a clash it found, `true` only when the search finished and the graph uses no construct the tableaux does not model, otherwise `null` |
+| `abox_consistent_before` | the same question of the store, asked only when the proposed graph is inconsistent; `null` otherwise |
+| `checked_by`, `reason` | what ran, and in words why each answer is what it is; `not_checked` when skipped |
+
+A new `error` or `warning` defect, or an inconsistency the store was not proven to
+have, sets `risk_score` to `high`, and `risk_reasons` says which. An `info`
+finding is listed and does not move the score. The consistency half runs under
+the `[reasoner]` budget (`tableaux_test_timeout_ms` per phase, under
+`classify_timeout_ms`), and a run that exhausts it reports `null` with the reason,
+never `true`. Skip the whole block with `--no-logic-check` or
+`check_logic: false`.
+
+The exit code of `plan` does not change with the verdict: it is 1 on an error and
+0 otherwise, as it always was for a `high` score from removals. A pipeline gates
+on `risk_score` or `logic`.
+
 ## Enforce
 
 Design pattern checks. Built-in packs: `generic` (orphan classes, missing labels), `boro` (IES4/BORO compliance), `value_partition` (disjointness). Custom SPARQL rules supported.
@@ -60,6 +91,12 @@ Design pattern checks. Built-in packs: `generic` (orphan classes, missing labels
 Two modes: `safe` (write the delta) or `migrate` (same, plus
 owl:equivalentClass/Property bridges for consumers).
 
+Apply does not re-judge the plan. It applies a plan whatever its `risk_score` or
+`logic` block said, and the only gate is the monitor (`force` skips that too). A
+change that removes terms on purpose has always been applicable at `high`, and an
+apply that began refusing on a field it never read would break the pipelines
+built on it without a word.
+
 Apply writes only the triples that differ, so an unchanged graph costs nothing
 and a one-instance change touches one triple. `strategy` reports `delta`, or
 `reload` when blank nodes are present anywhere in either graph: bnode labels are

src/batch.rs

@@ -126,6 +126,7 @@ impl BatchRunner {
             "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),
@@ -281,6 +282,51 @@ impl BatchRunner {
         }
     }
 
+    /// `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")
@@ -960,7 +1006,12 @@ impl BatchRunner {
                         max_rows: 1_000_000,
                     }
                 });
-                let result = planner.plan_checked(&turtle, opts)
+                // 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}))
             }