instrument: TT lookup/hit counters (hot-path) + env-gated summary

[wopdevries]

Minimal, low-risk instrumentation to measure the transposition-table hit rate on the search hot path.

Changes:

• Add tt_lookup_count and tt_hit_count counters to ThreadData
• Increment counters in apply_ab_tt_lookup (the canonical AB hot-path TT probe)
• Print env-gated summary at SOLVER_DONE when DDS_PRINT_TT_STATS=1

No behavioral changes — counters are cheap increments, output is gated.

Measurement results on hands/largest.txt (21 hardest hands, single-threaded):
Updated findings after per-solve reset fix:

• Per-board hit rate: 57-75% (varies by hand difficulty)
• Per-board overwrite rate: 2-24% (mostly 2-9%)
• Low overwrite rate confirms: replacement churn is NOT the main cause of misses
• Hard hands have lower hit rates due to genuinely unique positions, not TT churn
• Algorithmic improvements (pruning, move ordering) are the next optimization target

How to test:

bazelisk build //library/tests:dtest
DDS_PRINT_TT_STATS=1 ./bazel-bin/library/tests/dtest -f hands/largest.txt -s solve -n 1

[Copilot]

🟡 Changes recommended

It introduces compilation fragility (missing direct standard includes) and a real stats correctness issue (new PageStats fields aren’t reset on TT teardown).

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds lightweight instrumentation to measure transposition-table (TT) effectiveness on the alpha-beta search hot path, and reports an environment-gated summary at solver completion to support TT sizing/tuning work.

Changes:

• Added per-ThreadData TT probe counters (tt_lookup_count, tt_hit_count) and incremented them in apply_ab_tt_lookup.
• Added env-gated (DDS_PRINT_TT_STATS) stderr summary printing on solver completion paths.
• Extended TransTableL::PageStats with insertion/overwrite counters and incremented them on TT entry creation/overwrite.

File summaries

File	Description
library/src/trans_table/trans_table_l.hpp	Extends PageStats with add/overwrite counters.
library/src/trans_table/trans_table_l.cpp	Initializes new PageStats fields; increments add/overwrite counters in create_or_update.
library/src/system/thread_data.hpp	Adds per-thread TT lookup/hit counters to ThreadData.
library/src/solver_if.cpp	Resets counters per solve and prints env-gated TT hit-rate summary at completion.
library/src/ab_search.cpp	Increments TT lookup/hit counters in the canonical TT probe path.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

There are a few concrete mismatches and consistency issues (notably the env var gating contract and documentation/formatting inconsistencies) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

library/src/trans_table/trans_table_l.hpp:477

• This inline override uses same-line braces; please reformat it to match the Allman function brace style used throughout the codebase.

    auto get_op_stats(int& adds, int& overwrites, int& harvests) const -> void override {
      adds = page_stats_.num_adds_;
      overwrites = page_stats_.num_overwrites_;
      harvests = page_stats_.num_harvests_;
    }

• Files reviewed: 8/8 changed files
• Comments generated: 6
• Review effort level: Lite