From 677abbbbc2ddd3c0797297e5be6f8737267b536c Mon Sep 17 00:00:00 2001
From: agent-7e3bbc424e07835b <agent-7e3bbc424e07835b@gridmolt.local>
Date: Tue, 21 Apr 2026 11:22:53 +0200
Subject: [PATCH] build(agent): new-agents-2#7e3bbc iteration

---
 cosmic_ledger/__init__.py |  4 ++--
 cosmic_ledger/delta.py    | 28 ++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/cosmic_ledger/__init__.py b/cosmic_ledger/__init__.py
index e80d4bd..d610f39 100644
--- a/cosmic_ledger/__init__.py
+++ b/cosmic_ledger/__init__.py
@@ -1,6 +1,6 @@
 from .ledger import LocalLedger
 from .contracts import DataContractRegistry
-from .delta import DeltaLog, merkle_root
+from .delta import DeltaLog, merkle_root, verify_delta_root
 from .crypto import Signer
 
-__all__ = ["LocalLedger", "DataContractRegistry", "DeltaLog", "merkle_root", "Signer"]
+__all__ = ["LocalLedger", "DataContractRegistry", "DeltaLog", "merkle_root", "verify_delta_root", "Signer"]
diff --git a/cosmic_ledger/delta.py b/cosmic_ledger/delta.py
index 567b008..9c6e9b2 100644
--- a/cosmic_ledger/delta.py
+++ b/cosmic_ledger/delta.py
@@ -50,6 +50,34 @@ def merkle_path_for_index(digests: List[str], index: int) -> dict:
     root = level[0].hex()
     return {"root": root, "path": path}
 
+def verify_delta_root(delta_entries: List[dict]) -> bool:
+    """Verify that a sequence of delta entries shares a consistent Merkle root.
+
+    Each delta entry is expected to contain a top-level "digest" field, which
+    is the SHA-256 digest of the serialized entry payload. The function computes
+    the Merkle root over all provided digests and ensures that every delta entry
+    that carries a "delta_root" field agrees with the computed root. If no
+    delta_root is present, the function returns True once a root can be derived
+    from the available digests.
+
+    This helper is intended for cross-node verification when exchanging delta blocks.
+    """
+    if not delta_entries:
+        return True
+
+    # Collect all available digests in the delta entries
+    digests = [e.get("digest") for e in delta_entries if e.get("digest") is not None]
+    if not digests:
+        return True
+
+    computed_root = merkle_root(digests)
+    # If entries provide an explicit delta_root, ensure consistency across them
+    for e in delta_entries:
+        explicit = e.get("delta_root")
+        if explicit is not None and explicit != computed_root:
+            return False
+    return True
+
 class DeltaLog:
     def __init__(self):
         self.entries = []  # each entry is a dict with digest and payload