Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
Fix temporal revision integrity follow-ups
KaifAhmad18be16f782eef
diff --git a/semantica/kg/temporal_model.py b/semantica/kg/temporal_model.pyindex 13bfa0dd..90d47ba0 100644--- a/semantica/kg/temporal_model.py+++ b/semantica/kg/temporal_model.py@@ -6,8 +6,7 @@ from __future__ import annotationsimport jsonimport re-import warnings-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom datetime import datetime, timezonefrom enum import Enumfrom typing import Any, Dict, Optional@@ -21,6 +20,10 @@ class TemporalBound(Enum):OPEN = "OPEN"+def _default_recorded_at() -> datetime:+ return datetime.now(timezone.utc)++@dataclassclass BiTemporalFact:"""@@ -34,28 +37,23 @@ class BiTemporalFact:valid_from: Optional[datetime]valid_until: Optional[datetime | TemporalBound]- recorded_at: datetime+ recorded_at: datetime = field(default_factory=_default_recorded_at)superseded_at: datetime | TemporalBound = TemporalBound.OPEN@classmethoddef from_relationship(cls, relationship: Dict[str, Any]) -> "BiTemporalFact":valid_until_raw = relationship.get("valid_until", TemporalBound.OPEN)- if "valid_until" in relationship and relationship.get("valid_until") is None:- warnings.warn(- "`valid_until=None` is deprecated; use TemporalBound.OPEN or an explicit date.",- DeprecationWarning,- stacklevel=2,- )if valid_until_raw is None:valid_until_raw = TemporalBound.OPEN+ valid_from = parse_temporal_value(relationship.get("valid_from"))recorded_at_raw = relationship.get("recorded_at")superseded_at_raw = relationship.get("superseded_at", TemporalBound.OPEN)return cls(- valid_from=parse_temporal_value(relationship.get("valid_from")),+ valid_from=valid_from,valid_until=parse_temporal_bound(valid_until_raw),- recorded_at=parse_temporal_value(recorded_at_raw) if recorded_at_raw is not None else datetime.now(timezone.utc),+ recorded_at=parse_temporal_value(recorded_at_raw) if recorded_at_raw is not None else (valid_from or _default_recorded_at()),superseded_at=parse_temporal_bound(superseded_at_raw, default=TemporalBound.OPEN),)diff --git a/semantica/kg/temporal_query.py b/semantica/kg/temporal_query.pyindex f3b3c31e..d482845a 100644--- a/semantica/kg/temporal_query.py+++ b/semantica/kg/temporal_query.py@@ -6,6 +6,7 @@ import copyimport warningsfrom datetime import datetime, timedelta, timezonefrom typing import Any, Dict, List, Optional+from uuid import uuid4from ..utils.progress_tracker import get_progress_trackerfrom .temporal_model import (@@ -487,6 +488,8 @@ class TemporalGraphQuery:def _parse_time(self, time_value):"""Parse time value into a UTC-normalized datetime."""+ if time_value in (TemporalBound.OPEN, TemporalBound.OPEN.value):+ return Nonetry:return parse_temporal_value(time_value)except TemporalValidationError:@@ -927,7 +930,10 @@ class TemporalVersionManager:and relationship type. This preserves all prior versions instead oftrying to collapse them into a single mutable record."""+ from ..change_management import compute_checksum+revision_time = datetime.now(timezone.utc)+ revision_suffix = self._generate_revision_suffix(revision_time)relationships = copy.deepcopy(snapshot.get("relationships", []))fact_ids = set(revision.get("fact_ids", []))new_valid_from = parse_temporal_value(revision.get("new_valid_from"))@@ -962,7 +968,7 @@ class TemporalVersionManager:revised_relationships.append(original)replacement = copy.deepcopy(rel)- replacement["id"] = f"{rel_id}__rev__{int(revision_time.timestamp())}"+ replacement["id"] = f"{rel_id}__rev__{revision_suffix}"replacement["valid_from"] = serialize_temporal_value(new_valid_from)replacement["valid_until"] = (TemporalBound.OPEN if new_valid_until is TemporalBound.OPEN else serialize_temporal_value(new_valid_until)@@ -985,17 +991,23 @@ class TemporalVersionManager:]base_label = snapshot.get("label", "snapshot")original_label = base_label- revised_label = f"{base_label}__revision__{int(revision_time.timestamp())}"+ revised_label = f"{base_label}__revision__{revision_suffix}"original_snapshot = copy.deepcopy(snapshot)original_snapshot["label"] = original_labeloriginal_snapshot_inserted = Falseif self.storage.get(original_label) is None:+ original_snapshot["checksum"] = compute_checksum(+ {k: v for k, v in original_snapshot.items() if k != "checksum"}+ )self.storage.save(original_snapshot)original_snapshot_inserted = Truerevised_snapshot["label"] = revised_labelrevised_snapshot.setdefault("metadata", {})["revision_event"] = temporal_structure_to_json_ready(provenance_event)+ revised_snapshot["checksum"] = compute_checksum(+ {k: v for k, v in revised_snapshot.items() if k != "checksum"}+ )try:self.storage.save(revised_snapshot)except Exception as exc:@@ -1118,6 +1130,10 @@ class TemporalVersionManager:rel_type = relationship.get("type", relationship.get("relationship", ""))return f"{source}|{rel_type}|{target}"+ def _generate_revision_suffix(self, revision_time: datetime) -> str:+ timestamp_part = revision_time.strftime("%Y%m%dT%H%M%S%fZ")+ return f"{timestamp_part}_{uuid4().hex[:8]}"+def _warn_on_retroactive_overlap(self,replacement: Dict[str, Any],diff --git a/tests/change_management/test_temporal_versioning.py b/tests/change_management/test_temporal_versioning.pyindex 0f0000fd..45e5e747 100644--- a/tests/change_management/test_temporal_versioning.py+++ b/tests/change_management/test_temporal_versioning.py@@ -9,6 +9,7 @@ import osimport tempfileimport pytestfrom datetime import datetime, timezone+from unittest.mock import patchfrom semantica.kg.temporal_query import TemporalVersionManagerfrom semantica.kg.temporal_model import TemporalBoundfrom semantica.change_management import ChangeLogEntry, InMemoryVersionStorage, SQLiteVersionStorage@@ -280,6 +281,94 @@ class TestTemporalVersionManager:assert original is not Noneassert manager.get_version(revised["label"]) is not Noneassert len(manager.list_versions()) == 2+ assert manager.verify_checksum(revised) is True++ def test_apply_revision_recomputes_checksums_for_saved_snapshots(self):+ manager = TemporalVersionManager()+ snapshot = manager.create_snapshot(+ graph={+ "entities": [],+ "relationships": [+ {+ "id": "fact-1",+ "source": "drug_a",+ "target": "drug_b",+ "type": "interacts_with",+ "valid_from": "2021-01-01",+ "valid_until": TemporalBound.OPEN,+ }+ ],+ },+ version_label="v1.0",+ author="[email protected]",+ description="Initial version",+ )++ revised = manager.apply_revision(+ snapshot,+ {+ "fact_ids": ["fact-1"],+ "new_valid_from": "2019-01-01",+ "new_valid_until": None,+ "revision_type": "retroactive",+ "author": "[email protected]",+ "reason": "Backfilled evidence",+ },+ )++ assert manager.verify_checksum(revised) is True+ persisted_original = manager.get_version("v1.0")+ assert persisted_original is not None+ assert manager.verify_checksum(persisted_original) is True++ def test_generate_revision_suffix_is_collision_resistant(self):+ manager = TemporalVersionManager()+ revision_time = datetime(2026, 3, 23, 12, 0, 0, tzinfo=timezone.utc)++ suffix_one = manager._generate_revision_suffix(revision_time)+ suffix_two = manager._generate_revision_suffix(revision_time)++ assert suffix_one != suffix_two++ def test_apply_revision_uses_collision_resistant_suffix_for_ids_and_labels(self):+ manager = TemporalVersionManager()+ snapshot = manager.create_snapshot(+ graph={+ "entities": [],+ "relationships": [+ {+ "id": "fact-1",+ "source": "drug_a",+ "target": "drug_b",+ "type": "interacts_with",+ "valid_from": "2021-01-01",+ "valid_until": TemporalBound.OPEN,+ }+ ],+ },+ version_label="v1.0",+ author="[email protected]",+ description="Initial version",+ )++ with patch.object(manager, "_generate_revision_suffix", return_value="fixed_suffix"):+ revised = manager.apply_revision(+ snapshot,+ {+ "fact_ids": ["fact-1"],+ "new_valid_from": "2019-01-01",+ "new_valid_until": None,+ "revision_type": "retroactive",+ "author": "[email protected]",+ "reason": "Backfilled evidence",+ },+ )++ assert revised["label"].endswith("__revision__fixed_suffix")+ replacement = next(+ rel for rel in revised["relationships"] if rel["id"].startswith("fact-1__rev__")+ )+ assert replacement["id"] == "fact-1__rev__fixed_suffix"def test_detailed_entity_diff(self):"""Test detailed entity-level differences."""diff --git a/tests/kg/test_kg.py b/tests/kg/test_kg.pyindex 33544462..db8fb5cc 100644--- a/tests/kg/test_kg.py+++ b/tests/kg/test_kg.py@@ -333,7 +333,7 @@ class TestTemporalGraphQuery(unittest.TestCase):with self.assertRaises(TemporalValidationError):self.query_engine._parse_time("not-a-date")- def test_query_at_time_supports_open_bound_and_none_warning(self):+ def test_query_at_time_supports_open_bound_and_canonical_none_without_warning(self):graph = {"relationships": [{@@ -358,7 +358,7 @@ class TestTemporalGraphQuery(unittest.TestCase):result = self.query_engine.query_at_time(graph, "", "2026-01-01")self.assertEqual(len(result["relationships"]), 2)- self.assertTrue(any(item.category is DeprecationWarning for item in caught))+ self.assertFalse(any(item.category is DeprecationWarning for item in caught))def test_query_at_time_supports_transaction_axis(self):graph = {@@ -385,6 +385,46 @@ class TestTemporalGraphQuery(unittest.TestCase):self.assertEqual(len(result_2020["relationships"]), 0)self.assertEqual(len(result_2021["relationships"]), 1)+ def test_analyze_evolution_accepts_open_valid_until(self):+ graph = {+ "relationships": [+ {+ "source": "1",+ "target": "2",+ "type": "current",+ "valid_from": "2024-01-01",+ "valid_until": TemporalBound.OPEN,+ }+ ]+ }++ result = self.query_engine.analyze_evolution(+ graph,+ start_time="2025-01-01",+ end_time="2025-12-31",+ )++ self.assertEqual(result["num_relationships"], 1)++ def test_query_at_time_legacy_transaction_axis_uses_valid_from_when_recorded_missing(self):+ graph = {+ "relationships": [+ {+ "source": "1",+ "target": "2",+ "type": "legacy",+ "valid_from": "2024-01-01",+ "valid_until": TemporalBound.OPEN,+ }+ ]+ }++ result = self.query_engine.query_at_time(+ graph, "", "2025-06-01", time_axis="transaction"+ )++ self.assertEqual(len(result["relationships"]), 1)+def test_null_valid_until_deserializes_to_open(self):relationship = deserialize_relationship_temporal_fields({"source": "1", "target": "2", "type": "rel", "valid_from": "2024-01-01", "valid_until": None}