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
//! FLORA-style fuzzy-logic alignment adjudication (#38).
//!
//! Per the ISWC 2025 paper "FLORA: Fuzzy Logic Over Relational Alignments,"
//! this implements:
//!
//! - **A 10-rule Mamdani fuzzy inference system** over four input signals
//! (label Jaccard, parent overlap, sibling overlap, datatype overlap)
//! plus structural penalties.
//! - **Triangular membership functions** for each signal (low / medium /
//! high) with overlapping boundaries.
//! - **Three t-norms** for the AND aggregator (Gödel / product /
//! Łukasiewicz).
//! - **Centroid defuzzification** producing a crisp `[0, 1]` score.
//! - **Auditable rule trace** so a reviewer can see which rules fired and
//! with what activation strength.
//!
//! The architectural pivot recorded in project memory: HNSW is demoted to
//! a *candidate generator*; FLORA is the final-decision layer for the
//! pairs HNSW surfaces. Embedding-free and interpretable — every accept
//! decision is traceable back to the specific rules that fired.
use serde::{Deserialize, Serialize};
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
pub struct FuzzySignals {
/// Token Jaccard over labels in `[0, 1]`.
pub label_jaccard: f64,
/// Fraction of parents shared in `[0, 1]`.
pub parent_overlap: f64,
/// Fraction of siblings shared in `[0, 1]`.
pub sibling_overlap: f64,
/// Fraction of datatype properties shared in `[0, 1]`.
pub datatype_overlap: f64,
}
#[derive(Clone, Copy, Debug, Deserialize, Serialize, Default, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum TNorm {
/// `min(a, b)` — Gödel.
#[default]
Min,
/// `a * b` — product / probabilistic.
Product,
/// `max(0, a + b - 1)` — Łukasiewicz.
Lukasiewicz,
}
#[derive(Clone, Debug, Serialize)]
pub struct FuzzyDecision {
pub fuzzy_score: f64,
pub verdict: String,
/// Activation strength per rule (firing strength × consequent peak).
pub rule_activations: Vec<RuleFiring>,
pub rule_trace: Vec<String>,
}
#[derive(Clone, Debug, Serialize)]
pub struct RuleFiring {
pub rule_id: u32,
pub firing_strength: f64,
pub consequent: String,
}
// ─── Triangular membership functions ────────────────────────────────────────
//
// For each input signal, three fuzzy sets: low, medium, high. The
// triangles overlap at ~0.4 and ~0.7 so the rule base is continuous
// (no dead zones).
/// Membership in the "low" fuzzy set: peak 0.0, falls to 0 at 0.4.
fn mu_low(x: f64) -> f64 {
if x <= 0.0 { 1.0 }
else if x >= 0.4 { 0.0 }
else { 1.0 - x / 0.4 }
}
/// Membership in the "medium" fuzzy set: peak at 0.5, supports [0.2, 0.8].
fn mu_medium(x: f64) -> f64 {
if x <= 0.2 || x >= 0.8 { 0.0 }
else if x <= 0.5 { (x - 0.2) / 0.3 }
else { (0.8 - x) / 0.3 }
}
/// Membership in the "high" fuzzy set: rises from 0 at 0.6, peaks at 1.0.
fn mu_high(x: f64) -> f64 {
if x <= 0.6 { 0.0 }
else if x >= 1.0 { 1.0 }
else { (x - 0.6) / 0.4 }
}
// ─── Output fuzzy sets (verdict) ────────────────────────────────────────────
//
// Three output sets centred on 0.15, 0.5, 0.9 representing reject /
// borderline / accept.
const OUT_REJECT_PEAK: f64 = 0.15;
const OUT_BORDERLINE_PEAK: f64 = 0.5;
const OUT_ACCEPT_PEAK: f64 = 0.9;
// ─── Rule base (10 rules per the FLORA paper) ───────────────────────────────
#[derive(Clone, Copy, Debug)]
enum OutLabel {
Reject,
Borderline,
Accept,
}
impl OutLabel {
fn peak(self) -> f64 {
match self {
Self::Reject => OUT_REJECT_PEAK,
Self::Borderline => OUT_BORDERLINE_PEAK,
Self::Accept => OUT_ACCEPT_PEAK,
}
}
fn name(self) -> &'static str {
match self {
Self::Reject => "reject",
Self::Borderline => "borderline",
Self::Accept => "accept",
}
}
}
/// Combine two membership values under a t-norm (used for `AND` in
/// antecedents).
fn tnorm(a: f64, b: f64, t: TNorm) -> f64 {
match t {
TNorm::Min => a.min(b),
TNorm::Product => a * b,
TNorm::Lukasiewicz => (a + b - 1.0).max(0.0),
}
}
/// Combine n membership values under a t-norm.
fn tnorm_n(values: &[f64], t: TNorm) -> f64 {
if values.is_empty() {
return 0.0;
}
values[1..]
.iter()
.copied()
.fold(values[0], |acc, x| tnorm(acc, x, t))
.clamp(0.0, 1.0)
}
/// Evaluate the 10-rule FLORA inference base. Returns per-rule firing
/// strength + output consequent.
fn evaluate_rules(s: &FuzzySignals, t: TNorm) -> Vec<(u32, f64, OutLabel)> {
let l_hi = mu_high(s.label_jaccard);
let l_mid = mu_medium(s.label_jaccard);
let l_lo = mu_low(s.label_jaccard);
let p_hi = mu_high(s.parent_overlap);
let p_mid = mu_medium(s.parent_overlap);
let p_lo = mu_low(s.parent_overlap);
let sb_hi = mu_high(s.sibling_overlap);
let _sb_mid = mu_medium(s.sibling_overlap); // reserved for future rules
let d_hi = mu_high(s.datatype_overlap);
let _d_mid = mu_medium(s.datatype_overlap); // reserved for future rules
let d_lo = mu_low(s.datatype_overlap);
vec![
// R1: high label ∧ high parent → accept (strong textual+structural agreement).
(1, tnorm(l_hi, p_hi, t), OutLabel::Accept),
// R2: high label ∧ medium parent → accept (textual carries most of the weight).
(2, tnorm(l_hi, p_mid, t), OutLabel::Accept),
// R3: high label ∧ high datatype → accept (textual + same datatype properties).
(3, tnorm(l_hi, d_hi, t), OutLabel::Accept),
// R4: high parent ∧ high sibling ∧ high datatype → accept (pure structural).
(4, tnorm_n(&[p_hi, sb_hi, d_hi], t), OutLabel::Accept),
// R5: medium label ∧ high parent ∧ high sibling → borderline (struct without text).
(5, tnorm_n(&[l_mid, p_hi, sb_hi], t), OutLabel::Borderline),
// R6: medium label ∧ medium parent → borderline.
(6, tnorm(l_mid, p_mid, t), OutLabel::Borderline),
// R7: high label ∧ low parent ∧ low datatype → borderline (text but no structure).
(7, tnorm_n(&[l_hi, p_lo, d_lo], t), OutLabel::Borderline),
// R8: low label ∧ low parent → reject (no evidence).
(8, tnorm(l_lo, p_lo, t), OutLabel::Reject),
// R9: low label → reject (FLORA paper: label disagreement penalises strongly).
(9, l_lo, OutLabel::Reject),
// R10: low datatype ∧ medium label → reject (datatype mismatch is structural penalty).
(10, tnorm(d_lo, l_mid, t), OutLabel::Reject),
]
}
/// Centroid defuzzification: weighted average of output peaks by firing
/// strength.
fn defuzzify(firings: &[(u32, f64, OutLabel)]) -> f64 {
let mut num = 0.0_f64;
let mut den = 0.0_f64;
for (_, w, label) in firings {
num += *w * label.peak();
den += *w;
}
if den == 0.0 {
0.5 // total ambiguity — neutral
} else {
num / den
}
}
/// Adjudicate a candidate pair via the full FLORA fuzzy inference system.
pub fn adjudicate(
signals: &FuzzySignals,
tnorm: TNorm,
low_threshold: f64,
high_threshold: f64,
) -> FuzzyDecision {
let firings = evaluate_rules(signals, tnorm);
let fuzzy_score = defuzzify(&firings);
let verdict = if fuzzy_score >= high_threshold {
"accept"
} else if fuzzy_score >= low_threshold {
"borderline"
} else {
"reject"
}
.to_string();
let rule_activations: Vec<RuleFiring> = firings
.iter()
.filter(|(_, w, _)| *w > 1e-6)
.map(|(id, w, lbl)| RuleFiring {
rule_id: *id,
firing_strength: *w,
consequent: lbl.name().to_string(),
})
.collect();
let mut trace: Vec<String> = vec![
format!("inference: 10-rule Mamdani over signals {:?}, t-norm: {:?}", signals, tnorm),
];
for f in &rule_activations {
trace.push(format!(
"R{} fired @ {:.3} → {}",
f.rule_id, f.firing_strength, f.consequent
));
}
trace.push(format!(
"centroid defuzzification → score = {:.3}",
fuzzy_score
));
trace.push(format!(
"verdict: {} (thresholds: low={:.3}, high={:.3})",
verdict, low_threshold, high_threshold
));
FuzzyDecision {
fuzzy_score,
verdict,
rule_activations,
rule_trace: trace,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn s(l: f64, p: f64, sb: f64, d: f64) -> FuzzySignals {
FuzzySignals {
label_jaccard: l,
parent_overlap: p,
sibling_overlap: sb,
datatype_overlap: d,
}
}
#[test]
fn tnorm_n_combines_each_value_once() {
// Min is idempotent so it hides a double-count; Product and Lukasiewicz expose it.
// Three equal 0.75 inputs under Product must be 0.75^3, not 0.75^4.
assert!((tnorm_n(&[0.75, 0.75, 0.75], TNorm::Product) - 0.421875).abs() < 1e-9);
// Product of three distinct values combines each exactly once.
assert!((tnorm_n(&[0.5, 0.4, 0.2], TNorm::Product) - 0.04).abs() < 1e-9);
// Lukasiewicz chain over three 0.8 inputs: max(0,1.6-1)=0.6 then max(0,1.4-1)=0.4.
assert!((tnorm_n(&[0.8, 0.8, 0.8], TNorm::Lukasiewicz) - 0.4).abs() < 1e-9);
// Single value is itself under every t-norm; empty is 0.
assert_eq!(tnorm_n(&[0.6], TNorm::Product), 0.6);
assert_eq!(tnorm_n(&[], TNorm::Product), 0.0);
}
#[test]
fn membership_triangles_have_expected_peaks() {
assert!((mu_low(0.0) - 1.0).abs() < 1e-9);
assert_eq!(mu_low(0.5), 0.0);
assert!((mu_medium(0.5) - 1.0).abs() < 1e-9);
assert!((mu_high(1.0) - 1.0).abs() < 1e-9);
assert_eq!(mu_high(0.5), 0.0);
}
#[test]
fn strong_match_accepts() {
let d = adjudicate(&s(0.95, 0.9, 0.8, 0.7), TNorm::Min, 0.4, 0.7);
assert_eq!(d.verdict, "accept");
assert!(d.fuzzy_score >= 0.7);
// R1 must have fired.
assert!(d.rule_activations.iter().any(|r| r.rule_id == 1));
}
#[test]
fn strong_mismatch_rejects() {
let d = adjudicate(&s(0.05, 0.1, 0.1, 0.1), TNorm::Min, 0.4, 0.7);
assert_eq!(d.verdict, "reject");
assert!(d.fuzzy_score <= 0.4);
// R8 or R9 must have fired.
assert!(d.rule_activations.iter().any(|r| r.rule_id == 8 || r.rule_id == 9));
}
#[test]
fn moderate_label_borderline() {
let d = adjudicate(&s(0.5, 0.5, 0.3, 0.3), TNorm::Min, 0.4, 0.7);
assert_eq!(d.verdict, "borderline");
}
#[test]
fn rule_trace_records_firings_and_defuzz() {
let d = adjudicate(&s(0.7, 0.7, 0.5, 0.5), TNorm::Min, 0.4, 0.7);
assert!(d.rule_trace.iter().any(|s| s.contains("Mamdani")));
assert!(d.rule_trace.iter().any(|s| s.contains("centroid")));
assert!(d.rule_trace.iter().any(|s| s.contains("verdict")));
}
#[test]
fn datatype_only_penalises_under_r10() {
// Medium label + extreme datatype mismatch should fire R10 → reject leaning.
let d = adjudicate(&s(0.5, 0.1, 0.1, 0.0), TNorm::Min, 0.4, 0.7);
assert!(d.rule_activations.iter().any(|r| r.rule_id == 10),
"R10 should fire on low-datatype + medium-label; got: {:?}", d.rule_activations);
}
#[test]
fn product_tnorm_strictly_dampens_versus_min() {
let signals = s(0.7, 0.7, 0.5, 0.5);
let d_min = adjudicate(&signals, TNorm::Min, 0.4, 0.7);
let d_prod = adjudicate(&signals, TNorm::Product, 0.4, 0.7);
// Product reduces firing strengths; centroid leans more toward 0.5.
assert!(d_prod.fuzzy_score != d_min.fuzzy_score,
"product and min should produce different scores");
}
#[test]
fn defuzzification_returns_neutral_05_when_no_rules_fire() {
// All inputs in the "dead zone" — but our overlapping triangles
// mean some rule fires for any [0,1] input. Use truly empty firings.
let firings: Vec<(u32, f64, OutLabel)> = vec![];
assert_eq!(defuzzify(&firings), 0.5);
}
#[test]
fn high_structural_alone_can_still_accept_via_r4() {
// High parent + sibling + datatype, low label → R4 accept rule.
let d = adjudicate(&s(0.1, 0.9, 0.9, 0.9), TNorm::Min, 0.4, 0.7);
// R4 fires, but R9 (low label → reject) also fires strongly.
// Net score should be in the borderline-to-reject region, not accept.
assert!(d.fuzzy_score < 0.7,
"low-label should not yield strong accept even with structure; got {}",
d.fuzzy_score);
}
#[test]
fn fully_neutral_signals_yield_borderline() {
let d = adjudicate(&s(0.5, 0.5, 0.5, 0.5), TNorm::Min, 0.4, 0.7);
assert_eq!(d.verdict, "borderline");
}
}