Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

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.py
index 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 miss
a 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.checksum
expected_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.py
index 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