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
//! CIVeX-style causal certificate for state-changing ontology actions (#42).
//!
//! A scaffold port of the verifier described in **CIVeX: Causal Intervention
//! Verification for Language Agents** (Rovai, arXiv 2605.09168). The original
//! paper gates LLM-agent tool calls: it maps a proposed action to a structural
//! causal query `E[Y | do(t_v = t*)]`, checks identifiability under a committed
//! graph, computes a one-sided lower confidence bound on the do-effect, and
//! returns one of four auditable verdicts: EXECUTE / REJECT / EXPERIMENT /
//! ABSTAIN, each carrying a causal certificate.
//!
//! This module ports the structural shape to ontology operations: every state-
//! changing `onto_*` tool (apply / save / push / ingest / enrich) can be wrapped
//! in `certify_action` to obtain a verdict + certificate before executing.
//!
//! ## Scaffold scope vs paper
//!
//! What's faithful:
//!
//! - The four-way verdict.
//! - The certificate as an auditable JSON artefact: structural-graph slice
//! hash, labelled assumptions, identification proof, point estimate,
//! one-sided LCB, provenance hash, risk bound.
//! - LCB-based safety gating (executions are bounded at the LCB level α).
//! - Locked-IRI hard-rejection (the analogue of "risk class is forbidden").
//!
//! What's intentionally a proxy (and honestly documented):
//!
//! - **Identifiability check:** the paper runs backdoor / frontdoor / IV from
//! do-calculus. The scaffold runs a **structural-dependency check** —
//! "the proposed change is identifiable iff its effect on the utility metric
//! is bounded by the closure of dependent IRIs in the loaded ontology."
//! This is a sound conservative proxy for the typical ontology-edit case
//! (linear blast radius from a target IRI), not a substitute for true
//! do-calculus. The certificate flags this with `assumption = "structural_only"`.
//! - **The EXPERIMENT branch:** the paper consumes paired RCT-style data; the
//! scaffold maps EXPERIMENT to "queue for sandbox replay" and exposes a
//! separate path; it does not synthesise an RCT from observational data.
//! - **Adversarial-confounding robustness:** out of scope. The paper's Table 2
//! result depends on Causal-ToolBench instrumentation; the scaffold honest-
//! documents that confounded ontology workflows (e.g. cascading restriction
//! updates) may produce LCBs the verifier cannot defend against an
//! adversarial confounder.
//!
//! The follow-up issues track each of these toward production-grade fidelity.
use crate::graph::GraphStore;
use crate::state::StateDb;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::sync::Arc;
/// An action frame describing a proposed state-changing ontology operation.
/// Mirrors the paper's `a = (tool, t_v, t*, Y, c, r)` tuple.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct ActionFrame {
/// Name of the onto_* tool whose execution this certifies (e.g. "onto_apply",
/// "onto_save", "onto_push", "onto_ingest").
pub tool: String,
/// The IRIs being targeted by the proposed change. In CIVeX terms, the
/// `t_v` (target variable) generalises to the set of structural variables
/// the action intervenes on.
pub target_iris: Vec<String>,
/// The proposed change expressed as Turtle. Treated as the `t*` (target
/// value) — what the action would set the target IRIs' neighbourhood to.
pub proposed_delta_ttl: String,
/// The utility variable name. The scaffold computes the do-effect on this
/// metric. Supported values:
/// - `"dependent_query_pass_rate"` (default) — the caller supplies a list of
/// SPARQL queries in `dependent_queries`; the LCB is over the pre/post
/// pass rate.
/// - `"triple_count_delta"` — coarse proxy: change in total triple count.
/// - `"class_count_delta"` / `"property_count_delta"` — class/property
/// vocabulary changes.
pub utility_metric: String,
/// Optional list of SPARQL queries that should remain answerable post-change.
/// Used when `utility_metric == "dependent_query_pass_rate"`.
#[serde(default)]
pub dependent_queries: Vec<String>,
/// Cost budget. The action is REJECTED if `cost > cost_threshold`. Cost is
/// measured in triples-affected (from blast-radius), matching `onto_plan`.
pub cost_threshold: u64,
/// Utility threshold for EXECUTE. The action is EXECUTED only if
/// `LCB_α ≥ utility_threshold`. Conventional values: 0.0 for "do no harm",
/// 0.5 for "majority of dependent queries still answer", etc.
pub utility_threshold: f64,
/// Risk threshold. Upper bound on potential harm. Action is REJECTED if
/// `cost > risk_threshold` even when within the cost budget.
pub risk_threshold: u64,
/// Whether the action is reversible (has a defined inverse). Maps to the
/// paper's `r ∈ {0, 1}`. Reversibility unlocks the EXPERIMENT branch.
pub reversible: bool,
/// When true, the EXPERIMENT verdict is legal output; otherwise unknown
/// utility forces ABSTAIN. The paper requires explicit opt-in for
/// experimentation because it consumes real resources.
#[serde(default)]
pub allow_experiment: bool,
/// One-sided confidence level α for the LCB. Default 0.05 (95% one-sided).
/// Matches the paper's `LCB_{α=0.05}`.
#[serde(default = "default_alpha")]
pub alpha: f64,
/// Optional: name of a registered `dynamics::ActionSchema` this frame
/// refers to (#43). When set, `certify_action` echoes the schema name
/// into the certificate's assumptions and rationale, making the audit
/// trail explicit about which Dynamics action was gated.
#[serde(default)]
pub action_schema_name: Option<String>,
/// Identification mode (#48, v0.5). Defaults to [`IdentificationMode::Structural`]
/// for back-compat with v0.4 behaviour. When set to
/// [`IdentificationMode::DoCalculusBackdoor`] *and* the `causal-pywhy`
/// Cargo feature is enabled *and* the PyWhy subprocess succeeds, the
/// certificate's `identification_proof` and `assumptions` carry the
/// real backdoor-adjustment result. On any failure path
/// (python_unavailable / pywhy_unavailable / dowhy_runtime_failed) the
/// verifier silently falls back to the structural proxy and adds a
/// `do_calculus_unavailable:<reason>` marker to assumptions so the
/// audit trail is honest about what happened.
#[serde(default)]
pub identification_mode: IdentificationMode,
}
/// Which identifiability proof CIVeX should attempt. Set on
/// [`ActionFrame::identification_mode`].
#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum IdentificationMode {
/// v0.4 default: structural-dependency closure + bounded blast radius.
/// Always works; assumption recorded as `"structural_only"`.
#[default]
Structural,
/// v0.5 mode: invoke `civex_pywhy::run_pywhy_backdoor` on a DAG built
/// from the structural slice, ask DoWhy for a backdoor adjustment set.
/// Falls back to `Structural` on any failure (Python missing, DoWhy
/// missing, runtime error), with the reason recorded in assumptions.
DoCalculusBackdoor,
}
fn default_alpha() -> f64 {
0.05
}
/// The four-way verdict from `certify_action`. Auditable; the certificate
/// documents the assumptions under which the verdict holds.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
pub enum Verdict {
/// The action's effect is identifiable, its LCB clears the utility threshold,
/// and its cost is within budget. Execution is bounded at the α level
/// (probability of false-execute ≤ α).
Execute,
/// A hard constraint fails: locked IRIs would be touched, cost exceeds
/// the risk threshold, or the action is irreversible with insufficient
/// utility certainty.
Reject,
/// Utility is unidentifiable under the current observational data, but the
/// action is reversible and the caller has set `allow_experiment = true`.
/// The orchestrator is expected to run the action in a sandbox / dry-run
/// path, collect the resulting data, and re-invoke `certify_action` with
/// the updated evidence.
Experiment,
/// Utility ambiguous and either the action is irreversible or the caller
/// has not authorised experimentation. The orchestrator must obtain more
/// information (refine the utility metric, supply more dependent queries,
/// or relax the threshold) before re-invoking.
Abstain,
}
/// An auditable causal certificate. JSON-serialisable; the orchestrator can
/// log this artefact alongside the lineage trail.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct Certificate {
/// Verdict on the proposed action.
pub verdict: Verdict,
/// Hash of the structural dependency slice the verifier consulted. Stable
/// across runs over the same committed graph state, so a verdict is replayable.
pub graph_slice_hash: String,
/// Labelled assumptions under which the verdict holds. The scaffold always
/// emits `"structural_only"` (as opposed to full do-calculus identifiability)
/// plus the locked-IRI and reversibility flags actually used.
pub assumptions: Vec<String>,
/// Identification proof. For the scaffold this is a one-line statement:
/// `"structural-dependency closure of {target_iris} has bounded blast radius {N}"`.
/// A production verifier would emit a backdoor / frontdoor / IV proof.
pub identification_proof: String,
/// Point estimate of the do-effect on the utility metric.
pub utility_point_estimate: f64,
/// One-sided lower confidence bound on the do-effect at level α.
pub utility_lcb: f64,
/// α level the LCB was computed at.
pub alpha: f64,
/// SHA-256 hash of the observational data used (canonical-form snapshot
/// of the loaded ontology plus the proposed delta). Used for provenance
/// and replay.
pub provenance_hash: String,
/// Upper bound on potential harm, measured in triples-affected. Matches
/// the `cost` from `onto_plan`'s blast-radius.
pub risk_bound: u64,
/// Human-readable rationale explaining the verdict. Concatenation of the
/// triage rules that fired.
pub rationale: String,
}
/// Aggregate of the certificate plus side evidence for the orchestrator.
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct CertifyActionResult {
pub certificate: Certificate,
/// Number of dependent queries evaluated (when utility_metric is
/// `"dependent_query_pass_rate"`).
pub dependent_queries_evaluated: usize,
/// Per-query pass results post-delta (when utility_metric is
/// `"dependent_query_pass_rate"`).
pub per_query_pass: Vec<bool>,
}
/// Certify a proposed state-changing ontology action.
///
/// Returns a `CertifyActionResult` carrying the verdict, certificate, and
/// evidence. The orchestrator decides whether to actually execute the action
/// based on the verdict — this function is a gate, not an executor.
pub fn certify_action(
db: &StateDb,
graph: &Arc<GraphStore>,
frame: &ActionFrame,
) -> anyhow::Result<CertifyActionResult> {
// ── Step 1: locked-IRI check ────────────────────────────────────────────
// The hardest hard-constraint. Mirrors the paper's "risk class is forbidden"
// branch. Locked IRIs always REJECT regardless of utility.
let planner = crate::plan::Planner::new(db.clone(), graph.clone());
let locked_violations: Vec<String> = frame
.target_iris
.iter()
.filter(|iri| planner.is_locked(iri))
.cloned()
.collect();
// ── Step 2: blast-radius (cost) ─────────────────────────────────────────
// Reuses the existing onto_plan accounting.
let plan_json_str = planner.plan(&frame.proposed_delta_ttl)?;
let plan_json: serde_json::Value = serde_json::from_str(&plan_json_str)?;
let cost_triples = plan_json["blast_radius"]["triples_affected"]
.as_u64()
.unwrap_or(0);
// ── Step 3: structural-dependency slice + hash ──────────────────────────
let dependency_iris = collect_dependency_iris(graph, &frame.target_iris);
let slice_hash = hash_iri_set(&dependency_iris);
// ── Step 4: utility estimate + LCB (Wilson one-sided) ───────────────────
let (utility_point, utility_lcb, queries_eval, per_query_pass) = match frame
.utility_metric
.as_str()
{
"dependent_query_pass_rate" => {
evaluate_dependent_queries(graph, &frame.proposed_delta_ttl, &frame.dependent_queries, frame.alpha)?
}
_ => {
// Fallback: utility is a binary "delta is non-degenerate" check.
// Point estimate 1.0 if the delta loads as valid Turtle and adds at
// least one triple, else 0.0. LCB conservatively equals point estimate.
let temp = GraphStore::new();
let ok = temp.load_turtle(&frame.proposed_delta_ttl, None).is_ok();
let p = if ok { 1.0 } else { 0.0 };
(p, p, 0, Vec::new())
}
};
// ── Step 5: provenance hash (canonical-form snapshot + delta) ───────────
let provenance_hash = compute_provenance_hash(graph, &frame.proposed_delta_ttl)?;
// ── Step 6: triage ──────────────────────────────────────────────────────
let mut rationale_parts: Vec<String> = Vec::new();
// The identification assumption is appended by `derive_identification_proof`
// below; start the list with only the reversibility / schema-name flags.
let mut assumptions: Vec<String> = Vec::new();
if frame.reversible {
assumptions.push("reversible".to_string());
} else {
assumptions.push("irreversible".to_string());
}
if let Some(name) = &frame.action_schema_name {
assumptions.push(format!("dynamics_action_schema:{}", name));
}
let verdict = if !locked_violations.is_empty() {
rationale_parts.push(format!(
"REJECT: {} locked IRI(s) targeted",
locked_violations.len()
));
Verdict::Reject
} else if cost_triples > frame.risk_threshold {
rationale_parts.push(format!(
"REJECT: cost {} exceeds risk_threshold {}",
cost_triples, frame.risk_threshold
));
Verdict::Reject
} else if cost_triples > frame.cost_threshold {
rationale_parts.push(format!(
"REJECT: cost {} exceeds cost_threshold {}",
cost_triples, frame.cost_threshold
));
Verdict::Reject
} else if utility_lcb >= frame.utility_threshold {
rationale_parts.push(format!(
"EXECUTE: utility_lcb {:.3} ≥ utility_threshold {:.3}, cost {} within budget {}",
utility_lcb, frame.utility_threshold, cost_triples, frame.cost_threshold
));
Verdict::Execute
} else if frame.reversible && frame.allow_experiment {
rationale_parts.push(format!(
"EXPERIMENT: utility_lcb {:.3} < threshold {:.3} but reversible and experiment authorised",
utility_lcb, frame.utility_threshold
));
Verdict::Experiment
} else {
rationale_parts.push(format!(
"ABSTAIN: utility_lcb {:.3} < threshold {:.3}, irreversible or experiment not authorised",
utility_lcb, frame.utility_threshold
));
Verdict::Abstain
};
// Identification proof: structural by default; do-calculus when requested
// and the `causal-pywhy` feature is enabled and PyWhy succeeds.
let (identification_proof, identification_assumption) =
derive_identification_proof(graph, frame, cost_triples);
assumptions.push(identification_assumption);
let certificate = Certificate {
verdict,
graph_slice_hash: slice_hash,
assumptions,
identification_proof,
utility_point_estimate: utility_point,
utility_lcb,
alpha: frame.alpha,
provenance_hash,
risk_bound: cost_triples,
rationale: rationale_parts.join("; "),
};
// Record into lineage for audit trail.
let lineage = crate::lineage::LineageLog::new(db.clone());
lineage.record(
"civex",
"CV",
&format!("certify:{}", frame.tool),
&format!("{:?}:cost={}:lcb={:.3}", verdict, cost_triples, utility_lcb),
);
Ok(CertifyActionResult {
certificate,
dependent_queries_evaluated: queries_eval,
per_query_pass,
})
}
/// Evaluate each dependent SPARQL query against the (current state + proposed delta).
/// Returns (point estimate, Wilson LCB at α, evaluated count, per-query pass vec).
fn evaluate_dependent_queries(
graph: &Arc<GraphStore>,
proposed_delta_ttl: &str,
queries: &[String],
alpha: f64,
) -> anyhow::Result<(f64, f64, usize, Vec<bool>)> {
if queries.is_empty() {
// No queries to evaluate — best we can say is "pass rate undefined".
// Conservative: point estimate 1.0 (no evidence of failure), LCB 0.0.
return Ok((1.0, 0.0, 0, Vec::new()));
}
// Build a temp store: clone of current graph + apply delta.
// For the scaffold we load the delta into a fresh store rather than
// round-tripping through the main graph (cheaper + side-effect-free).
let combined = GraphStore::new();
let snapshot_ttl = graph.serialize("turtle")?;
combined.load_turtle(&snapshot_ttl, None)?;
combined.load_turtle(proposed_delta_ttl, None)?;
let mut passes = Vec::with_capacity(queries.len());
for q in queries {
let ok = combined.sparql_select(q).is_ok();
passes.push(ok);
}
let n = passes.len() as f64;
let k = passes.iter().filter(|p| **p).count() as f64;
let p_hat = k / n;
let lcb = wilson_one_sided_lcb(k as u64, n as u64, alpha);
Ok((p_hat, lcb, passes.len(), passes))
}
/// Wilson one-sided lower confidence bound for a binomial proportion. Closed
/// form, no stats library required. Conservative at small n.
fn wilson_one_sided_lcb(k: u64, n: u64, alpha: f64) -> f64 {
if n == 0 {
return 0.0;
}
let z = z_from_alpha(alpha);
let n_f = n as f64;
let p_hat = k as f64 / n_f;
let denom = 1.0 + (z * z) / n_f;
let centre = p_hat + (z * z) / (2.0 * n_f);
let radius = z * (p_hat * (1.0 - p_hat) / n_f + (z * z) / (4.0 * n_f * n_f)).sqrt();
let lcb = (centre - radius) / denom;
lcb.clamp(0.0, 1.0)
}
/// Z-value for a one-sided α. Hard-coded table for common α; closed-form inverse-
/// normal would be cleaner but adds a dependency we don't need for typical uses.
fn z_from_alpha(alpha: f64) -> f64 {
// One-sided critical values: P(Z ≥ z) = α.
if alpha <= 0.005 {
2.576
} else if alpha <= 0.01 {
2.326
} else if alpha <= 0.025 {
1.960
} else if alpha <= 0.05 {
1.645
} else if alpha <= 0.1 {
1.282
} else {
0.842 // α ≈ 0.2
}
}
/// Compute the certificate's `identification_proof` string and the assumption
/// label that accompanies it. Branches on [`ActionFrame::identification_mode`]:
///
/// - [`IdentificationMode::Structural`] (default, always available): returns
/// the v0.4 sentence + `"structural_only"`.
/// - [`IdentificationMode::DoCalculusBackdoor`]: attempts a PyWhy subprocess
/// when the `causal-pywhy` feature is on. On success, returns DoWhy's
/// adjustment estimand + `"do_calculus_backdoor"`. On any failure, falls
/// back to the structural sentence + `"do_calculus_unavailable:<kind>"`.
/// When the feature is off, falls back to the structural sentence +
/// `"do_calculus_unavailable:feature_disabled"`.
fn derive_identification_proof(
graph: &Arc<GraphStore>,
frame: &ActionFrame,
cost_triples: u64,
) -> (String, String) {
let structural_sentence = format!(
"structural-dependency closure of {} target IRI(s) has bounded blast radius of {} triples",
frame.target_iris.len(),
cost_triples
);
match frame.identification_mode {
IdentificationMode::Structural => (structural_sentence, "structural_only".to_string()),
IdentificationMode::DoCalculusBackdoor => {
attempt_do_calculus_backdoor(graph, frame, &structural_sentence)
}
}
}
#[cfg(feature = "causal-pywhy")]
fn attempt_do_calculus_backdoor(
graph: &Arc<GraphStore>,
frame: &ActionFrame,
structural_sentence: &str,
) -> (String, String) {
let (nodes, edges, treatment, outcome) = build_causal_dag(graph, &frame.target_iris);
let input = crate::civex_pywhy::PyWhyInput {
nodes: &nodes,
edges: &edges,
treatment: &treatment,
outcome: &outcome,
};
match crate::civex_pywhy::run_pywhy_backdoor(&input, None) {
Ok(est) if est.identifiable => {
let proof = format!(
"do_calculus_backdoor: P({}|do({})) identified via adjustment set {:?}; estimand: {}",
outcome, treatment, est.adjustment_set, est.estimand_expression
);
(proof, "do_calculus_backdoor".to_string())
}
Ok(_) => (
structural_sentence.to_string(),
"do_calculus_unavailable:unidentifiable".to_string(),
),
Err(e) => {
let reason = e
.to_string()
.split(':')
.next()
.unwrap_or("runtime_failed")
.to_string();
(
structural_sentence.to_string(),
format!("do_calculus_unavailable:{}", reason),
)
}
}
}
#[cfg(not(feature = "causal-pywhy"))]
fn attempt_do_calculus_backdoor(
_graph: &Arc<GraphStore>,
_frame: &ActionFrame,
structural_sentence: &str,
) -> (String, String) {
(
structural_sentence.to_string(),
"do_calculus_unavailable:feature_disabled".to_string(),
)
}
/// Build a causal DAG suitable for PyWhy from the loaded graph + a set of
/// target IRIs (#48, v0.5). Nodes are the target IRIs plus their one-hop
/// structural neighbours (the same slice CIVeX hashes into `slice_hash`).
/// Edges are derived from `rdfs:subClassOf` / `rdfs:subPropertyOf` /
/// `rdfs:domain` / `rdfs:range` triples observed in the graph that connect
/// two nodes in the slice. A synthetic `__utility__` sink node is added
/// downstream of every other node, modelling "every structural variable
/// in the slice could influence the utility metric."
///
/// Returns `(nodes, edges, treatment, outcome)` ready for
/// [`crate::civex_pywhy::PyWhyInput`].
#[allow(dead_code)] // referenced under `causal-pywhy` feature only
fn build_causal_dag(
graph: &Arc<GraphStore>,
target_iris: &[String],
) -> (Vec<String>, Vec<(String, String)>, String, String) {
use std::collections::BTreeSet;
let mut nodes: BTreeSet<String> = BTreeSet::new();
for iri in target_iris {
nodes.insert(iri.clone());
}
let deps = collect_dependency_iris(graph, target_iris);
for d in deps {
nodes.insert(d);
}
// Pull subclass / subproperty / domain / range edges among the slice.
let nodes_vec: Vec<String> = nodes.iter().cloned().collect();
let edge_predicates = [
"http://www.w3.org/2000/01/rdf-schema#subClassOf",
"http://www.w3.org/2000/01/rdf-schema#subPropertyOf",
"http://www.w3.org/2000/01/rdf-schema#domain",
"http://www.w3.org/2000/01/rdf-schema#range",
];
let mut edges: Vec<(String, String)> = Vec::new();
for pred in edge_predicates {
let q = format!("SELECT ?s ?o WHERE {{ ?s <{}> ?o }} LIMIT 500", pred);
if let Ok(json_str) = graph.sparql_select(&q)
&& let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json_str)
&& let Some(rows) = parsed["results"].as_array()
{
for row in rows {
if let (Some(s), Some(o)) = (row["s"].as_str(), row["o"].as_str()) {
let s = s.trim_matches(|c| c == '<' || c == '>').to_string();
let o = o.trim_matches(|c| c == '<' || c == '>').to_string();
if nodes.contains(&s) && nodes.contains(&o) {
// Edges in DoWhy point "cause → effect"; subClassOf
// says s is-a o, so structurally o influences s.
edges.push((o, s));
}
}
}
}
}
// Synthetic utility outcome — every structural node could influence it.
let utility_node = "__utility__".to_string();
for n in &nodes_vec {
edges.push((n.clone(), utility_node.clone()));
}
nodes.insert(utility_node.clone());
let treatment = target_iris
.first()
.cloned()
.unwrap_or_else(|| "__none__".to_string());
(nodes.into_iter().collect(), edges, treatment, utility_node)
}
/// Collect IRIs structurally dependent on the action's target IRIs. The scaffold
/// uses one-hop closure (subjects/objects of any triple referencing a target).
/// A production version would walk the full subclass + property-domain/range
/// closure and bound the recursion.
fn collect_dependency_iris(graph: &Arc<GraphStore>, target_iris: &[String]) -> Vec<String> {
use std::collections::BTreeSet;
let mut deps: BTreeSet<String> = BTreeSet::new();
for iri in target_iris {
let q = format!(
r#"SELECT DISTINCT ?x WHERE {{
{{ <{iri}> ?p ?x }} UNION
{{ ?x ?p <{iri}> }} UNION
{{ ?x <{iri}> ?o }}
}} LIMIT 200"#
);
if let Ok(json_str) = graph.sparql_select(&q)
&& let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json_str)
&& let Some(rows) = parsed["results"].as_array()
{
for row in rows {
if let Some(x) = row["x"].as_str() {
deps.insert(x.trim_matches(|c| c == '<' || c == '>').to_string());
}
}
}
}
for iri in target_iris {
deps.insert(iri.clone());
}
deps.into_iter().collect()
}
/// Stable hash of an IRI set. SHA-256 over the sorted concatenation.
fn hash_iri_set(iris: &[String]) -> String {
let mut sorted: Vec<&String> = iris.iter().collect();
sorted.sort();
let mut hasher = Sha256::new();
for iri in sorted {
hasher.update(iri.as_bytes());
hasher.update(b"\n");
}
hex_encode(&hasher.finalize())
}
/// SHA-256 over (current graph canonical-form serialisation + the proposed delta).
fn compute_provenance_hash(graph: &Arc<GraphStore>, delta_ttl: &str) -> anyhow::Result<String> {
let snapshot = graph.serialize("turtle")?;
let mut hasher = Sha256::new();
hasher.update(snapshot.as_bytes());
hasher.update(b"\n--DELTA--\n");
hasher.update(delta_ttl.as_bytes());
Ok(hex_encode(&hasher.finalize()))
}
fn hex_encode(bytes: &[u8]) -> String {
let mut s = String::with_capacity(bytes.len() * 2);
for b in bytes {
s.push_str(&format!("{:02x}", b));
}
s
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn wilson_lcb_at_full_pass_is_strictly_below_one() {
// 10/10 passes should give an LCB below 1.0 — Wilson's whole point is that
// observing a 100% pass rate on a small sample doesn't certify the true
// rate is 100%.
let lcb = wilson_one_sided_lcb(10, 10, 0.05);
assert!(lcb < 1.0, "Wilson LCB at 10/10 should be < 1.0; got {}", lcb);
assert!(lcb > 0.7, "but it should still be > 0.7; got {}", lcb);
}
#[test]
fn wilson_lcb_at_zero_pass_is_zero() {
let lcb = wilson_one_sided_lcb(0, 10, 0.05);
assert!(lcb <= 0.01, "Wilson LCB at 0/10 should be ≈ 0; got {}", lcb);
}
#[test]
fn wilson_lcb_at_empty_n_is_zero() {
assert_eq!(wilson_one_sided_lcb(0, 0, 0.05), 0.0);
}
#[test]
fn z_from_alpha_monotone_decreasing() {
// As α grows, the critical value should shrink (or stay equal for the
// hard-coded bands).
let zs = [
z_from_alpha(0.005),
z_from_alpha(0.01),
z_from_alpha(0.025),
z_from_alpha(0.05),
z_from_alpha(0.1),
];
for w in zs.windows(2) {
assert!(w[0] >= w[1], "z table must be monotone decreasing in α");
}
}
#[test]
fn hash_iri_set_is_deterministic() {
let a = hash_iri_set(&["b".to_string(), "a".to_string(), "c".to_string()]);
let b = hash_iri_set(&["c".to_string(), "a".to_string(), "b".to_string()]);
assert_eq!(a, b, "hash must be order-independent");
assert_eq!(a.len(), 64, "SHA-256 hex is 64 chars");
}
}