feat(flatkv): add comprehensive writing test coverage and centralize account-field semantics

[blindchaser]

Summary

Centralize account-field read/delete semantics into explicit AccountValue methods, remove dead pendingAccountWrite.isDelete code path, fix fullScanLtHash legacyDB omission, and add comprehensive write/persistence/fault-tolerance test coverage across all FlatKV sub-DBs.

KVPair.Delete for account fields (nonce, codehash) is a field reset within AccountValue, not a physical row removal. NonceBytes always returns (zero, true) for zero nonce; CodeHashBytes returns (nil, false) for zero codehash. Storage, code, and legacy deletes remain physical tombstones. The accountDB row always persists -- there is no row-level delete.

• keys.go: Add NonceBytes, CodeHashBytes, ClearNonce, ClearCodeHash to AccountValue. Each method encodes the asymmetric nonce/codehash delete contract at the type level.
• store.go: Remove isDelete from pendingAccountWrite. Document that account-field deletes are field resets, not row tombstones.
• store_read.go: Replace duplicated inline nonce/codehash extraction (2 call sites) with NonceBytes()/CodeHashBytes(). Remove dead paw.isDelete guard and unused encoding/binary import.
• store_write.go: ApplyChangeSets delete path calls ClearNonce()/ClearCodeHash() instead of manual zeroing. LtHash pair construction enforces Delete: false for account rows. commitBatches removes dead paw.isDelete branch -- account writes always use Set.
• lthash_correctness_test.go: fullScanLtHash now includes legacyDB scan, fixing an omission where legacy entries were excluded from ground-truth LtHash computation.
• store_test.go, store_read_test.go, store_write_test.go: All test changeset names corrected from "test"/"empty"/"write"/"delete" to "evm" so data flows through the actual EVM key routing path.

Test plan

keys_test.go -- 4 new unit tests:

• TestAccountValueNonceBytes: zero, non-zero, max uint64 nonce encoding; always found=true.
• TestAccountValueCodeHashBytes: zero codehash returns (nil, false); non-zero returns bytes.
• TestAccountValueClearNonce: zeroes nonce, preserves codehash.
• TestAccountValueClearCodeHash: zeroes codehash, preserves nonce.

store_write_test.go -- 8 new tests:

• TestDeleteSemanticsCodehashAsymmetry: nonce delete returns (zero, found=true), codehash delete returns (nil, found=false), accountDB row persists, code physically deleted.
• TestCrossApplyChangeSetsOrdering: write-then-delete and delete-then-write for storage keys within same block.
• TestCrossApplyChangeSetsAccountOrdering: 4 subtests for nonce/codehash write-delete ordering and asymmetric visibility.
• TestEmptyCommitWALPayloadsDiffer: nil vs empty changeset WAL payload distinction.
• TestSubDBEntryCount: live entry counts after writes, overwrites, and deletes across sub-DBs; account delete does not reduce count.
• TestApplyChangeSetsInvalidNonceLength / TestApplyChangeSetsInvalidCodehashLength: input validation error paths.
• TestAccountValueEncodingTransition: EOA (40 bytes) to contract (72 bytes) and back via codehash add/delete; nonce survives transitions.

lthash_correctness_test.go -- 6 new tests:

• TestFullScanLtHashIncludesLegacy: ground-truth scan covers legacyDB.
• TestLtHashCrossApply{Account,Storage,Code,Legacy,Mixed}Overwrite: same-key overwrite across two ApplyChangeSets calls in one block, full-scan verified for each key type and all types combined.

snapshot_test.go -- 7 new tests:

• TestReopenAfterEmptyCommits / TestReopenAfterDeletes: version and LtHash persistence across close/reopen; asymmetric nonce/codehash delete visibility after restart.
• TestWALTruncationThenRollback: snapshot + WAL truncation + rollback to earlier version.
• TestReopenAfterSnapshotAndTruncation: reopen from snapshot after WAL truncation.
• TestSingleDBOpenFailure / TestGlobalMetadataCorruption / TestLocalMetaCorruption: fault injection -- corrupt MANIFEST, global version, local meta; LoadVersion rejects.
• TestWALDirectoryDeleted: recovery from missing WAL directory when snapshot is current.
• TestWALSegmentCorruption: corrupt WAL segments prevent catchup to target version.

store_meta_test.go -- 1 new test:

• TestGlobalMetadataPersistence: global version and LtHash checksum survive close/reopen via metadataDB.

[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	Mar 12, 2026, 5:39 AM

[codecov]

Codecov Report

❌ Patch coverage is 81.81818% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.35%. Comparing base (56ed5a7) to head (f9c5a60).

Files with missing lines	Patch %	Lines
sei-db/state_db/sc/flatkv/store_read.go	50.00%	2 Missing ⚠️
sei-db/state_db/sc/flatkv/store_write.go	66.66%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3057      +/-   ##
==========================================
+ Coverage   58.32%   58.35%   +0.02%     
==========================================
  Files        2079     2079              
  Lines      171899   171897       -2     
==========================================
+ Hits       100268   100318      +50     
+ Misses      62674    62636      -38     
+ Partials     8957     8943      -14     

Flag	Coverage Δ
sei-chain-pr	67.15% <81.81%> (?)
sei-db	70.41% <ø> (ø)

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/flatkv/keys.go	100.00% <100.00%> (ø)
sei-db/state_db/sc/flatkv/store.go	72.72% <ø> (+12.25%)	⬆️
sei-db/state_db/sc/flatkv/store_read.go	64.34% <50.00%> (+7.50%)	⬆️
sei-db/state_db/sc/flatkv/store_write.go	80.07% <66.66%> (+2.25%)	⬆️

🚀 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.