execution/cache, execution/commitment: address #22154 review

- CodeStore.Evict: tableSizeBytes starts at 0 each process start, so a
  persistent TblCodeCache that already exceeds the cap would never be pruned
  (unbounded growth across restarts). Seed it once from the table via
  sumTableBytes, in the same key+value byte units the eviction loop decrements.
- BranchCache.Get: only count a pinned hit/miss when the prefix actually routes
  to a pinned storage trunk; account-trie and tail-only lookups no longer
  inflate pinnedMisses.
- AdaptivePinController: the value threaded through OnBlockComplete is a txNum
  (that is what SharedDomains has at commit), not a block number; rename the
  parameter, the write-only promotedAtBlock field, and the log keys to txNum so
  the diagnostics are accurate. No behaviour change.

Author: mh0lt

execution/cache/code_store.go

@@ -21,6 +21,7 @@ type CodeStore struct {
 	// LRU and entries re-derive from CodeDomain.
 	tableCapBytes  uint64
 	tableSizeBytes atomic.Int64
+	tableSeeded    atomic.Bool
 
 	memHits   atomic.Uint64
 	tableHits atomic.Uint64
@@ -97,7 +98,21 @@ func (s *CodeStore) PutByHash(tx kv.RwTx, codeHash, code []byte) error {
 // order when over capacity. Safe: evicted entries are re-derivable from
 // CodeDomain on miss. Call on a write tx (e.g., at commit), never on reads.
 func (s *CodeStore) Evict(tx kv.RwTx) error {
-	if s == nil || s.tableCapBytes == 0 || uint64(s.tableSizeBytes.Load()) <= s.tableCapBytes {
+	if s == nil || s.tableCapBytes == 0 {
+		return nil
+	}
+	// tableSizeBytes starts at 0 each process start; seed it once from the
+	// persistent table (in the same key+value byte units the eviction loop
+	// decrements) so a backing that already exceeds the cap gets pruned rather
+	// than growing unbounded across restarts.
+	if s.tableSeeded.CompareAndSwap(false, true) {
+		total, err := sumTableBytes(tx)
+		if err != nil {
+			return err
+		}
+		s.tableSizeBytes.Store(total)
+	}
+	if uint64(s.tableSizeBytes.Load()) <= s.tableCapBytes {
 		return nil
 	}
 	c, err := tx.RwCursor(kv.TblCodeCache)
@@ -121,3 +136,21 @@ func (s *CodeStore) Evict(tx kv.RwTx) error {
 	}
 	return nil
 }
+
+// sumTableBytes returns the total key+value byte size of TblCodeCache, in the
+// same units Evict tracks and decrements.
+func sumTableBytes(tx kv.RwTx) (int64, error) {
+	c, err := tx.Cursor(kv.TblCodeCache)
+	if err != nil {
+		return 0, err
+	}
+	defer c.Close()
+	var total int64
+	for k, v, err := c.First(); k != nil; k, v, err = c.Next() {
+		if err != nil {
+			return 0, err
+		}
+		total += int64(len(k) + len(v))
+	}
+	return total, nil
+}

execution/cache/code_store_test.go

@@ -60,4 +60,13 @@ func TestCodeStore_TwoTierAndEvict(t *testing.T) {
 	}
 	require.NoError(t, small.Evict(tx))
 	require.LessOrEqual(t, small.tableSizeBytes.Load(), int64(128))
+
+	// Restart scenario: a fresh store (tableSizeBytes=0) over an already-full
+	// backing must still prune — seed the size from the table, don't grow
+	// unbounded. Without the seed, Evict's under-cap early return would skip.
+	restarted := NewCodeStore(1<<20, 128)
+	require.Zero(t, restarted.tableSizeBytes.Load())
+	require.NoError(t, restarted.Evict(tx))
+	require.LessOrEqual(t, restarted.tableSizeBytes.Load(), int64(128),
+		"a fresh store must seed its size from the backing and prune, not grow unbounded across restarts")
 }

execution/commitment/adaptive_pin.go

@@ -71,7 +71,7 @@ type DbBranchesProvider func(contractHash []byte) map[string][]byte
 
 type adaptiveContractState struct {
 	contractHash     [32]byte
-	promotedAtBlock  uint64
+	promotedAtTxNum  uint64
 	preload          *ContractTrunkPreload         // serial-BFS path (nil when parallel)
 	parallel         *ContractTrunkPreloadParallel // parallel-wave-BFS path (nil when serial)
 	coldBlocksInARow int
@@ -161,7 +161,7 @@ func (c *AdaptivePinController) onCacheMiss(prefix []byte) {
 // OnBlockComplete consumes the per-block miss snapshot and decides
 // promotions, extensions, and demotions. Synchronous — preloads run
 // inline so the new pin set is available for the next block's reads.
-func (c *AdaptivePinController) OnBlockComplete(ctx context.Context, blockNum uint64, reader CommitmentReader) {
+func (c *AdaptivePinController) OnBlockComplete(ctx context.Context, txNum uint64, reader CommitmentReader) {
 	misses := c.snapshotMisses()
 
 	c.mu.Lock()
@@ -173,7 +173,7 @@ func (c *AdaptivePinController) OnBlockComplete(ctx context.Context, blockNum ui
 	if c.parallelResolverFactory != nil {
 		r, release, err := c.parallelResolverFactory()
 		if err != nil {
-			c.warnf("[adaptive-pin] parallel resolver factory failed, falling back to serial", "err", err, "block", blockNum)
+			c.warnf("[adaptive-pin] parallel resolver factory failed, falling back to serial", "err", err, "txNum", txNum)
 		} else {
 			parallelResolve = r
 			releaseParallel = release
@@ -215,7 +215,7 @@ func (c *AdaptivePinController) OnBlockComplete(ctx context.Context, blockNum ui
 	if len(misses) > 0 && len(c.states) < c.cfg.MaxPromotedContracts {
 		candidates := pickPromotionCandidates(misses, c.cfg.PromoteThresholdMisses, c.cfg.MaxPromotedContracts-len(c.states))
 		for _, hash := range candidates {
-			state, err := c.promoteLocked(ctx, hash, blockNum, parallelResolve, reader)
+			state, err := c.promoteLocked(ctx, hash, txNum, parallelResolve, reader)
 			if err != nil {
 				c.warnf("[adaptive-pin] initial-view failed", "hash", hex.EncodeToString(hash[:]), "err", err)
 				continue
@@ -238,7 +238,7 @@ func (c *AdaptivePinController) OnBlockComplete(ctx context.Context, blockNum ui
 
 	if c.logger != nil && (promoted+extended+demoted > 0 || len(c.states) > 0) {
 		c.logger.Info("[adaptive-pin]",
-			"block", blockNum,
+			"txNum", txNum,
 			"promoted_total", len(c.states),
 			"promoted_this_block", promoted,
 			"extended_this_block", extended,
@@ -278,7 +278,7 @@ func (c *AdaptivePinController) demoteLocked(hash [32]byte, state *adaptiveContr
 func (c *AdaptivePinController) promoteLocked(
 	ctx context.Context,
 	hash [32]byte,
-	blockNum uint64,
+	txNum uint64,
 	parallelResolve BatchBranchResolver,
 	reader CommitmentReader,
 ) (*adaptiveContractState, error) {
@@ -299,7 +299,7 @@ func (c *AdaptivePinController) promoteLocked(
 		}
 		return &adaptiveContractState{
 			contractHash:    hash,
-			promotedAtBlock: blockNum,
+			promotedAtTxNum: txNum,
 			parallel:        p,
 		}, nil
 	}
@@ -315,7 +315,7 @@ func (c *AdaptivePinController) promoteLocked(
 	}
 	return &adaptiveContractState{
 		contractHash:    hash,
-		promotedAtBlock: blockNum,
+		promotedAtTxNum: txNum,
 		preload:         p,
 	}, nil
 }

execution/commitment/branch_cache.go

@@ -483,6 +483,8 @@ func (c *BranchCache) lookup(prefix []byte) (*branchCacheEntry, bool) {
 		return nil, false
 	}
 	// Pinned tier: per-contract storage trunk (fixed skeleton + deep overflow).
+	// Only a lookup that actually routes to a pinned trunk counts toward the
+	// pinned hit/miss stats; account-trie and tail-only prefixes are excluded.
 	if st, _, stor, ok := c.storageRoute(prefix, false); ok {
 		var entry *branchCacheEntry
 		if slot := st.slot(stor); slot != nil {
@@ -494,8 +496,8 @@ func (c *BranchCache) lookup(prefix []byte) (*branchCacheEntry, bool) {
 			c.pinnedHits.Add(1)
 			return entry, true
 		}
+		c.pinnedMisses.Add(1)
 	}
-	c.pinnedMisses.Add(1)
 	entry, ok := c.tail.Get(maphash.Hash(prefix))
 	if !ok {
 		c.tailMisses.Add(1)