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.

feat: add hierarchy enforce rule pack — detects flat hierarchies

FABIOTESS83d0f7701906
diff --git a/CLAUDE.md b/CLAUDE.md
index fbc917cd..f12b3a69 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -75,7 +75,7 @@ Claude dynamically decides the next tool call based on what the previous tool re
| `onto_apply` | After plan + enforce — applies changes in `safe` or `migrate` mode |
| `onto_lock` | To protect production IRIs from removal |
| `onto_drift` | To compare two versions — rename detection, drift velocity, self-calibrating confidence |
-| `onto_enforce` | After loading — design pattern checks: `generic`, `boro`, `value_partition`, or custom rules |
+| `onto_enforce` | After loading — design pattern checks: `generic`, `boro`, `value_partition`, `hierarchy`, or custom rules |
| `onto_monitor` | After apply — run SPARQL watchers with threshold alerts. Watchers with `webhook_url` POST alerts to external systems (Slack, PagerDuty, etc.) |
| `onto_monitor_clear` | To clear blocked state after resolving monitor alerts |
| `onto_crosswalk` | To look up clinical terminology mappings (ICD-10 ↔ SNOMED ↔ MeSH) |
@@ -104,7 +104,7 @@ When evolving an ontology in production, follow this Terraform-style cycle. Clau
### Enforce
-4. Call `onto_enforce` with a rule pack (`generic`, `boro`, `value_partition`) — checks design pattern compliance
+4. Call `onto_enforce` with a rule pack (`generic`, `boro`, `value_partition`, `hierarchy`) — checks design pattern compliance
5. Fix any violations before applying
### Apply
diff --git a/src/enforce.rs b/src/enforce.rs
index 0136339b..1a16491d 100644
--- a/src/enforce.rs
+++ b/src/enforce.rs
@@ -29,6 +29,7 @@ impl Enforcer {
"generic" => self.run_generic_rules(&mut violations, &mut total_rules, &mut passed_rules),
"boro" => self.run_boro_rules(&mut violations, &mut total_rules, &mut passed_rules),
"value_partition" => self.run_value_partition_rules(&mut violations, &mut total_rules, &mut passed_rules),
+ "hierarchy" => self.run_hierarchy_rules(&mut violations, &mut total_rules, &mut passed_rules),
_ => {}
}
@@ -280,6 +281,201 @@ impl Enforcer {
}
}
+ fn run_hierarchy_rules(&self, violations: &mut Vec<serde_json::Value>, total: &mut u32, passed: &mut u32) {
+ // Rule 1: Flat hierarchy — classes with too many direct children (>5)
+ // These are candidates for intermediate grouping classes.
+ *total += 1;
+ let flat_query = "SELECT ?parent (COUNT(DISTINCT ?child) AS ?count) WHERE { \
+ ?child <http://www.w3.org/2000/01/rdf-schema#subClassOf> ?parent . \
+ ?child a ?type . \
+ FILTER(?type IN (<http://www.w3.org/2002/07/owl#Class>, <http://www.w3.org/2000/01/rdf-schema#Class>)) \
+ } GROUP BY ?parent HAVING (COUNT(DISTINCT ?child) > 5) ORDER BY DESC(?count)";
+
+ let flat_parents = self.query_flat_hierarchy(flat_query);
+ if flat_parents.is_empty() {
+ *passed += 1;
+ } else {
+ for (parent, count, children) in &flat_parents {
+ violations.push(serde_json::json!({
+ "rule": "flat_hierarchy",
+ "severity": "info",
+ "entity": parent,
+ "message": format!(
+ "Flat hierarchy: {} has {} direct children. Consider adding intermediate grouping classes to deepen the subClassOf chain and improve RDFS inference. Children: {}",
+ parent, count, children.join(", ")
+ ),
+ "children_count": count,
+ "children": children,
+ }));
+ }
+ }
+
+ // Rule 2: Shallow max depth — hierarchy should be at least 3 levels deep
+ *total += 1;
+ let depth_query = "SELECT (MAX(?depth) AS ?max_depth) WHERE { \
+ SELECT ?class (COUNT(?ancestor) AS ?depth) WHERE { \
+ ?class <http://www.w3.org/2000/01/rdf-schema#subClassOf>+ ?ancestor . \
+ } GROUP BY ?class \
+ }";
+
+ if let Ok(json) = self.graph.sparql_select(depth_query)
+ && let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json)
+ && let Some(results) = parsed["results"].as_array()
+ && let Some(first) = results.first()
+ && let Some(depth_str) = first["max_depth"].as_str()
+ {
+ let depth: f64 = depth_str
+ .split('"')
+ .nth(1)
+ .unwrap_or(depth_str)
+ .parse()
+ .unwrap_or(0.0);
+ if depth >= 3.0 {
+ *passed += 1;
+ } else {
+ violations.push(serde_json::json!({
+ "rule": "shallow_hierarchy",
+ "severity": "warning",
+ "entity": "graph",
+ "message": format!(
+ "Shallow hierarchy: max depth is {:.0}. Ontologies with deeper hierarchies produce richer RDFS inference. Consider adding intermediate grouping classes.",
+ depth
+ ),
+ "max_depth": depth,
+ }));
+ }
+ } else {
+ *passed += 1; // Can't determine depth — don't penalize
+ }
+
+ // Rule 3: Low average depth — average should be above 2.0
+ *total += 1;
+ let avg_query = "SELECT (AVG(?depth) AS ?avg_depth) WHERE { \
+ SELECT ?class (COUNT(?ancestor) AS ?depth) WHERE { \
+ ?class <http://www.w3.org/2000/01/rdf-schema#subClassOf>+ ?ancestor . \
+ } GROUP BY ?class \
+ }";
+
+ if let Ok(json) = self.graph.sparql_select(avg_query)
+ && let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json)
+ && let Some(results) = parsed["results"].as_array()
+ && let Some(first) = results.first()
+ && let Some(avg_str) = first["avg_depth"].as_str()
+ {
+ let avg: f64 = avg_str
+ .split('"')
+ .nth(1)
+ .unwrap_or(avg_str)
+ .parse()
+ .unwrap_or(0.0);
+ if avg >= 2.0 {
+ *passed += 1;
+ } else {
+ violations.push(serde_json::json!({
+ "rule": "low_avg_depth",
+ "severity": "info",
+ "entity": "graph",
+ "message": format!(
+ "Low average hierarchy depth: {:.2}. An average above 2.0 indicates well-structured intermediate groupings that produce richer RDFS inference.",
+ avg
+ ),
+ "avg_depth": avg,
+ }));
+ }
+ } else {
+ *passed += 1;
+ }
+
+ // Rule 4: RDFS inference potential — estimate inferred triples vs raw
+ *total += 1;
+ let raw_query = "SELECT (COUNT(*) AS ?count) WHERE { ?s ?p ?o }";
+ let subclass_query = "SELECT (COUNT(*) AS ?count) WHERE { \
+ ?s <http://www.w3.org/2000/01/rdf-schema#subClassOf> ?o \
+ }";
+
+ let raw_count = self.query_count(raw_query);
+ let subclass_count = self.query_count(subclass_query);
+
+ if raw_count > 0 {
+ let ratio = subclass_count as f64 / raw_count as f64;
+ if ratio >= 0.05 {
+ // At least 5% of triples are subClassOf — good hierarchy density
+ *passed += 1;
+ } else {
+ violations.push(serde_json::json!({
+ "rule": "low_hierarchy_density",
+ "severity": "info",
+ "entity": "graph",
+ "message": format!(
+ "Low hierarchy density: only {:.1}% of triples are rdfs:subClassOf ({} of {}). Dense hierarchies drive richer RDFS inference.",
+ ratio * 100.0, subclass_count, raw_count
+ ),
+ "subclass_count": subclass_count,
+ "total_triples": raw_count,
+ "density_pct": ratio * 100.0,
+ }));
+ }
+ } else {
+ *passed += 1;
+ }
+ }
+
+ fn query_flat_hierarchy(&self, query: &str) -> Vec<(String, u64, Vec<String>)> {
+ let mut results = Vec::new();
+ if let Ok(json) = self.graph.sparql_select(query)
+ && let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json)
+ && let Some(rows) = parsed["results"].as_array()
+ {
+ for row in rows {
+ let parent = row["parent"]
+ .as_str()
+ .unwrap_or("")
+ .trim_matches(|c| c == '<' || c == '>')
+ .to_string();
+ let count: u64 = row["count"]
+ .as_str()
+ .unwrap_or("0")
+ .split('"')
+ .nth(1)
+ .unwrap_or("0")
+ .parse()
+ .unwrap_or(0);
+
+ // Get the children names
+ let children_query = format!(
+ "SELECT ?child WHERE {{ ?child <http://www.w3.org/2000/01/rdf-schema#subClassOf> <{}> }}",
+ parent
+ );
+ let children = self.query_iris(&children_query, "child");
+ let short_children: Vec<String> = children
+ .iter()
+ .map(|c| c.rsplit_once('#').or(c.rsplit_once('/')).map(|(_, n)| n.to_string()).unwrap_or(c.clone()))
+ .collect();
+
+ results.push((parent, count, short_children));
+ }
+ }
+ results
+ }
+
+ fn query_count(&self, query: &str) -> u64 {
+ if let Ok(json) = self.graph.sparql_select(query)
+ && let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json)
+ && let Some(results) = parsed["results"].as_array()
+ && let Some(first) = results.first()
+ && let Some(count_str) = first["count"].as_str()
+ {
+ count_str
+ .split('"')
+ .nth(1)
+ .unwrap_or(count_str)
+ .parse()
+ .unwrap_or(0)
+ } else {
+ 0
+ }
+ }
+
fn run_custom_rules(&self, rule_pack: &str, violations: &mut Vec<serde_json::Value>, total: &mut u32, passed: &mut u32) {
let conn = self.db.conn();
let mut stmt = conn