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(temporal): bi-temporal facts, valid time and recorded time

FABIOTESS2479ec5eb972
diff --git a/CLAUDE.md b/CLAUDE.md
index 58706442..9996b465 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -93,6 +93,9 @@ Claude dynamically decides the next tool call based on what the previous tool re
| `onto_support_report` | To summarise provenance quality: unsourced-claim rate over the graph, support rate across the claims judged so far |
| `onto_pack` | To write the loaded graph and its verification evidence to a portable versioned artifact: sorted N-Triples, a manifest (name, version, counts, timestamp, tool version, sha256) and the lint/enforce results recorded at pack time. What you promote between environments is then a graph that has already passed its checks, with the evidence attached |
| `onto_unpack` | To load a pack, refusing it if the checksum does not match. `verify_only` inspects the manifest and evidence without loading |
+| `onto_temporal_snapshot` | To see which named graphs are in scope at a point in time. Two independent clocks: `valid_at` asks what was TRUE then, `as_of` asks what was KNOWN then. Graphs without validity metadata are timeless and always in scope, so the vocabulary is additive to an existing store |
+| `onto_temporal_query` | To run a SPARQL graph pattern against only the graphs in temporal scope: what the graph said at a given valid time, as known at a given recorded time |
+| `onto_temporal_conflicts` | To separate genuine contradictions from corrections. A disjointness violation only counts when the two assertions claim OVERLAPPING validity; where one period ends as the other begins, the pair is superseded history, not a conflict |
| `onto_lineage` | To view the session's lineage trail (plan → enforce → apply → monitor → drift) |
| `onto_lint_feedback` | To accept/dismiss a lint issue — teaches lint to suppress repeatedly dismissed warnings |
| `onto_enforce_feedback` | To accept/dismiss an enforce violation — teaches enforce to suppress repeatedly dismissed violations |
diff --git a/src/inputs.rs b/src/inputs.rs
index 7a2e848e..9e735e2e 100644
--- a/src/inputs.rs
+++ b/src/inputs.rs
@@ -1149,3 +1149,21 @@ pub struct OntoReasonIncrementalInput {
/// Write the inferences into the store (default true)
pub materialize: Option<bool>,
}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct OntoTemporalSnapshotInput {
+ /// Instant to evaluate validity at, e.g. "2026-03-01". Omit for any time.
+ pub valid_at: Option<String>,
+ /// Only consider what was recorded by this instant. Omit for everything known.
+ pub as_of: Option<String>,
+}
+
+#[derive(Deserialize, JsonSchema)]
+pub struct OntoTemporalQueryInput {
+ /// SPARQL graph pattern, the body of a WHERE clause
+ pub pattern: String,
+ /// Instant to evaluate validity at
+ pub valid_at: Option<String>,
+ /// Only consider what was recorded by this instant
+ pub as_of: Option<String>,
+}
diff --git a/src/lib.rs b/src/lib.rs
index fda57324..90534fed 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -25,6 +25,7 @@ pub mod extract_scaffold;
pub mod flora_pipeline;
pub mod pack;
pub mod support;
+pub mod temporal;
pub mod policy;
pub mod projection_check;
pub mod shape_combinatorics;
diff --git a/src/server.rs b/src/server.rs
index 7f3f0605..32821e03 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -885,6 +885,35 @@ impl OpenOntologiesServer {
}
}
+ #[tool(name = "onto_temporal_snapshot", description = "Which named graphs are in scope at a point in time, and which are excluded and why. Two independent clocks: valid_at asks what was TRUE then, as_of asks what was KNOWN then. Assertions live in named graphs described in the default graph with temporal:validFrom, validTo and recordedAt; a graph with no description is timeless and always in scope.")]
+ async fn onto_temporal_snapshot(&self, Parameters(input): Parameters<OntoTemporalSnapshotInput>) -> String {
+ use crate::temporal::Temporal;
+ match Temporal::new(self.graph.clone()).snapshot(input.valid_at.as_deref(), input.as_of.as_deref()) {
+ Ok(json) => json,
+ Err(e) => format!(r#"{{"error":"{}"}}"#, e.to_string().replace('"', "'")),
+ }
+ }
+
+ #[tool(name = "onto_temporal_query", description = "Run a SPARQL graph pattern against only the graphs in temporal scope: what the graph said at a given valid time, as known at a given recorded time. Pass the body of a WHERE clause as `pattern`.")]
+ async fn onto_temporal_query(&self, Parameters(input): Parameters<OntoTemporalQueryInput>) -> String {
+ use crate::temporal::Temporal;
+ match Temporal::new(self.graph.clone()).query_at(
+ &input.pattern, input.valid_at.as_deref(), input.as_of.as_deref(),
+ ) {
+ Ok(json) => json,
+ Err(e) => format!(r#"{{"error":"{}"}}"#, e.to_string().replace('"', "'")),
+ }
+ }
+
+ #[tool(name = "onto_temporal_conflicts", description = "Disjointness violations that claim OVERLAPPING validity, separated from those that do not. Without valid time a correction reads as a contradiction: an entity recorded one way until May and another after trips every check. This reports genuine disagreement about the same period as contradictions, and everything else as superseded history.")]
+ async fn onto_temporal_conflicts(&self) -> String {
+ use crate::temporal::Temporal;
+ match Temporal::new(self.graph.clone()).conflicts() {
+ Ok(json) => json,
+ Err(e) => format!(r#"{{"error":"{}"}}"#, e.to_string().replace('"', "'")),
+ }
+ }
+
#[tool(name = "onto_reason_incremental", description = "Derive the consequences of newly added triples WITHOUT recomputing the whole closure. Pass the added triples as N-Triples in `delta`; the engine joins them against the existing closure (semi-naive evaluation), so the work is proportional to what changed rather than to the size of the store. Use after adding facts to an already-materialised graph. Adding SCHEMA axioms (subClassOf, domain, range, inverseOf, equivalentClass) changes what the whole store entails and is refused with an explanation: run onto_reason for those.")]
async fn onto_reason_incremental(&self, Parameters(input): Parameters<OntoReasonIncrementalInput>) -> String {
use crate::reason_incremental::{parse_ntriples, IncrementalReasoner};
diff --git a/src/temporal.rs b/src/temporal.rs
new file mode 100644
index 00000000..2f889c59
--- /dev/null
+++ b/src/temporal.rs
@@ -0,0 +1,329 @@
+//! Bi-temporal facts: when something was true, and when we learned it.
+//!
+//! Two clocks, deliberately independent:
+//!
+//! - VALID time is when a statement holds in the world. A cell line was
+//! adherent until May and suspension after; both statements are true, of
+//! different periods.
+//! - RECORDED time is when the store came to hold it. A correction entered
+//! today about last year changes what we know, not what happened.
+//!
+//! Collapsing them loses the two questions people actually ask: what was true
+//! then, and what did we believe then. An audit needs the second; analysis
+//! needs the first; a contradiction check needs both, because two statements
+//! only conflict if they claim the same period.
+//!
+//! ## Shape on disk
+//!
+//! RDF-star would be the elegant carrier and the parser does not accept it,
+//! so assertions live in NAMED GRAPHS and their validity is described in the
+//! default graph, which is ordinary TriG that any store can read:
+//!
+//! ```turtle
+//! :g1 { :HEK293 a :AdherentCellLine . }
+//! :g2 { :HEK293 a :SuspensionCellLine . }
+//! {
+//! :g1 t:validFrom "2024-01-01"^^xsd:date ;
+//! t:validTo "2026-05-01"^^xsd:date ;
+//! t:recordedAt "2024-01-05"^^xsd:dateTime .
+//! :g2 t:validFrom "2026-05-01"^^xsd:date ;
+//! t:recordedAt "2026-05-02"^^xsd:dateTime .
+//! }
+//! ```
+//!
+//! An absent `validFrom` means "since always", an absent `validTo` means
+//! "still true", and a graph with no temporal description at all is timeless:
+//! it is in scope for every snapshot, so adding this vocabulary to an
+//! existing store changes nothing until it is used.
+//!
+//! Intervals are half-open, `[validFrom, validTo)`. Two facts that meet at a
+//! boundary do not overlap, which is what makes "adherent until May,
+//! suspension from May" a correction rather than a contradiction.
+
+use crate::graph::GraphStore;
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+pub const NS: &str = "https://open-ontologies.org/temporal#";
+
+pub struct Temporal {
+ graph: Arc<GraphStore>,
+}
+
+#[derive(Clone, Debug)]
+pub struct Validity {
+ pub graph: String,
+ pub valid_from: Option<String>,
+ pub valid_to: Option<String>,
+ pub recorded_at: Option<String>,
+}
+
+impl Validity {
+ /// Was this true at `instant`, on the half-open interval.
+ fn valid_at(&self, instant: &str) -> bool {
+ self.valid_from.as_deref().is_none_or(|f| f <= instant)
+ && self.valid_to.as_deref().is_none_or(|t| instant < t)
+ }
+
+ /// Had we recorded it by `instant`.
+ fn recorded_by(&self, instant: &str) -> bool {
+ self.recorded_at.as_deref().is_none_or(|r| r <= instant)
+ }
+
+ /// Do two validity periods share any instant. Half-open, so touching
+ /// intervals do not overlap.
+ fn overlaps(&self, other: &Validity) -> bool {
+ let start_before_end = |a: &Option<String>, b: &Option<String>| match (a, b) {
+ (Some(start), Some(end)) => start.as_str() < end.as_str(),
+ _ => true, // an open end never closes the interval
+ };
+ start_before_end(&self.valid_from, &other.valid_to)
+ && start_before_end(&other.valid_from, &self.valid_to)
+ }
+
+ fn describe(&self) -> String {
+ let from = self.valid_from.as_deref().unwrap_or("always");
+ let to = self.valid_to.as_deref().unwrap_or("still true");
+ format!("{from} to {to}")
+ }
+}
+
+/// Literal or IRI as SPARQL returns it, without its wrapping.
+fn plain(value: &str) -> String {
+ let v = value.trim();
+ if v.starts_with('<') && v.ends_with('>') {
+ return v[1..v.len() - 1].to_string();
+ }
+ if let Some(body) = v.strip_prefix('"') {
+ for cut in ["\"^^", "\"@", "\""] {
+ if let Some(i) = body.find(cut) {
+ return body[..i].to_string();
+ }
+ }
+ }
+ v.to_string()
+}
+
+fn local(iri: &str) -> &str {
+ iri.rsplit(['#', '/']).next().unwrap_or(iri)
+}
+
+impl Temporal {
+ pub fn new(graph: Arc<GraphStore>) -> Self {
+ Self { graph }
+ }
+
+ fn rows(&self, query: &str) -> anyhow::Result<Vec<serde_json::Value>> {
+ let raw = self.graph.sparql_select(query)?;
+ let parsed: serde_json::Value = serde_json::from_str(&raw)?;
+ Ok(parsed
+ .get("results")
+ .and_then(|r| r.as_array())
+ .cloned()
+ .unwrap_or_default())
+ }
+
+ /// Every graph that carries validity metadata.
+ fn validities(&self) -> anyhow::Result<BTreeMap<String, Validity>> {
+ let query = format!(
+ "SELECT ?g ?from ?to ?rec WHERE {{ \
+ {{ ?g <{NS}validFrom> ?from }} UNION {{ ?g <{NS}validTo> ?to }} \
+ UNION {{ ?g <{NS}recordedAt> ?rec }} }} LIMIT 20000"
+ );
+ let mut out: BTreeMap<String, Validity> = BTreeMap::new();
+ for row in self.rows(&query)? {
+ let Some(g) = row.get("g").and_then(|v| v.as_str()).map(plain) else {
+ continue;
+ };
+ let entry = out.entry(g.clone()).or_insert(Validity {
+ graph: g,
+ valid_from: None,
+ valid_to: None,
+ recorded_at: None,
+ });
+ if let Some(v) = row.get("from").and_then(|v| v.as_str()) {
+ entry.valid_from = Some(plain(v));
+ }
+ if let Some(v) = row.get("to").and_then(|v| v.as_str()) {
+ entry.valid_to = Some(plain(v));
+ }
+ if let Some(v) = row.get("rec").and_then(|v| v.as_str()) {
+ entry.recorded_at = Some(plain(v));
+ }
+ }
+ Ok(out)
+ }
+
+ /// Named graphs holding assertions, whether or not they are described.
+ fn all_graphs(&self) -> anyhow::Result<BTreeSet<String>> {
+ Ok(self
+ .rows("SELECT DISTINCT ?g WHERE { GRAPH ?g { ?s ?p ?o } } LIMIT 20000")?
+ .iter()
+ .filter_map(|r| r.get("g").and_then(|v| v.as_str()).map(plain))
+ .collect())
+ }
+
+ /// Which graphs are in scope for a snapshot, and why.
+ pub fn snapshot(&self, valid_at: Option<&str>, as_of: Option<&str>) -> anyhow::Result<String> {
+ let validities = self.validities()?;
+ let graphs = self.all_graphs()?;
+
+ let mut in_scope = Vec::new();
+ let mut excluded = Vec::new();
+ for g in &graphs {
+ match validities.get(g) {
+ // Undescribed graphs are timeless and always in scope, so
+ // this vocabulary is additive to an existing store.
+ None => in_scope.push(serde_json::json!({"graph": g, "reason": "no validity recorded, timeless"})),
+ Some(v) => {
+ let valid_ok = valid_at.is_none_or(|t| v.valid_at(t));
+ let recorded_ok = as_of.is_none_or(|t| v.recorded_by(t));
+ if valid_ok && recorded_ok {
+ in_scope.push(serde_json::json!({"graph": g, "valid": v.describe()}));
+ } else {
+ excluded.push(serde_json::json!({
+ "graph": g,
+ "valid": v.describe(),
+ "reason": if !valid_ok { "not true at that instant" } else { "not yet recorded then" },
+ }));
+ }
+ }
+ }
+ }
+
+ Ok(serde_json::json!({
+ "ok": true,
+ "valid_at": valid_at,
+ "as_of": as_of,
+ "in_scope": in_scope,
+ "excluded": excluded,
+ "note": "Graphs without validity metadata are timeless and always in scope.",
+ })
+ .to_string())
+ }
+
+ /// Run a query against only the graphs in temporal scope.
+ ///
+ /// The query is wrapped rather than rewritten: its pattern is evaluated
+ /// inside a GRAPH block restricted to the snapshot, which keeps arbitrary
+ /// SPARQL working without parsing it.
+ pub fn query_at(
+ &self,
+ pattern: &str,
+ valid_at: Option<&str>,
+ as_of: Option<&str>,
+ ) -> anyhow::Result<String> {
+ let snapshot: serde_json::Value = serde_json::from_str(&self.snapshot(valid_at, as_of)?)?;
+ let graphs: Vec<String> = snapshot
+ .get("in_scope")
+ .and_then(|v| v.as_array())
+ .map(|rows| {
+ rows.iter()
+ .filter_map(|r| r.get("graph").and_then(|g| g.as_str()).map(String::from))
+ .collect()
+ })
+ .unwrap_or_default();
+
+ if graphs.is_empty() {
+ return Ok(serde_json::json!({
+ "ok": true,
+ "results": [],
+ "note": "no graphs in scope at that instant",
+ })
+ .to_string());
+ }
+
+ let values = graphs
+ .iter()
+ .map(|g| format!("<{g}>"))
+ .collect::<Vec<_>>()
+ .join(" ");
+ let body = pattern.trim();
+ let body = body
+ .strip_prefix('{')
+ .and_then(|b| b.strip_suffix('}'))
+ .unwrap_or(body);
+ let wrapped = format!(
+ "SELECT * WHERE {{ VALUES ?__g {{ {values} }} GRAPH ?__g {{ {body} }} }} LIMIT 10000"
+ );
+ let raw = self.graph.sparql_select(&wrapped)?;
+ let parsed: serde_json::Value = serde_json::from_str(&raw)?;
+ Ok(serde_json::json!({
+ "ok": true,
+ "valid_at": valid_at,
+ "as_of": as_of,
+ "graphs_in_scope": graphs.len(),
+ "results": parsed.get("results").cloned().unwrap_or(serde_json::json!([])),
+ })
+ .to_string())
+ }
+
+ /// Disjointness violations, but only where the two assertions claim
+ /// OVERLAPPING validity.
+ ///
+ /// This is the point of carrying valid time at all. Without it, a
+ /// correction reads as a contradiction: an entity recorded as one thing
+ /// until May and another thereafter trips every disjointness check, and
+ /// the finding is noise. With it, a superseded statement is superseded,
+ /// and only genuine disagreement about the same period survives.
+ pub fn conflicts(&self) -> anyhow::Result<String> {
+ let validities = self.validities()?;
+ let rows = self.rows(
+ "PREFIX owl: <http://www.w3.org/2002/07/owl#> \
+ PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> \
+ SELECT DISTINCT ?s ?a ?b ?ga ?gb WHERE { \
+ GRAPH ?ga { ?s a ?a } GRAPH ?gb { ?s a ?b } \
+ FILTER(STR(?a) < STR(?b)) \
+ ?a rdfs:subClassOf* ?da . ?b rdfs:subClassOf* ?db . \
+ { ?da owl:disjointWith ?db } UNION { ?db owl:disjointWith ?da } \
+ } LIMIT 5000",
+ )?;
+
+ let mut conflicts = Vec::new();
+ let mut superseded = Vec::new();
+ for row in &rows {
+ let get = |k: &str| row.get(k).and_then(|v| v.as_str()).map(plain);
+ let (Some(s), Some(a), Some(b), Some(ga), Some(gb)) = (
+ get("s"), get("a"), get("b"), get("ga"), get("gb"),
+ ) else {
+ continue;
+ };
+ if ga == gb {
+ continue;
+ }
+
+ let timeless = Validity {
+ graph: String::new(),
+ valid_from: None,
+ valid_to: None,
+ recorded_at: None,
+ };
+ let va = validities.get(&ga).unwrap_or(&timeless);
+ let vb = validities.get(&gb).unwrap_or(&timeless);
+
+ let entry = serde_json::json!({
+ "subject": local(&s),
+ "types": [local(&a), local(&b)],
+ "periods": [va.describe(), vb.describe()],
+ "graphs": [ga, gb],
+ });
+ if va.overlaps(vb) {
+ conflicts.push(entry);
+ } else {
+ superseded.push(entry);
+ }
+ }
+
+ Ok(serde_json::json!({
+ "ok": true,
+ "contradictions": conflicts,
+ "contradiction_count": conflicts.len(),
+ "superseded": superseded,
+ "superseded_count": superseded.len(),
+ "note": "contradictions claim overlapping validity and genuinely disagree. \
+ superseded pairs are corrections: one period ends where the other begins, \
+ which is a history rather than a conflict.",
+ })
+ .to_string())
+ }
+}