Backport release/v6.7: fix(memiavl): hold a snapshot reference for an iterator's lifetime

[seidroid]

Backport of #4291 to release/v6.7.

[cursor]

PR Summary

Medium Risk
Touches core state-DB iteration and snapshot refcounting; incorrect refcounting could leak mmap mappings or delay snapshot cleanup, but the change is narrowly scoped with targeted regression tests.

Overview
Fixes a fatal mmap use-after-unmap when a memiavl tree iterator stays open across snapshot rewrite/reload.

Iterator lifecycle: NewIterator now takes an optional *Snapshot, acquires it when non-nil, and releases it on Close. Close also nils cached key/value so zero-copy slices cannot point at unmapped pages after close. Tree.Iterator passes t.snapshot under the read lock so the backing mmap cannot be torn down while iteration continues after the tree lock is released.

Tests: Adds regression coverage that iteration survives rewrite/reload (non-zero-copy clone path) and that snapshot refcount increments/decrements correctly on iterator open/close (including idempotent double-close).

^{Reviewed by Cursor Bugbot for commit 86067da. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Sep 24, 2026, 1:22 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.62%. Comparing base (bdf3c15) to head (86067da).

Additional details and impacted files

@@               Coverage Diff                @@
##           release/v6.7    #4313      +/-   ##
================================================
- Coverage         61.36%   60.62%   -0.74%     
================================================
  Files              2163     2083      -80     
  Lines            189065   180455    -8610     
================================================
- Hits             116014   109397    -6617     
+ Misses            62320    61028    -1292     
+ Partials          10731    10030     -701     

Flag	Coverage Δ
sei-db	69.80% <ø> (ø)
sei-db-state-db	?
sei-db-state-db-pr	77.38% <100.00%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sei-db/state_db/sc/memiavl/iterator.go	100.00% <100.00%> (ø)
sei-db/state_db/sc/memiavl/tree.go	88.88% <100.00%> (ø)

... and 109 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[seidroid]

Clean backport of #4291: Tree.Iterator now takes a refcount on the backing *Snapshot under the tree's read lock and Iterator.Close returns it, closing the window where a concurrent snapshot rewrite/reload could unmap pages an open iterator was still reading. I verified the diff is byte-identical to the merged upstream PR, that the single NewIterator caller was updated, and that the acquire/release pairing is correct and idempotent; no PR-introduced issues found.

Findings: 0 blocking | 1 non-blocking | 0 posted inline

Blockers

• None at the file/PR level.

Non-blocking

• None at the file/PR level.
• 1 non-blocking pre-existing issue(s) listed below under pre-existing issues.

Pre-existing issues

• [suggestion] Tree.Iterator (sei-db/state_db/sc/memiavl/tree.go:346) captures t.root under the read lock but the returned iterator walks it lock-free after the lock is released, and — unlike Tree.Copy — it does not hash the reachable nodes or raise cowVersion. A concurrent Set/Remove therefore mutates in place any reachable MemNode above cowVersion (via MemNode.Mutate), so iterating a live tree while it is written races on the unpersisted half of the tree. This PR closes the mmap half of the same hazard; the heap half remains. Note also that CompositeCommitStore.iterate's comment (sei-db/state_db/sc/composite/store.go:1499) claims "memiavl captures a COW root under the tree lock," which is not what Tree.Iterator currently does. Pre-existing on the base branch and unchanged by this diff.

[alexander-sei]

@seidroid review

[seidroid]

Clean backport of #4291 to release/v6.7: the PR diff is byte-identical to the merged upstream change, the single NewIterator caller is updated, and the snapshot acquire/release pairing is correct and idempotent. No PR-introduced issues found.

Findings: 0 blocking | 1 non-blocking | 0 posted inline

Blockers

• None at the file/PR level.

Non-blocking

• None at the file/PR level.
• 1 non-blocking pre-existing issue(s) listed below under pre-existing issues.

Pre-existing issues

• [suggestion] Tree.Iterator (sei-db/state_db/sc/memiavl/tree.go:346) captures t.root under the read lock but the returned iterator walks it lock-free once the lock is released, and — unlike Tree.Copy — it neither hashes the reachable nodes nor raises cowVersion. A concurrent Set/Remove can therefore mutate in place any reachable MemNode above cowVersion (via MemNode.Mutate), so iterating a live tree while it is written still races on the unpersisted half of the tree. This PR closes the mmap half of the hazard; the heap half remains. Relatedly, CompositeCommitStore.iterate's comment (sei-db/state_db/sc/composite/store.go:1500) claims "memiavl captures a COW root under the tree lock," which is not what Tree.Iterator does. Pre-existing on the base branch and unchanged by this diff.