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(provenance): let verify_chain check an expected count and head (#2030) (#2033)
Kevinf346e76745fa
diff --git a/semantica/provenance/manager.py b/semantica/provenance/manager.pyindex 1a2b26f1..b28f7f8c 100644--- a/semantica/provenance/manager.py+++ b/semantica/provenance/manager.py@@ -1447,7 +1447,11 @@ class ProvenanceManager:"errors": errors,}- def verify_chain(self) -> Dict[str, Any]:+ def verify_chain(+ self,+ expected_count: Optional[int] = None,+ expected_head: Optional[str] = None,+ ) -> Dict[str, Any]:"""Verify the hash chain across all provenance entries (issue #825,Part A item 2).@@ -1470,12 +1474,37 @@ class ProvenanceManager:see integrity.py), which alone would let a checksum-only check missa gap that the sequence check still catches.+ Args:+ expected_count: Optional number of records the caller expects. A+ truncated store cannot be detected from inside the chain: the+ surviving rows are internally consistent, so ``valid`` stays+ true. Comparing against a count the caller already knows (the+ count the exporter wrote into its manifest) is what catches a+ dropped tail.+ expected_head: Optional checksum of the last expected record.+Returns:- Dictionary with "valid", "total_entries", and "broken_links"- (list of {"entity_id", "sequence_id", "reason"} dicts).+ Dictionary with "valid", "total_entries", "head", "broken_links"+ (list of {"entity_id", "sequence_id", "reason"} dicts),+ "count_matches", "head_matches" and "unsequenced_records".++ ``expected_count`` counts only chained (sequenced) records. A record+ stored without a ``sequence_id`` is outside the chain and is not+ counted; only direct storage access produces one, because every+ ``track_*`` call assigns a sequence. ``unsequenced_records`` reports+ how many such rows exist if you need to notice them. The last two are ``True`` when+ the corresponding expectation was not supplied, and ``valid`` is+ ``False`` when either supplied expectation disagrees.++ Note:+ ``invalidate()`` appends a revision rather than editing a row, so+ both the count and the head move after every mutation. Read them+ after all writes, not before."""+ stored = list(self.storage.retrieve_all())+ unsequenced = [e for e in stored if e.sequence_id is None]entries = sorted(- (e for e in self.storage.retrieve_all() if e.sequence_id is not None),+ (e for e in stored if e.sequence_id is not None),key=lambda e: e.sequence_id,)@@ -1513,9 +1542,17 @@ class ProvenanceManager:expected_previous = entry.checksumexpected_sequence = entry.sequence_id+ actual_head = entries[-1].checksum if entries else None+ count_matches = expected_count is None or expected_count == len(entries)+ head_matches = expected_head is None or expected_head == actual_head+return {- "valid": len(broken_links) == 0,+ "valid": len(broken_links) == 0 and count_matches and head_matches,"total_entries": len(entries),+ "head": actual_head,+ "count_matches": count_matches,+ "head_matches": head_matches,+ "unsequenced_records": len(unsequenced),"broken_links": broken_links,}diff --git a/tests/provenance/test_manager.py b/tests/provenance/test_manager.pyindex a505fe92..e6ee51b9 100644--- a/tests/provenance/test_manager.py+++ b/tests/provenance/test_manager.py@@ -1865,3 +1865,106 @@ class TestMixedFormatTimestampComparisons:prov_mgr = self._manager_with("not-a-timestamp", "2026-08-19T12:00:00+00:00")entries = prov_mgr.audit_log(since="2026-08-19T11:00:00", format="json")assert [e["entity_id"] for e in entries] == ["entity_1"]+++def test_verify_chain_rejects_a_truncated_store_when_the_count_is_known(tmp_path):+ """A dropped tail keeps the surviving rows internally consistent.++ The chain cannot see it; the caller's expected count can.+ """+ storage = str(tmp_path / "prov.json")+ manager = ProvenanceManager(storage_path=storage)+ for index in range(4):+ manager.track_entity(f"E-{index}", source="src", entity_type="row_set")++ full = manager.verify_chain()+ assert full["valid"] is True+ assert full["total_entries"] == 4+ head = full["head"]+ assert head++ # Drop the last record, the way a shortened export pack would.+ import sqlite3++ connection = sqlite3.connect(storage)+ connection.execute(+ "delete from provenance where sequence_id = (select max(sequence_id) from provenance)"+ )+ connection.commit()+ connection.close()++ truncated = ProvenanceManager(storage_path=storage)+ # Without an expectation the surviving three rows are still consistent.+ assert truncated.verify_chain()["valid"] is True+ # With one, the missing record is caught.+ result = truncated.verify_chain(expected_count=4, expected_head=head)+ assert result["valid"] is False+ assert result["count_matches"] is False+ assert result["head_matches"] is False+ assert result["total_entries"] == 3+++def test_verify_chain_passes_when_the_expectations_match(tmp_path):+ storage = str(tmp_path / "prov.json")+ manager = ProvenanceManager(storage_path=storage)+ manager.track_entity("E-0", source="src", entity_type="row_set")++ result = manager.verify_chain(expected_count=1, expected_head=manager.verify_chain()["head"])++ assert result["valid"] is True+ assert result["count_matches"] is True+ assert result["head_matches"] is True+++def test_an_unsequenced_record_is_invisible_to_the_expected_count(tmp_path):+ """A row without a sequence_id is outside the chain, so it is not counted.++ Only direct storage access can create one; every track_* call assigns a+ sequence. Such a row is still exported, which is why the count cannot see+ it, and the result is documented rather than silently surprising.+ """+ import sqlite3++ storage = str(tmp_path / "prov.json")+ manager = ProvenanceManager(storage_path=storage)+ for index in range(3):+ manager.track_entity(f"E-{index}", source="src", entity_type="row_set")++ connection = sqlite3.connect(storage)+ connection.execute(+ "insert into provenance (entity_id, entity_type, activity_id, agent_id,"+ " source_document, timestamp, first_seen, last_updated, confidence,"+ " checksum, metadata, version, sequence_id)"+ " select 'E-extra', entity_type, activity_id, agent_id, source_document,"+ " timestamp, first_seen, last_updated, confidence, checksum, metadata,"+ " version, NULL from provenance limit 1"+ )+ connection.commit()+ connection.close()++ result = ProvenanceManager(storage_path=storage).verify_chain(expected_count=3)++ assert result["unsequenced_records"] == 1+ assert result["count_matches"] is True+ assert result["valid"] is True+++def test_unsequenced_records_do_not_break_the_default_call(tmp_path):+ import sqlite3++ storage = str(tmp_path / "prov.json")+ manager = ProvenanceManager(storage_path=storage)+ manager.track_entity("E-0", source="src", entity_type="row_set")+ connection = sqlite3.connect(storage)+ connection.execute(+ "insert into provenance (entity_id, entity_type, activity_id, agent_id,"+ " source_document, timestamp, first_seen, last_updated, confidence,"+ " checksum, metadata, version, sequence_id)"+ " select 'E-extra', entity_type, activity_id, agent_id, source_document,"+ " timestamp, first_seen, last_updated, confidence, checksum, metadata,"+ " version, NULL from provenance limit 1"+ )+ connection.commit()+ connection.close()++ assert ProvenanceManager(storage_path=storage).verify_chain()["valid"] is True