Skip to main content

qualia_core_db/sparql_library/
kernel_extensions.rs

1//! Qualia kernel SPARQL extension functions (UE-052).
2//!
3//! Scalar numeric helpers callable as `q42:mean`, `q42:gini`, … from FILTER /
4//! BIND. Fail closed on empty / non-finite input. Not a substitute for the
5//! receipted WASM welfare surface — these are query-local scalars.
6
7use crate::q_hash;
8
9/// Recognised kernel extension functions.
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum KernelFn {
12    Mean,
13    Min,
14    Max,
15    Sum,
16    Gini,
17    Rawlsian,
18}
19
20const IRIS: &[(&str, KernelFn)] = &[
21    ("q42:mean", KernelFn::Mean),
22    ("https://webizen.org/ns/q42#mean", KernelFn::Mean),
23    ("q42:min", KernelFn::Min),
24    ("https://webizen.org/ns/q42#min", KernelFn::Min),
25    ("q42:max", KernelFn::Max),
26    ("https://webizen.org/ns/q42#max", KernelFn::Max),
27    ("q42:sum", KernelFn::Sum),
28    ("https://webizen.org/ns/q42#sum", KernelFn::Sum),
29    ("q42:gini", KernelFn::Gini),
30    ("https://webizen.org/ns/q42#gini", KernelFn::Gini),
31    ("q42:rawlsian", KernelFn::Rawlsian),
32    ("https://webizen.org/ns/q42#rawlsian", KernelFn::Rawlsian),
33];
34
35/// Resolve a function IRI hash to a kernel op.
36pub fn kernel_fn_for_hash(iri_hash: u64) -> Option<KernelFn> {
37    for &(iri, op) in IRIS {
38        if q_hash(iri) == iri_hash {
39            return Some(op);
40        }
41    }
42    None
43}
44
45/// Evaluate a kernel extension over float arguments.
46pub fn eval_kernel_fn(op: KernelFn, args: &[f64]) -> Result<f64, String> {
47    if args.is_empty() {
48        return Err("q42 kernel function requires at least one numeric argument".into());
49    }
50    if args.iter().any(|x| !x.is_finite()) {
51        return Err("q42 kernel function: non-finite argument".into());
52    }
53    match op {
54        KernelFn::Mean => Ok(args.iter().sum::<f64>() / args.len() as f64),
55        KernelFn::Min => Ok(args.iter().copied().fold(f64::INFINITY, f64::min)),
56        KernelFn::Max => Ok(args.iter().copied().fold(f64::NEG_INFINITY, f64::max)),
57        KernelFn::Sum => Ok(args.iter().sum()),
58        KernelFn::Rawlsian => Ok(args.iter().copied().fold(f64::INFINITY, f64::min)),
59        KernelFn::Gini => gini(args),
60    }
61}
62
63fn gini(incomes: &[f64]) -> Result<f64, String> {
64    if incomes.iter().any(|v| *v < 0.0) {
65        return Err("q42:gini: negative income".into());
66    }
67    let n = incomes.len();
68    let mut sum = 0.0f64;
69    let mut total = 0.0f64;
70    for &yi in incomes {
71        total += yi;
72        for &yj in incomes {
73            sum += (yi - yj).abs();
74        }
75    }
76    if total <= 0.0 {
77        return Err("q42:gini: all-zero incomes".into());
78    }
79    let mean = total / n as f64;
80    Ok(sum / (2.0 * n as f64 * n as f64 * mean))
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    #[test]
88    fn mean_and_gini_basic() {
89        assert!((eval_kernel_fn(KernelFn::Mean, &[1.0, 2.0, 3.0]).unwrap() - 2.0).abs() < 1e-12);
90        let g = eval_kernel_fn(KernelFn::Gini, &[0.0, 1.0]).unwrap();
91        assert!((g - 0.5).abs() < 1e-12);
92    }
93
94    #[test]
95    fn hash_lookup_stable() {
96        assert_eq!(kernel_fn_for_hash(q_hash("q42:mean")), Some(KernelFn::Mean));
97        assert_eq!(kernel_fn_for_hash(q_hash("q42:nope")), None);
98    }
99}