Detect duplicate version ranges and version downgrades in snapshot PRs (#1084)

Follow-up to #1083. Adds two new critical checks to the summarize-changes skill:

- Version conflict detection: scans the full toml file to find multiple
  versions of the same file type coexisting for the same range (e.g.,
  v1.1 and v1.2 of accounts.0-32.vi). These cause download conflicts.

- Version downgrade detection: identifies files replaced with a LOWER
  version than before (e.g., v1.2 -> v1.1), indicating a regression.

Both are flagged as critical and recommend not merging until investigated.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: wmitsuda

.claude/skills/summarize-changes/SKILL.md

@@ -15,9 +15,20 @@ If $PR_URL_OR_NUMBER is a full URL, extract the PR number from it. If it is just
 Run these commands using the Bash tool:
 
 1. `gh pr view <number> --repo erigontech/erigon-snapshot` to get PR title, description, and metadata
-2. Save the diff to a temp file and run the analysis script:
+2. Save the diff to a temp file:
    ```
-   gh pr diff <number> --repo erigontech/erigon-snapshot > /tmp/pr_diff.txt && python3 "$(git rev-parse --show-toplevel)/.claude/skills/summarize-changes/analyze_diff.py" /tmp/pr_diff.txt
+   gh pr diff <number> --repo erigontech/erigon-snapshot > /tmp/pr_diff.txt
+   ```
+3. Fetch the full toml file from the PR's head branch:
+   ```
+   HEAD_REF=$(gh pr view <number> --repo erigontech/erigon-snapshot --json headRefName -q .headRefName)
+   TOML_FILE=$(gh pr diff <number> --repo erigontech/erigon-snapshot --name-only | head -1)
+   gh api "repos/erigontech/erigon-snapshot/contents/$TOML_FILE" \
+     -H "Accept: application/vnd.github.raw" -F ref="$HEAD_REF" > /tmp/pr_toml.txt
+   ```
+4. Run the analysis script with both files:
+   ```
+   python3 "$(git rev-parse --show-toplevel)/.claude/skills/summarize-changes/analyze_diff.py" /tmp/pr_diff.txt /tmp/pr_toml.txt
    ```
 
 The script (`analyze_diff.py` in the skill directory) parses the diff, classifies all changes, and outputs structured sections. Use its output to build the final report.
@@ -27,8 +38,10 @@ The script (`analyze_diff.py` in the skill directory) parses the diff, classifie
 - **Hash Changes**: same filename in both removed and added sets with different hash (CRITICAL)
 - **Range Merges**: multiple smaller removed ranges replaced by a single larger added range
 - **Version Upgrades**: removed entries at one version replaced by added entries at a newer version
+- **Version Downgrades**: removed entries at one version replaced by added entries at a LOWER version (CRITICAL — indicates regression)
 - **New Data Pruned from MDBX**: added entries beyond the previously highest block number
 - **Unexpected Deletions**: removed entries not covered by any of the above (CRITICAL)
+- **Version Conflicts**: multiple versions of the same file type and range coexisting in the final toml (CRITICAL)
 
 ## Step 4: Generate Report
 
@@ -93,6 +106,28 @@ If NO unexpected deletions, use ✅ emoji:
 
 ---
 
+### VERSION CONFLICTS
+
+If version conflicts exist, use 🚨 emoji:
+
+### 🚨🚨🚨 VERSION CONFLICTS — DO NOT MERGE
+
+> **Multiple versions of the same file for the same range must not coexist. This will cause download conflicts for nodes.**
+
+Group by State Snapshots / CL Snapshots / EL Block Snapshots. Show a table:
+
+| Type | Ext | Range | Versions |
+|------|-----|-------|----------|
+| accounts | .vi | 0-32 | v1.1, v1.2 |
+
+If NO version conflicts, use ✅ emoji:
+
+### ✅ Version Conflicts
+
+**No version conflicts detected.** Each file type has exactly one version per range.
+
+---
+
 ### Merged Ranges
 
 Present merges in a table format, with one table per high-level group (State Snapshots / CL Snapshots / EL Block Snapshots). Sort rows by subdir (accessor, domain, history, idx, caplin, or root) then by snapshot type (datatype).
@@ -139,6 +174,28 @@ Use continuation rows (empty Subdir cell) for subsequent files in the same subdi
 
 ---
 
+### VERSION DOWNGRADES
+
+If version downgrades exist, use 🚨 emoji:
+
+### 🚨🚨🚨 VERSION DOWNGRADES — DO NOT MERGE
+
+> **Files were replaced with a LOWER version than they had before. This is a regression that needs investigation.**
+
+Group by State Snapshots / CL Snapshots / EL Block Snapshots. Show a table:
+
+| Subdir | Type | Ext | Old Version | New Version | Ranges |
+|--------|------|-----|-------------|-------------|--------|
+| accessor | accounts | .vi | v1.2 | v1.1 | 0-256, 256-512, 512-768 |
+
+If NO version downgrades, use ✅ emoji:
+
+### ✅ Version Downgrades
+
+**No version downgrades detected.** All version changes go to equal or higher versions.
+
+---
+
 ### Version Upgrades
 
 Group by State Snapshots / CL Snapshots / EL Block Snapshots. List version transitions (e.g., v1.1 -> v2.0) by category and datatype.
@@ -153,20 +210,21 @@ Any changes to Other Files (salt files, etc.) or anything not fitting the above
 
 ### Reviewer Recommendation
 
-Based on the two critical signals (hash changes and unexpected deletions), add a final recommendation section:
+Based on the four critical signals (hash changes, unexpected deletions, version conflicts, and version downgrades), add a final recommendation section:
 
-If NO hash changes AND NO unexpected deletions:
+If NO hash changes AND NO unexpected deletions AND NO version conflicts AND NO version downgrades:
 
 ### ✅ Recommendation: Safe to Approve
 
 This PR contains only routine changes: range merges, version upgrades, and new data pruned from MDBX. No anomalies detected.
 
-If hash changes OR unexpected deletions exist:
+If hash changes OR unexpected deletions OR version conflicts OR version downgrades exist:
 
 ### 🚨 Recommendation: Investigation Required
 
 This PR contains changes that need manual review before approval:
-- (list each concern: N hash change(s), N unexpected deletion(s), with brief context from the sections above)
+- (list each concern: N hash change(s), N unexpected deletion(s), N version conflict(s), N version downgrade(s), with brief context from the sections above)
+- Version conflicts and version downgrades specifically mean "do not merge" — they will cause download conflicts or regressions for nodes
 
 ## Step 5: Offer to Post as PR Comment
 

.claude/skills/summarize-changes/analyze_diff.py

@@ -1,11 +1,13 @@
 #!/usr/bin/env python3
 """Analyze a snapshot PR diff file and classify all changes.
 
-Usage: python3 analyze_diff.py <diff_file>
+Usage: python3 analyze_diff.py <diff_file> [toml_file]
 
 The diff file should be the raw output of `gh pr diff`.
+The optional toml_file is the full toml from the PR branch, used to detect
+version conflicts (multiple versions of the same file type coexisting).
 Outputs structured text sections for hash changes, merges, version upgrades,
-new data pruned from MDBX, and unexpected deletions.
+new data pruned from MDBX, unexpected deletions, and version conflicts.
 """
 
 import re
@@ -57,6 +59,35 @@ def hgroup(cat):
     return "other"
 
 
+def parse_ver(v):
+    return tuple(int(x) for x in v.lstrip("v").split("."))
+
+
+def parse_toml(path):
+    filenames = []
+    with open(path) as f:
+        for line in f:
+            m = re.match(r"^'([^']+)'\s*=\s*'[a-f0-9]+'", line.strip())
+            if m:
+                filenames.append(m.group(1))
+    return filenames
+
+
+def detect_version_conflicts(filenames):
+    groups = defaultdict(set)
+    for fname in filenames:
+        info = parse_filename(fname)
+        if info["cat"] in ("other", "unknown"):
+            continue
+        key = (info["cat"], info["dt"], info["ext"], info["s"], info["e"])
+        groups[key].add(info["ver"])
+    conflicts = {}
+    for key, versions in groups.items():
+        if len(versions) >= 2:
+            conflicts[key] = sorted(versions)
+    return conflicts
+
+
 def classify(removed, added):
     # 1. Hash changes
     hash_changes = []
@@ -126,7 +157,7 @@ def classify(removed, added):
     return hash_changes, merges, version_upgrades_list, frontier, unexpected
 
 
-def print_report(removed, added, hash_changes, merges, version_upgrades_list, frontier, unexpected):
+def print_report(removed, added, hash_changes, merges, version_upgrades_list, frontier, unexpected, version_conflicts=None):
     # Hash changes
     print("=== HASH CHANGES ===")
     for f, oh, nh in hash_changes:
@@ -140,6 +171,14 @@ def print_report(removed, added, hash_changes, merges, version_upgrades_list, fr
         print(f"  [{hgroup(u['cat'])}] {u['fname']}")
     print(f"  count={len(unexpected)}")
 
+    # Version conflicts
+    if version_conflicts is not None:
+        print("=== VERSION CONFLICTS ===")
+        for (cat, dt, ext, s, e), versions in sorted(version_conflicts.items()):
+            ver_str = ", ".join(f"{v} (.{ext})" for v in versions)
+            print(f"  [{hgroup(cat)}] {cat}/{dt} range {s}-{e}: {ver_str}")
+        print(f"  count={len(version_conflicts)}")
+
     # Merges table
     print("=== MERGES TABLE ===")
     mp = defaultdict(list)
@@ -162,14 +201,28 @@ def print_report(removed, added, hash_changes, merges, version_upgrades_list, fr
         types_str = ", ".join(sorted(set(items)))
         print(f"  [{hg}] | {cat} | {types_str} | {old_r} | {ar[0]}-{ar[1]} [{nv}] | {note}")
 
-    # Version upgrades
-    print("=== VERSION UPGRADES ===")
-    vup = defaultdict(list)
+    # Version upgrades and downgrades
+    upgrades = defaultdict(list)
+    downgrades = defaultdict(list)
     for vu in version_upgrades_list:
         vk = (hgroup(vu["cat"]), vu["cat"], tuple(sorted(vu["old_vers"])), vu["new_ver"])
         rr = [(s, e) for s, e, v in vu["rem_ranges"]]
-        vup[vk].append(f"{vu['dt']} (.{vu['ext']}): {', '.join(f'{s}-{e}' for s, e in rr)} -> {vu['add_range'][0]}-{vu['add_range'][1]}")
-    for (hg, cat, ov, nv), items in sorted(vup.items()):
+        detail = f"{vu['dt']} (.{vu['ext']}): {', '.join(f'{s}-{e}' for s, e in rr)} -> {vu['add_range'][0]}-{vu['add_range'][1]}"
+        max_old = max(parse_ver(v) for v in vu["old_vers"])
+        if parse_ver(vu["new_ver"]) < max_old:
+            downgrades[vk].append(detail)
+        else:
+            upgrades[vk].append(detail)
+
+    print("=== VERSION DOWNGRADES ===")
+    for (hg, cat, ov, nv), items in sorted(downgrades.items()):
+        print(f"  [{hg}] {cat}: {','.join(ov)} -> {nv}")
+        for i in sorted(items):
+            print(f"    {i}")
+    print(f"  count={sum(len(v) for v in downgrades.values())}")
+
+    print("=== VERSION UPGRADES ===")
+    for (hg, cat, ov, nv), items in sorted(upgrades.items()):
         print(f"  [{hg}] {cat}: {','.join(ov)} -> {nv}")
         for i in sorted(items):
             print(f"    {i}")
@@ -190,14 +243,21 @@ def print_report(removed, added, hash_changes, merges, version_upgrades_list, fr
 
 
 def main():
-    if len(sys.argv) != 2:
-        print(f"Usage: {sys.argv[0]} <diff_file>", file=sys.stderr)
+    if len(sys.argv) < 2 or len(sys.argv) > 3:
+        print(f"Usage: {sys.argv[0]} <diff_file> [toml_file]", file=sys.stderr)
         sys.exit(1)
 
     diff_file = sys.argv[1]
     removed, added = parse_diff(diff_file)
     hash_changes, merges, version_upgrades_list, frontier, unexpected = classify(removed, added)
-    print_report(removed, added, hash_changes, merges, version_upgrades_list, frontier, unexpected)
+
+    version_conflicts = None
+    if len(sys.argv) == 3:
+        toml_file = sys.argv[2]
+        filenames = parse_toml(toml_file)
+        version_conflicts = detect_version_conflicts(filenames)
+
+    print_report(removed, added, hash_changes, merges, version_upgrades_list, frontier, unexpected, version_conflicts)
 
 
 if __name__ == "__main__":