Add Eval() bitboard-migration plan, per-term EVAL_TIME cycle breakdown, drop redundant pawn-location bitboard

board_representation/EVAL.md: rewritten migration plan for a
bitboard-backed Eval() (mobility ray-walks + bvAttacks replacement),
plus a performance-philosophy section recording the profiling-first,
cut-aggressively-except-mobility/safety-awareness approach agreed on
this session, and findings on CountKingSafetyDefects' structural
inability to share bvAttacks-derived state with _EvalKing.

EVAL_TIME per-term instrumentation (chess.h/eval.c/root.c): breaks
the existing whole-Eval() cycle counter down by pawns/knight/bishop/
rook/queen/king, the always-paid pre-lazy-exit segment, and the
full-eval-only post-lazy segment, printed alongside the existing
"Avg. cpu cycles in eval" line. Diagnostic only (EVAL_TIME-gated),
no effect on the normal release profile.

Drop PAWN_HASH_ENTRY's bbPawnLocations[2]: it duplicated
POSITION's own incrementally-maintained bbPawns[2], rebuilt bit-by-bit
on every pawn-hash miss for no reason. eval.c now reads pos->bbPawns[]
directly; removed a stale per-iteration invariant assert in _EvalPawns
that only made sense when the bitboard was being built bit-by-bit in
that same loop.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01P6g6iF6mD1Hau6nCZCzwYj

1 files changed, 66 insertions, 8 deletions

diff --git a/src/chess.h b/src/chess.h
index ed903a5..f39a956 100755
--- a/src/chess.h
+++ b/src/chess.h
@@ -653,9 +653,8 @@ typedef struct _POSITION
     // convention). Maintained incrementally in move.c at every site
     // that already updates cNonPawns[]/uNonPawnCount[] (see
     // board_representation/MIGRATION.md), not rebuilt -- O(1) per
-    // move. Pawns use pHash->bbPawnLocations[2] (pawn-hash-keyed,
-    // already established) instead; king is a single square
-    // (cNonPawns[color][0]), a bitboard adds nothing.
+    // move. Pawns use bbPawns[2] below instead; king is a single
+    // square (cNonPawns[color][0]), a bitboard adds nothing.
     BITBOARD bbPieces[2][8];
 
     // Per-color pawn location bitboard -- same incremental-maintenance
@@ -663,10 +662,13 @@ typedef struct _POSITION
     // deliberately excludes). Exists so _BuildOccupiedBB (see.c) can
     // build full-board occupancy via two ORs instead of looping
     // cPawns[2][8] (up to 16 iterations) on every call -- see
-    // board_representation/MIGRATION.md section 3. Distinct from
-    // pHash->bbPawnLocations[2] (pawn-hash-keyed, tied to pawn-eval
-    // caching); this one is plain POSITION state, reachable without a
-    // SEARCHER_THREAD_CONTEXT.
+    // board_representation/MIGRATION.md section 3. Also the single
+    // source of truth for pawn locations used by pawn eval
+    // (board_representation/EVAL.md section 0c) -- PAWN_HASH_ENTRY
+    // used to carry its own redundant bbPawnLocations[2], rebuilt
+    // bit-by-bit on every pawn-hash miss even though this field
+    // already had the answer; removed 2026-09-05, eval.c now reads
+    // this field directly instead.
     BITBOARD bbPawns[2];
 
     ULONG uWhiteSqBishopCount[2];          // num bishops on white squares
@@ -896,6 +898,40 @@ typedef struct _COUNTERS
         UINT64 u64LazyEvals;
         UINT64 u64FullEvals;
         UINT64 u64CyclesInEval;
+
+        //
+        // Per-eval-term cycle breakdown (EVAL_TIME only) -- board_
+        // representation/EVAL.md section 0b's "profile before
+        // rewriting" step. Sum of these plus "everything else"
+        // (u64CyclesInEval minus this sum, computed at print time)
+        // equals u64CyclesInEval; kept as separate counters rather
+        // than an array so each term's call sites in eval.c can name
+        // its own accumulator directly.
+        //
+        UINT64 u64CyclesEvalPawns;
+        UINT64 u64CyclesEvalKnight;
+        UINT64 u64CyclesEvalBishop;
+        UINT64 u64CyclesEvalRook;
+        UINT64 u64CyclesEvalQueen;
+        UINT64 u64CyclesEvalKing;
+
+        //
+        // u64CyclesEvalPreLazy covers the "always paid, even on a
+        // lazy exit" segment -- material setup through the lazy-
+        // margin decision (passer races, bad trades, bishop pairs,
+        // EstimatePositionalScore/CountKingSafetyDefects) -- and
+        // *includes* u64CyclesEvalPawns as a subset (pawns is nested
+        // inside this segment, not sequential with it); print sites
+        // must subtract pawns back out rather than summing both.
+        // u64CyclesEvalPostLazyMisc covers what's left of the "only
+        // paid on a full eval" segment once the named piece-type
+        // buckets above are excluded: _EvalPassers, _EvalLookForDanger,
+        // _EvalTrappedPieces, the B-over-N/reduced-material endgame
+        // scalers.
+        //
+        UINT64 u64CyclesEvalPreLazy;
+        UINT64 u64CyclesEvalPostLazyMisc;
+        UINT64 u64CyclesEvalAttackTablePop;
     }
     tree;
 
@@ -1035,7 +1071,6 @@ PLY_INFO;
 typedef struct _PAWN_HASH_ENTRY
 {
     UINT64 u64Key;
-    BITBOARD bbPawnLocations[2];
     BITBOARD bbPasserLocations[2];
     BITBOARD bbStationaryPawns[2];
     SHORT iScore[2];
@@ -3042,6 +3077,29 @@ TestEvalWithSymmetry(void);
 #endif
 
 //
+// Per-eval-term cycle accounting, EVAL_TIME only -- see
+// board_representation/EVAL.md section 0b. CTX must be the
+// SEARCHER_THREAD_CONTEXT* in scope at the call site; COUNTER names
+// one of the ctx->sCounters.tree.u64CyclesEval* fields. Wraps CALL
+// (an expression, e.g. a function call whose return value is
+// discarded or assigned outside the macro) with a start/stop
+// timestamp pair, accumulating elapsed cycles into COUNTER. A no-op
+// wrapper (CALL alone) outside EVAL_TIME builds so call sites don't
+// need their own #ifdef.
+//
+#ifdef EVAL_TIME
+#define TIMED_EVAL_CALL(CTX, COUNTER, CALL)                    \
+    do {                                                       \
+        UINT64 u64EvalTimerStart = SystemReadTimeStampCounter(); \
+        CALL;                                                  \
+        (CTX)->sCounters.tree.COUNTER +=                       \
+            (SystemReadTimeStampCounter() - u64EvalTimerStart); \
+    } while (0)
+#else
+#define TIMED_EVAL_CALL(CTX, COUNTER, CALL) CALL
+#endif
+
+//
 // bitboard.c
 //
 void