Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

Fix temporal revision integrity follow-ups

KaifAhmad18be16f782eef
diff --git a/semantica/kg/temporal_model.py b/semantica/kg/temporal_model.py
index 13bfa0dd..90d47ba0 100644
--- a/semantica/kg/temporal_model.py
+++ b/semantica/kg/temporal_model.py
@@ -6,8 +6,7 @@ from __future__ import annotations
import json
import re
-import warnings
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from datetime import datetime, timezone
from enum import Enum
from typing import Any, Dict, Optional
@@ -21,6 +20,10 @@ class TemporalBound(Enum):
OPEN = "OPEN"
+def _default_recorded_at() -> datetime:
+ return datetime.now(timezone.utc)
+
+
@dataclass
class 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
@classmethod
def 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.py
index f3b3c31e..d482845a 100644
--- a/semantica/kg/temporal_query.py
+++ b/semantica/kg/temporal_query.py
@@ -6,6 +6,7 @@ import copy
import warnings
from datetime import datetime, timedelta, timezone
from typing import Any, Dict, List, Optional
+from uuid import uuid4
from ..utils.progress_tracker import get_progress_tracker
from .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 None
try:
return parse_temporal_value(time_value)
except TemporalValidationError:
@@ -927,7 +930,10 @@ class TemporalVersionManager:
and relationship type. This preserves all prior versions instead of
trying 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_label
original_snapshot_inserted = False
if 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 = True
revised_snapshot["label"] = revised_label
revised_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.py
index 0f0000fd..45e5e747 100644
--- a/tests/change_management/test_temporal_versioning.py
+++ b/tests/change_management/test_temporal_versioning.py
@@ -9,6 +9,7 @@ import os
import tempfile
import pytest
from datetime import datetime, timezone
+from unittest.mock import patch
from semantica.kg.temporal_query import TemporalVersionManager
from semantica.kg.temporal_model import TemporalBound
from semantica.change_management import ChangeLogEntry, InMemoryVersionStorage, SQLiteVersionStorage
@@ -280,6 +281,94 @@ class TestTemporalVersionManager:
assert original is not None
assert manager.get_version(revised["label"]) is not None
assert 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.py
index 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}