semantica/docs/reference/change_management.md

title, description, icon

title	description	icon
Change Management Module	Version control, SHA-256 checksums, diff analysis, rollback, and audit trails for knowledge graphs and ontologies.	clock-rotate-left

Enterprise-grade version control and audit trails for knowledge graphs with data integrity verification.

---

Overview

The Change Management Module provides versioning for knowledge graphs — SHA-256 checksums, full snapshot history, diff analysis, rollback protection, and compliance-grade audit trails (HIPAA, SOX, FDA 21 CFR Part 11).

Snapshot, diff, rollback, and audit trail for knowledge graphs. Version control for OWL ontologies with diff and migration support. Pluggable storage — in-memory for tests, SQLite for production. SHA-256 checksums to detect unauthorized modifications.

---

TemporalVersionManager

Version control for knowledge graphs:

from semantica.change_management import TemporalVersionManager

manager = TemporalVersionManager(storage_path="versions.db")

# Create a snapshot
snapshot_id = manager.create_snapshot(
    graph=kg,
    version="v1.0",
    author="user@example.com",
    message="Initial knowledge graph"
)

print(f"Snapshot {snapshot_id}")
print(f"Checksum: {manager.get_checksum(snapshot_id)}")

---

Versioning

# List all versions
versions = manager.list_versions()
for v in versions:
    print(f"{v.version} — {v.author} — {v.created_at} — {v.checksum[:8]}...")

# Retrieve a specific version
kg_v1 = manager.get_version("v1.0")

# Rollback
manager.rollback(target_version="v1.0", allow_data_loss=False)

---

Diff Analysis

diff = manager.diff("v1.0", "v2.0")

print(f"Added nodes:    {len(diff.added_nodes)}")
print(f"Removed nodes:  {len(diff.removed_nodes)}")
print(f"Modified edges: {len(diff.modified_edges)}")

for change in diff.changes:
    print(f"  [{change.type}] {change.element}: {change.description}")

---

OntologyVersionManager

Version control for OWL ontologies:

from semantica.change_management import OntologyVersionManager, OntologyVersion

manager = OntologyVersionManager()

# Save a version
version: OntologyVersion = manager.save_version(
    ontology=ontology,
    version="1.2.0",
    author="ontology-team",
    message="Added FHIR alignment mappings"
)

# Diff two ontology versions
diff = manager.diff("1.1.0", "1.2.0")
for change in diff.changes:
    print(f"[{change.type}] {change.class_name}: {change.description}")

---

VersionStorage

Pluggable storage backends:

from semantica.change_management import (
    VersionStorage,
    InMemoryVersionStorage,
    SQLiteVersionStorage,
)

# In-memory (tests and development)
storage = InMemoryVersionStorage()

# SQLite (production — persistent across restarts)
storage = SQLiteVersionStorage(db_path="versions.db")

# Pass to a version manager
manager = TemporalVersionManager(storage=storage)

---

Integrity Verification

SHA-256 checksums detect any unauthorized modification to the graph:

from semantica.change_management import compute_checksum, verify_checksum

# Compute checksum for a graph
checksum = compute_checksum(kg)

# Verify graph against stored checksum
is_valid = verify_checksum(kg, expected_checksum=checksum)

if not is_valid:
    print("Warning: Graph has been modified since the checksum was recorded")

---

Audit Trail

# Full audit trail for an entity
trail = manager.get_audit_trail(entity_id="apple_inc")
for entry in trail:
    print(f"{entry.timestamp} — {entry.author}: {entry.action} — {entry.description}")

# Export audit trail
manager.export_audit_trail("audit.csv",  format="csv")
manager.export_audit_trail("audit.json", format="json")

---

ChangeLogEntry

Every version snapshot includes a structured ChangeLogEntry:

from semantica.change_management import ChangeLogEntry

entry: ChangeLogEntry = manager.get_log_entry(snapshot_id)

print(entry.version)
print(entry.author)
print(entry.message)
print(entry.checksum)
print(entry.created_at)
print(entry.changes)    # list of individual change records

---

See Also

W3C PROV-O lineage tracking. The graph being versioned. Export versioned snapshots. Detect conflicts introduced between versions.