ChessAI.py

"""
Search & Evaluation
"""
"""
Handling the AI moves.
Scores - Chess.com
Depth=4, Time/move=30: Won vs 1000 rated bot
Depth=4, Time/move=30: Won vs 1300 rated bot
Depth=4, Time/move=30: Won vs 1400 rated bot - 38 moves
Depth=4, Time/move=30: Lost vs 1500 rated bot - 33 moves
-- Added more evaluation enhancements (13 in total) --
Depth=4, Time/move=30: Won vs 1500 rated bot - 60 moves
-- Added more evaluation enhancements (18 in total), added new class to make things more efficient --
Depth=4, Time/move=30: Draw (Stalemate) vs 1700 rated bot - 100 moves
-- Added more evaluation enhancements (21 in total), big improvements to all the files in efficiency and functionality --
Depth=10, Time/move=30: Draw (Insufficient Material) vs 1800 rated bot - 88 moves (Threw winning game) (Reached depth 5-6 on average, max 7)
-- Added more evaluation enhancements (23 in total), improved values of the previous functions --
Depth=10, Time/move=30: Lost vs 1900 rated bot - <50 moves (Played terrible due to drop in depth and got checkmated) (Reached depth 4-5 on average, max 6)
-- Rework in calculation going from decimals to integers (cp score) --
Depth=10, Time/move=30: Won vs 1900 rated bot - 47 moves (Almost a domination) (Depth: 6.57 on average, max 8, min 6)
Depth=10, Time/move=30: Won vs 2200 rated bot - 57 moves (Comfortable win) (Depth: 5.5 on average, max 7, min 4)
Depth=10, Time/move=30: Lost vs 2400 rated bot - 28 moves (Got destroyed) (Depth: 5.77 on average, max 7, min 4)
-- Added a Opening Book --
Depth=10, Time/move=30: Won vs 2400 rated bot - 69 moves (Well played) (Depth: 6.16 on average, max 8, min 5)
Depth=10, Time/move=30: Lost vs 2700 rated bot - 63 moves (Some clear mistakes) (Depth: 7.2 on average, max 9, min 5)
Depth=30, Time/move=30: Lost vs 2600 rated bot - 81 moves (Threw a completely Drawn endgame) (Depth: 8.0 on average, max 14, min 2)
Depth=30, Time/move=30: Draw vs 2600 rated bot - 22 moves () (Depth:  on average, max , min )

"""
import random
import time
import chess
from opening_book import BookManager
from collections import defaultdict, namedtuple

piece_score = {"K": 0.0, "Q": 9.75, "R": 5.0, "B": 3.25, "N": 3.25, "p": 1.0}

# Knights: center good, but modest. Max ≈ +0.40
knight_scores = [
    [ 0.00, 0.00, 0.05, 0.10, 0.10, 0.05, 0.00,  0.00],
    [ 0.00, 0.10, 0.20, 0.25, 0.25, 0.20, 0.10,  0.00],
    [ 0.05, 0.20, 0.30, 0.35, 0.35, 0.30, 0.20,  0.05],
    [ 0.10, 0.25, 0.35, 0.43, 0.43, 0.35, 0.25,  0.10],
    [ 0.10, 0.25, 0.35, 0.43, 0.43, 0.35, 0.25,  0.10],
    [ 0.05, 0.20, 0.30, 0.35, 0.35, 0.30, 0.20,  0.05],
    [ 0.00, 0.10, 0.20, 0.25, 0.25, 0.20, 0.10,  0.00],
    [ 0.00, 0.00, 0.05, 0.10, 0.10, 0.05, 0.00,  0.00],
]

# Bishops: prefer long diagonals/center. Max ≈ +0.30
bishop_scores = [
    [0.00, 0.05, 0.10, 0.15, 0.15, 0.10, 0.05, 0.00],
    [0.05, 0.10, 0.15, 0.20, 0.20, 0.15, 0.10, 0.05],
    [0.05, 0.15, 0.20, 0.25, 0.25, 0.20, 0.15, 0.05],
    [0.10, 0.20, 0.25, 0.30, 0.30, 0.25, 0.20, 0.10],
    [0.10, 0.20, 0.25, 0.30, 0.30, 0.25, 0.20, 0.10],
    [0.05, 0.15, 0.20, 0.25, 0.25, 0.20, 0.15, 0.05],
    [0.05, 0.10, 0.15, 0.20, 0.20, 0.15, 0.10, 0.05],
    [0.00, 0.05, 0.10, 0.15, 0.15, 0.10, 0.05, 0.00],
]

# Rooks: very light PST (real bonuses come from open/semi-open/7th-rank features)
rook_scores = [
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
]

# Queens: keep flat; queen play is handled by other features.
queen_scores = [
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],
]

# Pawns: reward healthy advance (small), instead of anchoring on rank 2.
pawn_scores = [
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],  # 8
    [0.35, 0.35, 0.35, 0.35, 0.35, 0.35, 0.35, 0.35],  # 7  
    [0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 0.25, 0.25],  # 6  
    [0.18, 0.18, 0.18, 0.18, 0.18, 0.18, 0.18, 0.18],  # 5  
    [0.12, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12, 0.12],  # 4 
    [0.08, 0.08, 0.08, 0.08, 0.08, 0.08, 0.08, 0.08],  # 3  
    [0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04, 0.04],  # 2  
    [0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00, 0.00],  # 1
]

piece_position_scores = {"wN": knight_scores,
                         "bN": knight_scores[::-1],
                         "wB": bishop_scores,
                         "bB": bishop_scores[::-1],
                         "wQ": queen_scores,
                         "bQ": queen_scores[::-1],
                         "wR": rook_scores,
                         "bR": rook_scores[::-1],
                         "wp": pawn_scores,
                         "bp": pawn_scores[::-1]}

BISHOP_PAIR  = 50
ROOK_OPEN    = 20

# a zero table for kings
king_zero = [[0.0]*8 for _ in range(8)]
piece_position_scores['wK'] = king_zero
piece_position_scores['bK'] = [row[:] for row in king_zero[::-1]]

# flattened PSTs for O(1) indexed access (values unchanged)
def _flatten2d(mat):
    return tuple(v for row in mat for v in row)

PST_FLAT = {k: _flatten2d(v) for k, v in piece_position_scores.items()}

# --- Unit conversion helpers (pawns → centipawns) ---
PAWN = 100

def to_cp(pawn_value: float) -> int:
    """Convert white-positive pawn units (float) to centipawns (int)."""
    return int(round(pawn_value * PAWN))

def pc_cp(pt: str) -> int:
    """Piece value in cp from piece_score dict (kept in pawns by user request)."""
    return int(round(piece_score[pt] * PAWN))

# Derived absolute piece magnitudes in cp (for ordering like MVV-LVA)
PIECE_CP = {k: int(round(v * PAWN)) for k, v in piece_score.items()}

def sq_index(row, col):
    """ Map (r,c) -> 0..63."""
    return (row << 3) | col

def mirror_vert(sq):
    """Flip square vertically (for quick black/white mirroring if needed)."""
    return sq ^ 56

# Transposition Table with Zobrist Hashing: to avoid re-searching identical positions - shaves 30-50% off the node count.
# Zobrist hashing (deterministic RNG)
PIECES = ['wp','wN','wB','wR','wQ','wK','bp','bN','bB','bR','bQ','bK']

# Use a dedicated RNG so Zobrist is stable across runs and doesn't perturb global random.
_zrnd = random.Random(0x9E3779B97F4A7C15)  # arbitrary fixed seed

ZOBRIST_PIECE   = {p: [_zrnd.getrandbits(64) for _ in range(64)] for p in PIECES}
ZOBRIST_SIDE    = _zrnd.getrandbits(64)
ZOBRIST_CASTLING = [_zrnd.getrandbits(64) for _ in range(4)]  # Four castling‐rights bits: wK, wQ, bK, bQ
ZOBRIST_ENPASSANT = [_zrnd.getrandbits(64) for _ in range(8)] # Eight en‐passant files a–h

# --- Transposition Table (fixed-size, dict-compatible wrapper) ---
EXACT, LOWERBOUND, UPPERBOUND = 0, 1, 2
TTEntry = namedtuple('TTEntry', 'depth flag value best_move')

TT_SIZE = 1 << 20  # ~1M buckets

class TranspositionTable:
    __slots__ = ('table', 'mask')

    def __init__(self, size=TT_SIZE):
        assert size & (size - 1) == 0, "TT size must be a power of two"
        self.table = [None] * size
        self.mask = size - 1

    def get(self, zkey, default=None):
        slot = self.table[zkey & self.mask]
        if slot is None:
            return default
        key, depth, flag, value, best_move = slot
        return TTEntry(depth, flag, value, best_move) if key == zkey else default

    def __getitem__(self, zkey):
        e = self.get(zkey)
        if e is None:
            raise KeyError(zkey)
        return e

    def __setitem__(self, zkey, entry):
        if not isinstance(entry, TTEntry):
            entry = TTEntry(*entry)
        idx = zkey & self.mask
        cur = self.table[idx]
        if cur is None:
            self.table[idx] = (zkey, entry.depth, entry.flag, entry.value, entry.best_move)
            return
        _, d, f, _, _ = cur
        pri = lambda flag: 2 if flag == EXACT else (1 if flag == LOWERBOUND else 0)
        if (entry.depth > d) or (entry.depth == d and pri(entry.flag) > pri(f)):
            self.table[idx] = (zkey, entry.depth, entry.flag, entry.value, entry.best_move)

    def clear(self):
        self.table[:] = [None] * len(self.table)

# Instantiate TT with same variable name used elsewhere
TT = TranspositionTable()

# History table (array-backed, dict-compatible)
MAX_MOVES = 1 << 16  # adjust if your moveIDs exceed this

class HistoryTable:
    __slots__ = ('arr', 'overflow', 'size')

    def __init__(self, size=MAX_MOVES):
        self.size = size
        self.arr = [0] * size
        self.overflow = defaultdict(int)  # fallback for non-int/large IDs

    def __getitem__(self, k):
        if isinstance(k, int) and 0 <= k < self.size:
            return self.arr[k]
        return self.overflow[k]

    def __setitem__(self, k, v):
        if isinstance(k, int) and 0 <= k < self.size:
            self.arr[k] = v
        else:
            self.overflow[k] = v

    def get(self, k, default=0):
        if isinstance(k, int) and 0 <= k < self.size:
            return self.arr[k]
        return self.overflow.get(k, default)

    def add(self, k, delta):
        if isinstance(k, int) and 0 <= k < self.size:
            self.arr[k] += delta
        else:
            self.overflow[k] += delta

    def clear(self):
        self.arr[:] = [0] * self.size
        self.overflow.clear()

history_scores = HistoryTable()

# Search timing / globals
CHECKMATE = 30000 # score for checkmate
STALEMATE = 0 # score for stalemate. Better than losing, worse than winning. So, White checkmate = +30000 and Black checkmate = -30000
DEPTH = 30 # depth of the search tree aka how many moves ahead the AI will look
TIME_PER_MOVE = 30.0      # seconds per move

# --- Light pruning knobs (centipawns) ---
RAZOR_MARGIN         = 165     # only at depth==1 and not in check
STATIC_BETA_MARGIN   = 110     # depth<=3: prune when static_cp - d*margin >= beta
FUTILITY_BASE_MARGIN = 100     # depth<=2: skip very-late quiets if static far below alpha

# --- Null-move pruning knobs ---
NULLMOVE_MIN_DEPTH = 3          # only try when depth >= 3
NULLMOVE_R_BASE    = 2          # reduction R = 2 or 3 (adaptive)
NULLMOVE_R_BONUS_D = 6          # add +1 reduction if depth >= this

# --- Internal Iterative Deepening (IID) ---
IID_MIN_DEPTH = 4      # only try when depth >= 4
IID_REDUCE    = 2      # search at depth - 2 to find a TT move

# tuneables
QCHECKS_ENABLE = True
QCHECKS_MAX_PER_NODE = 1      # max quiet checks to try per node (often +30–60 Elo for tactical stability)
QCHECKS_SKIP_QUEEN = True     # queen checks are often noisy/expensive

CONTEMPT = 0.10  # Tiny root-only draw bias (pawns). 0.10 is plenty.
CONTEMPT_CP = to_cp(CONTEMPT)

DEBUG_SEARCH = False

nodes_searched = 0 # global counter for nodes searched
now = time.perf_counter  # high-resolution, monotonic timer
next_move = None

# Opening book config (single book)
# make sure at the top of the file you have:  from opening_book import BookManager
BOOK_ENABLED       = True
BOOK_MAIN_PATH     = "mainbook.bin"
BOOK_RANDOM        = False     # set True if you want variety
BOOK_TEMPERATURE   = 0.75      # used only when BOOK_RANDOM=True
BOOK_TOP_K         = None         # 0 = no restriction; else sample from top-k moves
DEBUG_BOOK        = False           # set True only when debugging book integration
FILE_LETTERS = "abcdefgh"

# Single global manager (safe for your AI worker thread)
try:
    BOOK = BookManager(BOOK_MAIN_PATH)
except Exception as e:
    print("[BOOK] load failed:", e)
    BOOK = None

# --- “out of book” tracker for current game ---
BOOK_PROBE_ACTIVE = True       # when False, skip book probes entirely
_BOOK_ZERO_HITS   = 0          # count of consecutive zero-entry probes this game

def _maybe_reset_book_probe(gs):
    """Reset the book probe state at the start of a game (empty move log)."""
    global BOOK_PROBE_ACTIVE, _BOOK_ZERO_HITS
    if not gs.move_log:        # new game or custom FEN with no moves played
        BOOK_PROBE_ACTIVE = True
        _BOOK_ZERO_HITS   = 0

class SearchTimeout(Exception):
    """Raised when the allotted time per move is exceeded."""
    pass

class _PrunedQuiet(Exception):
    """Internal control-flow to skip a pruned quiet move inside the move loop."""
    __slots__ = ()

# Iteration deadline helpers (set by the search driver)
_deadline = None
def set_move_time(seconds: float):
    global _deadline
    _deadline = now() + seconds

def check_time():
    if _deadline is not None and now() >= _deadline:
        raise SearchTimeout

# --- Mate score (de)normalisation for TT ---
MATE_SCORE = CHECKMATE
MATE_MIN = MATE_SCORE - 1000  # band near mate

def score_to_tt(score: int, ply: int) -> int:
    """Normalise mate scores with ply so they remain comparable across depths."""
    if score >= MATE_MIN:
        return score + ply
    if score <= -MATE_MIN:
        return score - ply
    return score

def score_from_tt(score: int, ply: int) -> int:
    """Restore mate scores from TT normalised values."""
    if score >= MATE_MIN:
        return score - ply
    if score <= -MATE_MIN:
        return score + ply
    return score

# --- MVV-LVA capture ordering (uses your material scaled to cp) ---
PIECE_TO_IDX = {"p":0, "N":1, "B":2, "R":3, "Q":4, "K":5}
MVV_LVA = [[0]*6 for _ in range(6)]
for atk, ai in PIECE_TO_IDX.items():
    for vic, vi in PIECE_TO_IDX.items():
        victim_cp = PIECE_CP[vic]
        attacker_cp = PIECE_CP[atk]
        MVV_LVA[ai][vi] = victim_cp * 16 - attacker_cp  # larger is better

def capture_score(m) -> int:
    """Positive ordering score for captures (bigger is better). Safe if no capture."""
    if m.piece_captured == "--":
        return 0
    return MVV_LVA[PIECE_TO_IDX[m.piece_moved[1]]][PIECE_TO_IDX[m.piece_captured[1]]]

# --- Killers and counter-moves ---
MAX_PLY = 128
killers = [[0, 0] for _ in range(MAX_PLY)]       # moveIDs per ply
counter_move = defaultdict(int)                  # key: prev_moveID -> moveID

def score_move(m, tt_move_id: int, ply: int, prev_move_id: int | None = None) -> int:
    """
    Unified move ordering score:
    TT > good captures (MVV-LVA, with SEE-lite penalty for losing trades)
       > castles > killers > promotions > counter-move > history.
    """
    # TT move always first
    if m.moveID == tt_move_id:
        return 1_000_000_000

    score = 0

    # Captures (MVV-LVA already scaled via capture_score)
    if getattr(m, "is_capture", False):
        score += 1_000_000 + capture_score(m)

        # SEE-lite: penalize obviously losing captures (by static piece values),
        # unless it's a promotion (which can compensate tactically).
        if m.piece_captured != "--":
            victim_cp   = PIECE_CP[m.piece_captured[1]]
            attacker_cp = PIECE_CP[m.piece_moved[1]]
            if (victim_cp - attacker_cp) < 0 and not getattr(m, "is_pawn_promotion", False):
                score -= 120_000

    # Castling: search it early so the engine actually castles
    if getattr(m, 'is_castle_move', False) or getattr(m, 'isCastleMove', False):
        score += 850_000

    # Killer moves
    k0, k1 = killers[ply]
    if m.moveID == k0:
        score += 900_000
    elif m.moveID == k1:
        score += 800_000

    # Promotions (quiet promotions get a bump too)
    if getattr(m, "is_pawn_promotion", False):
        promo = getattr(m, "promotion_choice", "Q")
        promo_bonus = {"Q": 300_000, "R": 200_000, "N": 180_000, "B": 150_000}.get(promo, 250_000)
        score += promo_bonus

    # Counter-move heuristic (boost reply that refuted prev opp move before)
    if prev_move_id is not None:
        cm = counter_move.get(prev_move_id, 0)
        if cm and m.moveID == cm:
            score += 700_000

    # History last
    score += history_scores.get(m.moveID, 0)

    return score

# EvalContext cache (bounded)
_eval_ctx_cache = {} # Cache EvalContext objects to avoid rebuilding them on identical positions
EVAL_CTX_CACHE_MAX = 100_000  # simple cap; tune as needed
EVAL_VERSION = 7
EVAL_USE_FAST_FROM_DEPTH = 3  # use fast features when depth is deep
EVAL_CACHE = {}  # (zobrist, fast_bool) -> eval score

PROFILE = {"ctx_builds_fast":0, "ctx_builds_full":0, "score_calls_fast":0, "score_calls_full":0}

def _phase_hint(gs):
    """Cheap material phase in [0..1]; identical to ChessEngine._phase."""
    bb = gs.bitboards
    cnt = (bb['wN'].bit_count() + bb['bN'].bit_count()
           + bb['wB'].bit_count() + bb['bB'].bit_count()
           + 2 * (bb['wR'].bit_count() + bb['bR'].bit_count())
           + 4 * (bb['wQ'].bit_count() + bb['bQ'].bit_count()))
    return min(24, cnt) / 24.0

def _use_fast_eval(gs, depth, is_pv, is_root=False):
    """
    Policy:
      - FULL at root, PV nodes, shallow leaves (depth<=2), and EG-ish.
      - FAST otherwise.
    """
    # FULL at root and PV
    if is_root or is_pv:
        return False
    # FULL for shallow leaves
    if depth <= 2:
        return False
    # FULL for EG-ish if you want (optional)
    try:
        if getattr(gs, 'small_endgame', False):
            return False
    except Exception:
        pass
    # otherwise FAST
    return True

def _fmt_white_pawns(score_cp: int, white_to_move: bool) -> str:
    """Format centipawn score from White's perspective as ±X.XX pawns."""
    white_cp = score_cp if white_to_move else -score_cp
    return f"{white_cp/100:.2f}" if white_cp >= 0 else f"-{abs(white_cp)/100:.2f}"

def evaluate_cp(gs) -> int:
    """
    White-positive evaluation in centipawns.
    Uses GameState.current_eval (maintained incrementally in pawns) + fast features (cp).
    Negate at the call site if you use negamax with side-to-move.
    """
    # base material + PST in pawns → cp
    score = to_cp(gs.current_eval)
    return score

def _has_non_pawn_material(gs, white: bool) -> bool: # Some zugzwangy endings hate null moves; skip NMP (Null-Move Pruning) if side has only king+pawns.
    bb = gs.bitboards
    if white:
        return bool(bb['wQ'] | bb['wR'] | bb['wB'] | bb['wN'])
    else:
        return bool(bb['bQ'] | bb['bR'] | bb['bB'] | bb['bN'])

def _king_danger_flag(gs):
    # Immediate check is always "danger"
    if gs.inCheck():
        return True

    phase = _phase(gs)

    # Ring-based danger is a middlegame concept; skip it in late EG
    if phase <= 0.35:
        return False

    def ring_hits(kr, kc, by_white, opp_kr, opp_kc):
        h = 0
        for rr in (kr-1, kr, kr+1):
            if 0 <= rr < 8:
                for cc in (kc-1, kc, kc+1):
                    if 0 <= cc < 8:
                        if rr == kr and cc == kc:
                            continue  # skip the king’s own square
                        # Don't count the enemy king’s inherent adjacency attacks
                        if abs(rr - opp_kr) <= 1 and abs(cc - opp_kc) <= 1:
                            continue
                        if gs.is_square_attacked_bb(rr*8 + cc, by_white=by_white):
                            h += 1
        return h


    wkr, wkc = gs.white_king_location
    bkr, bkc = gs.black_king_location
    w_hits = ring_hits(wkr, wkc, by_white=False, opp_kr=bkr, opp_kc=bkc)
    b_hits = ring_hits(bkr, bkc, by_white=True,  opp_kr=wkr, opp_kc=wkc)

    # Slightly stricter in MG
    if w_hits >= 5 or b_hits >= 5:
        return True

    # e-pawn shield only matters early
    if phase > 0.6:
        board = gs.board
        if board[6][4] != 'wp' and board[7][4] == 'wK':  # white king still e1, e-pawn moved
            return True
        if board[1][4] != 'bp' and board[0][4] == 'bK':  # black king still e8, e-pawn moved
            return True

    return False

def _gives_check(gs, m):
    """True if m gives check (without altering state long-term)."""
    gs.makeMove(m)
    try:
        return gs.inCheck()  # after move, opponent to move; if they're in check, our move gave check
    finally:
        gs.undoMove()

def get_eval_context(gs, is_white, fast=False):
    """
    Cached EvalContext builder. If fast=True, builds a light context (skips heavy maps).
    """
    key = (EVAL_VERSION, id(gs), gs.zobrist_key, is_white, bool(fast))
    ctx = _eval_ctx_cache.get(key)
    if ctx is None:
        ctx = EvalContext(gs, is_white, light=fast)
        if 'PROFILE' in globals():
            if fast: PROFILE["ctx_builds_fast"] += 1
            else:    PROFILE["ctx_builds_full"] += 1
        _eval_ctx_cache[key] = ctx
        if len(_eval_ctx_cache) > EVAL_CTX_CACHE_MAX:
            _eval_ctx_cache.clear()
            _eval_ctx_cache[key] = ctx
    return ctx

def _mate_score(ply: int) -> int:
    """
    Return a mate score that prefers faster mates.
    For the side to move, mate in N plies should be +(CHECKMATE - ply).
    """
    return CHECKMATE - ply

def _is_mate_after(gs, m) -> bool:
    """True if playing m delivers immediate checkmate."""
    gs.makeMove(m)
    try:
        return (not gs.getValidMoves()) and gs.inCheck()
    finally:
        gs.undoMove()

def _score_root_move(gs, m):
    """
    Heuristic root-only ordering (centipawns).
    Prioritizes checks, safe captures, promotions, castling, and early development.
    Penalizes obviously losing captures and premature queen sorties.
    """
    # Instant mate? Always first.
    if _is_mate_after(gs, m):
        return 1_000_000

    # --- small helpers ---
    def _dest_sq(move):
        return move.end_row * 8 + move.end_col

    def _mover_is_white_after_make():
        # after makeMove(), side-to-move flips, so mover was the previous side
        return not gs.white_to_move

    # rough full-move number (white starts at FM1; every black move completes one full move)
    fullmove = 1 + sum(1 for x in gs.move_log if x.piece_moved[0] == 'b')
    phase = _phase(gs)

    sc = 0

    # --- base tactical terms ---
    # Captures: MVV-LVA-ish bump
    if m.piece_captured != "--":
        sc += 1000 + (PIECE_CP[m.piece_captured[1]] - PIECE_CP[m.piece_moved[1]])

    # Promotions (to anything): big bump
    if getattr(m, "is_pawn_promotion", False):
        sc += 800

    # Castling: help engine do it sooner at root
    if m.piece_moved[1] == 'K' and getattr(m, "is_castle_move", False):
        sc += 400

    # --- quick make/undo to evaluate check and destination safety for SEE-lite ---
    gs.makeMove(m)
    try:
        gives_check = gs.inCheck()
        if gives_check:
            sc += 2000

        mover_is_white = _mover_is_white_after_make()
        dest_sq = _dest_sq(m)

        # Is our landing square attacked/defended after the move?
        attacked_by_opp = gs.is_square_attacked_bb(dest_sq, by_white=(not mover_is_white))
        defended_by_us  = gs.is_square_attacked_bb(dest_sq, by_white=mover_is_white)

        # Lightweight SEE gate for captures: if it's a clearly losing capture, push it down.
        if m.piece_captured != "--":
            # material swing (captured - attacker) in cp
            mat_gain = PIECE_CP[m.piece_captured[1]] - PIECE_CP[m.piece_moved[1]]
            # losing capture: square attacked and not defended, or negative material swing
            if (attacked_by_opp and not defended_by_us) or (mat_gain < 0):
                sc -= 1500  # big enough to outrank the generic capture bonus

        # Penalize “hanging” quiet moves (move lands on attacked square with no defense)
        if m.piece_captured == "--" and attacked_by_opp and not defended_by_us:
            sc -= 250

        # Endgame micro-preferences for rook activity (ordering-only, cheap):
        if phase < 0.45 and m.piece_moved[1] == 'R':
            # prefer rook checks a bit in EG (on top of the generic check bonus)
            if gives_check:
                sc += 150
    finally:
        gs.undoMove()

    # --- opening/early-game nudges (ordering only; eval stays authoritative) ---
    # Early development: moving a minor off the back rank in the first ~8 full moves
    if fullmove <= 8 and m.piece_moved[1] in ('N', 'B'):
        home_row = 7 if gs.white_to_move else 0
        if m.start_row == home_row:
            sc += 120

    # Premature queen development without check/capture in first ~8 full moves
    if fullmove <= 8 and m.piece_moved[1] == 'Q' and m.piece_captured == "--":
        # only penalize if it didn't already get a "gives_check" boost
        # (gives_check is defined above inside the make/undo block and is in scope)
        try:
            if not gives_check:
                sc -= 150
        except NameError:
            # safety: if something changes above, keep original behavior
            sc -= 150

    # Early f/g-pawn push before castling (ordering nudge; eval has the real penalty)
    if fullmove <= 10 and m.piece_moved[1] == 'p' and m.piece_captured == "--":
        # If king still on e1/e8 and not castled, nudge down f/g pawn pushes
        if gs.white_to_move:
            kr, kc = gs.white_king_location
            castled = (kr, kc) in ((7, 6), (7, 2))
            if not castled and (m.start_col in (5, 6)):  # f or g file
                sc -= 80
        else:
            kr, kc = gs.black_king_location
            castled = (kr, kc) in ((0, 6), (0, 2))
            if not castled and (m.start_col in (5, 6)):
                sc -= 80

    # Endgame: small nudge for rook to 7th/2nd (strictly ordering, phase-gated)
    if phase < 0.45 and m.piece_moved[1] == 'R':
        if (gs.white_to_move and m.end_row == 1) or ((not gs.white_to_move) and m.end_row == 6):
            sc += 140

    return sc

def find_forced_mate_k(gs, k, soft_time_ms=30):
    """
    Try to prove a forced mate for the side-to-move within k plies
    using a checks-only DFS (defender: evasions only).
    Returns a PV as a list of Move objects [m0, m1, m2, ...] if found,
    else None. Budgeted by soft_time_ms.
    """
    start = time.perf_counter()
    def time_up():
        return (time.perf_counter() - start) * 1000.0 > soft_time_ms

    # Quick terminal
    root_moves = gs.getValidMoves()
    if not root_moves:
        return None  # mate/stalemate is handled by main search

    # Generate only checking moves at root
    check_moves = [m for m in root_moves if _gives_check(gs, m)]
    if not check_moves:
        return None

    # Prefer “heavier” checks first (MVV-LVA bias + promotions), in cp
    def _root_check_key(m):
        cap = PIECE_CP[m.piece_captured[1]] if m.piece_captured != "--" else 0
        att = PIECE_CP[m.piece_moved[1]]
        promo = 50 if getattr(m, "is_pawn_promotion", False) else 0
        return (cap - att) + promo
    check_moves.sort(key=_root_check_key, reverse=True)

    # Inner recursive proof: after our checking move, defender to move and in check.
    def prove_after_our_check(depth, ply_acc):
        """
        Defender is in check. We must show: for EVERY legal evasion, there exists
        a checking reply that continues the proof to mate within 'depth' plies.
        """
        if time_up():
            return None
        evasions = gs.getValidMoves()          # when in check, these are evasions
        if not evasions:
            # side to move is checkmated
            return []  # empty tail; caller will prepend the previous move

        if depth <= 0:
            return None  # ran out of proving depth

        # For each evasion, we must find some checking reply that keeps the proof alive
        for ev in evasions:
            gs.makeMove(ev)
            try:
                # Our turn: must reply with a checking move
                replies = [m for m in gs.getValidMoves() if _gives_check(gs, m)]
                if not replies:
                    return None  # this evasion breaks the force

                ok = False
                for rep in replies:
                    gs.makeMove(rep)
                    try:
                        # If opponent has no move and is in check → mate
                        if not gs.getValidMoves() and gs.inCheck():
                            ok = True
                            break
                        tail = prove_after_our_check(depth - 1, ply_acc + 2)
                        if tail is not None:
                            ok = True
                            break
                    finally:
                        gs.undoMove()
                if not ok:
                    return None
            finally:
                gs.undoMove()

        # All evasions are handled by at least one checking reply → success
        return []

    # Try each root checking move
    for m0 in check_moves:
        if time_up():
            break
        gs.makeMove(m0)
        try:
            # Immediate mate?
            if not gs.getValidMoves() and gs.inCheck():
                return [m0]
            tail = prove_after_our_check(k - 1, 1)
            if tail is not None:
                return [m0]  # You can extend to reconstruct full PV if desired
        finally:
            gs.undoMove()

    return None

def findBestMove(game_state, valid_moves, return_queue):
    """
    Iterative deepening with aspiration windows (phase-aware), strong root ordering,
    quick checks-only mate probe, and a deterministic safe fallback on timeout.
    Adds an opening-book probe before search (instant move if hit).
    Hard cap: never spend more than TIME_PER_MOVE on a move.
    """
    global next_move, nodes_searched
    # also touch book probe guards here
    global _BOOK_ZERO_HITS, BOOK_PROBE_ACTIVE

    turn_multiplier = 1 if game_state.white_to_move else -1

    # Set a single global deadline for this move (enforced via check_time())
    set_move_time(TIME_PER_MOVE)
    start_time = now()  # only for logging/NPS

    # Root move list (once)
    original_root_moves = valid_moves if valid_moves is not None else game_state.getValidMoves()
    if not original_root_moves:
        return_queue.put(None)
        return
    
    # Reset the “out of book” guard at game start
    _maybe_reset_book_probe(game_state)

    # --- Opening book probe (before any search) ---
    try:
        if BOOK_ENABLED and BOOK_PROBE_ACTIVE and (BOOK is not None) and BOOK.available():
            pyb = _gs_to_pyboard(game_state)

            # Probe entries exactly once
            entries = BOOK.entries(pyb)
            n = len(entries)

            # Debug printing rules:
            # - If entries > 0, print (if DEBUG_BOOK) and try to play from book
            # - If entries == 0, print it only the FIRST time; from the second time on, be silent
            if n == 0:
                _BOOK_ZERO_HITS += 1
                # print the zero-entry line only for the first miss
                if 'DEBUG_BOOK' in globals() and DEBUG_BOOK and _BOOK_ZERO_HITS < 2:
                    key = chess.polyglot.zobrist_hash(pyb)
                    print(f"[BOOK] fen={pyb.fen()}  key={hex(key)}  entries=0")
                # after the second consecutive zero, disable further book probes this game
                if _BOOK_ZERO_HITS >= 2:
                    BOOK_PROBE_ACTIVE = False
            else:
                # Found book moves → reset the zero streak
                _BOOK_ZERO_HITS = 0

                if 'DEBUG_BOOK' in globals() and DEBUG_BOOK:
                    key = chess.polyglot.zobrist_hash(pyb)
                    es = BOOK.entries(pyb)
                    print(f"[BOOK] fen={pyb.fen()}  key={hex(key)}  entries={len(es)}")
                    for e in sorted(es, key=lambda x: -x.weight)[:10]:
                        try:
                            print("   ", pyb.san(e.move), e.move.uci(), e.weight)
                        except Exception:
                            print("   ", e.move.uci(), e.weight)

                poly_mv = BOOK.pick(
                    pyb,
                    randomize=BOOK_RANDOM,
                    temperature=BOOK_TEMPERATURE,
                    top_k=BOOK_TOP_K,
                )
                if poly_mv:
                    mv = _polyglot_to_engine_move(game_state, poly_mv)
                    if mv is not None:
                        return_queue.put((
                            'book',
                            mv.start_row, mv.start_col, mv.end_row, mv.end_col,
                            mv.promotion_choice if getattr(mv, 'is_pawn_promotion', False) else None
                        ))
                        return
    except Exception as e:
        if 'DEBUG_SEARCH' in globals() and DEBUG_SEARCH:
            print("Book probe failed:", e)

    # --- Instant mate-in-1 chooser (no time slice) ---
    for mv in original_root_moves:
        if _is_mate_after(game_state, mv):
            return_queue.put(mv)
            return

    id_to_move = {m.moveID: m for m in original_root_moves}
    best_move_id = None
    last_safe = original_root_moves[0]  # always-valid fallback

    # Last score used to center the aspiration window (centipawns)
    last_score = 0

    for current_depth in range(1, DEPTH + 1):
        try:
            check_time()  # respect hard cap at depth start
            next_move = None

            # Strong tactical ordering at the root
            root_moves = list(original_root_moves)
            root_moves.sort(key=lambda m: _score_root_move(game_state, m), reverse=True)

            # --- QUICK FORCED-MATE PROBE (depth 1 only) ---
            if current_depth == 1:
                probe_ms = int(min(40, TIME_PER_MOVE * 1000 * 0.25))  # ≤40ms or ≤25% of budget
                mate_line = find_forced_mate_k(game_state, k=5, soft_time_ms=probe_ms)
                if mate_line:
                    mv0 = mate_line[0]
                    if 'DEBUG_SEARCH' in globals() and DEBUG_SEARCH:
                        print("Forced mate found quickly:", mv0)
                    return_queue.put(mv0)
                    return

            nodes_searched = 0
            depth_start = now()

            # --- Aspiration window around last_score (phase-aware width) ---
            phase_here = _phase(game_state)
            base_window = 30  # cp
            window = base_window + int(20 * phase_here)  # EG ~30, MG ~50
            alpha = last_score - window
            beta  = last_score + window

            # For robust timeout logging if we time out before any score is set
            score_for_log = last_score

            # Fail-low/high re-search loop (expands window on demand)
            while True:
                check_time()  # hard cap during re-search loop

                score = findMoveNegaMaxAlphaBeta(
                    game_state, root_moves,
                    current_depth,
                    max(-CHECKMATE, alpha), min(CHECKMATE, beta),
                    turn_multiplier,
                    start_time,
                    # root node is PV by definition
                    is_pv=True,
                    is_root=True,
                    ply=0
                )
                score_for_log = score  # safe for timeout log

                if score <= alpha:
                    window *= 2
                    alpha = score - window
                    continue
                if score >= beta:
                    window *= 2
                    beta = score + window
                    continue
                break  # inside window → accept

            best_move_id = next_move
            if best_move_id in id_to_move:
                last_safe = id_to_move[best_move_id]

            elapsed = max(1e-6, now() - depth_start)
            nps = int(nodes_searched / elapsed)
            last_score = score  # recenter next depth
            white_perspective = _fmt_white_pawns(score, game_state.white_to_move)
            if 'DEBUG_SEARCH' in globals() and DEBUG_SEARCH:
                print(f"depth {current_depth}: best={last_safe}, score={white_perspective}, nps={nps}")

        except SearchTimeout:
            elapsed = max(1e-6, now() - depth_start)
            nps = int(nodes_searched / elapsed)
            white_perspective = _fmt_white_pawns(score_for_log, game_state.white_to_move)
            print(f"Timeout at depth {current_depth}, returning best={last_safe}, last score={white_perspective}, nps={nps}")
            break

        # Optional: stop if we’re close to the cap even after finishing this depth
        try:
            check_time()
        except SearchTimeout:
            if 'DEBUG_SEARCH' in globals() and DEBUG_SEARCH:
                print("Overall time budget reached after completing this depth; stopping ID.")
            break

    return_queue.put(last_safe)

def quiescenceSearch(game_state, alpha, beta, turn_multiplier, start_time, qply=0, qply_max=32, ply=0):
    """
    Fast quiescence: captures + promotions only; allow *one* quiet rook check
    in rookish endgames; otherwise allow at most one quiet check in MG when
    both queens are on. Uses incremental current_eval for stand-pat and delta
    pruning.
    """
    global nodes_searched
    nodes_searched += 1
    check_time()

    make = game_state.makeMove
    undo = game_state.undoMove
    in_check = game_state.inCheck
    get_valid = game_state.getValidMoves
    get_pseudo = game_state.getAllPossibleMoves

    # If in check: full evasions (not cut by QS tail caps)
    if in_check():
        evasions = get_valid()
        if not evasions:
            return -_mate_score(ply)
        best = -CHECKMATE
        a = alpha
        for mv in evasions:
            make(mv)
            try:
                score = -quiescenceSearch(game_state, -beta, -a, -turn_multiplier, start_time,
                                          qply=qply+1, qply_max=qply_max, ply=ply+1)
            finally:
                undo()
            if score >= beta:
                return beta
            if score > best:
                best = score
                if score > a:
                    a = score
        return best

    # ---------------- Phase-aware local QS tail cap (shorter in EG) ----------------
    phase = _phase(game_state)  # 1 → MG, 0 → EG
    local_qply_cap = 24 if phase > 0.45 else 8
    effective_qply_max = min(qply_max, local_qply_cap)
    if qply >= effective_qply_max:
        return alpha

    # ---------- STAND-PAT: use static_eval with FAST/FULL policy ----------
    # We don't have PV info at QS nodes here, so pass is_pv=False, at_root=False.
    fast_flag = _use_fast_eval(game_state, depth=0, is_pv=False, is_root=False)
    stand_pat_pawns = game_state.static_eval(fast=fast_flag)    # white-positive, in pawns
    stand_pat = to_cp(turn_multiplier * stand_pat_pawns)        # convert to side-to-move CP

    if stand_pat >= beta:
        return stand_pat
    if stand_pat > alpha:
        alpha = stand_pat

    # Pseudo moves once
    pseudo = get_pseudo()

    # Base noisy set: captures & promotions
    noisy = [m for m in pseudo if (m.piece_captured != "--" or getattr(m, "is_pawn_promotion", False))]

    # ---------- Quiet checks ----------
    # Allow at most one quiet check per node, but:
    # - MG + both queens on: any piece except K (optionally skip Q)
    # - Rookish EG (no minors, <=2 total rooks, no queens): allow exactly one *rook* quiet check
    if QCHECKS_ENABLE and QCHECKS_MAX_PER_NODE > 0:
        bb = game_state.bitboards
        queens_on   = (bb['wQ'] != 0) and (bb['bQ'] != 0)
        minor_total = (bb['wN'].bit_count() + bb['bN'].bit_count()
                       + bb['wB'].bit_count() + bb['bB'].bit_count())
        rook_total  = bb['wR'].bit_count() + bb['bR'].bit_count()
        zug_prone   = (minor_total == 0 and rook_total <= 2 and not queens_on)

        want_qchecks_mg = (phase > 0.45) and queens_on and (
            _king_danger_flag(game_state) or
            stand_pat <= alpha + 25
        )
        allow_eg_rook_check = zug_prone

        if want_qchecks_mg or allow_eg_rook_check:
            added = 0
            mover_is_white = game_state.white_to_move  # side making the quiet move
            for m in pseudo:
                if added >= QCHECKS_MAX_PER_NODE:
                    break
                if m.piece_captured != "--" or getattr(m, "is_pawn_promotion", False):
                    continue
                if m.piece_moved[1] == 'K':
                    continue
                # EG gate: only rook quiet checks
                if allow_eg_rook_check and not queens_on and m.piece_moved[1] != 'R':
                    continue
                # MG option: skip queen quiet checks if requested
                if queens_on and QCHECKS_SKIP_QUEEN and m.piece_moved[1] == 'Q':
                    continue

                make(m)
                try:
                    # 1) ensure the quiet move is LEGAL (own king not in check after move)
                    ok = True
                    own_kr, own_kc = (game_state.white_king_location if mover_is_white
                                      else game_state.black_king_location)
                    # opponent now to move:
                    own_in_check = game_state.is_square_attacked_bb(own_kr * 8 + own_kc,
                                                                    by_white=(not mover_is_white))
                    if own_in_check:
                        ok = False

                    # 2) and it actually gives check to opponent
                    if ok and game_state.inCheck():
                        noisy.append(m)
                        added += 1
                finally:
                    undo()

    # Filter obviously losing captures (unless promo)
    def _losing_capture(m):
        if m.piece_captured == "--":
            return False
        return (pc_cp(m.piece_captured[1]) - pc_cp(m.piece_moved[1])) <= -150 \
            and not getattr(m, "is_pawn_promotion", False)

    noisy = [m for m in noisy if not _losing_capture(m)]

    if not noisy:
        return alpha

    # Delta pruning
    max_gain = 0
    for m in noisy:
        g = 0
        if m.piece_captured != "--":
            g += pc_cp(m.piece_captured[1])
        if getattr(m, "is_pawn_promotion", False):
            g += pc_cp('Q') - pc_cp('p')
        if g > max_gain:
            max_gain = g

    eg_tighten = 0 if phase > 0.45 else 25
    if stand_pat + max_gain + 50 + eg_tighten < alpha:
        return alpha

    # Ordering (tiny bump for the rare quiet checks)
    def noisy_key(m):
        sc = capture_score(m)
        if getattr(m, "is_pawn_promotion", False):
            sc += 400
        if m.piece_captured == "--":   # these are the injected quiet checks
            sc += 120
        return sc

    noisy.sort(key=noisy_key, reverse=True)

    best = alpha
    for m in noisy:
        make(m)
        try:
            if game_state._own_king_in_check_after_move():
                continue
            score = -quiescenceSearch(game_state, -beta, -best, -turn_multiplier,
                                      start_time, qply=qply+1, qply_max=qply_max, ply=ply+1)
        finally:
            undo()
        if score >= beta:
            return beta
        if score > best:
            best = score
    return best

def findMoveNegaMaxAlphaBeta(game_state, valid_moves, depth, alpha, beta, turn_multiplier, start_time,
                             is_root=False, ply=0, check_ext_used=False, iid_allowed=True, prev_move_id=None,
                             is_pv=False):
    """
    Negamax PVS with TT (mate-normalised), PV ordering, single check-extension,
    cautious LMR, fail-soft returns, plus light static/razor/futility pruning,
    and Internal Iterative Deepening (IID) to seed TT/order. `ply` counts from root (0).
    Counter-move heuristic uses prev_move_id to boost ordering.

    FAST-vs-FULL eval policy:
      - Use FULL only at: root, PV nodes, and shallow leaves (handled by callers/qsearch).
      - Use FAST everywhere else.
    """
    global next_move, nodes_searched
    nodes_searched += 1

    # Derive PV-ness of THIS node
    pv = is_pv or is_root

    # Timeout guard
    check_time()

    # Draw adjudication with *phase-scaled* contempt (discourage draws in MG, not in EG)
    if game_state.is_threefold_repetition() or game_state.is_fifty_move_rule():
        phase_here = _phase(game_state)
        scaled_contempt = int(round(CONTEMPT_CP * phase_here))
        return -scaled_contempt if is_root else 0

    # Exact draw: insufficient mating material (no contempt)
    if game_state.is_insufficient_material():
        return 0

    # Locals for speed
    make = game_state.makeMove
    undo = game_state.undoMove
    get_moves = game_state.getValidMoves
    in_check = game_state.inCheck
    score_move_local = score_move

    # Get move list
    moves = list(valid_moves) if valid_moves is not None else get_moves()

    # --- TT probe ---
    zobrist = game_state.zobrist_key
    entry = TT.get(zobrist)
    if entry and entry.depth >= depth:
        val = score_from_tt(entry.value, ply)
        if entry.flag == EXACT:
            if is_root and entry.best_move is not None:
                next_move = entry.best_move
            return val
        if entry.flag == LOWERBOUND:
            alpha = max(alpha, val)
        elif entry.flag == UPPERBOUND:
            beta = min(beta, val)
        if alpha >= beta:
            if is_root and entry.best_move is not None:
                next_move = entry.best_move
            return val

    # --- Leaf conditions ---
    if not moves:
        return -_mate_score(ply) if in_check() else STALEMATE

    if depth == 0:
        return quiescenceSearch(game_state, alpha, beta, turn_multiplier, start_time, ply=ply)

    # --- Internal Iterative Deepening (IID) ---
    if iid_allowed and depth >= IID_MIN_DEPTH and ((entry is None) or (entry.best_move is None)):
        iid_depth = max(1, depth - IID_REDUCE)
        try:
            _ = findMoveNegaMaxAlphaBeta(
                game_state, None, iid_depth,
                alpha, beta, turn_multiplier, start_time,
                is_root=False, ply=ply, check_ext_used=check_ext_used, iid_allowed=False, prev_move_id=prev_move_id,
                is_pv=False  # IID is a helper search; keep FAST
            )
        except SearchTimeout:
            raise
        entry = TT.get(zobrist)

    # --- Precompute endgame shape flags (used by pruning/LMR/NMP guards) ---
    bb = game_state.bitboards
    minor_total = (bb['wN'].bit_count() + bb['bN'].bit_count()
                   + bb['wB'].bit_count() + bb['bB'].bit_count())
    rook_w = bb['wR'].bit_count()
    rook_b = bb['bR'].bit_count()
    rook_total = rook_w + rook_b
    queens_on = (bb['wQ'] != 0) and (bb['bQ'] != 0)

    rook_vs_rook = (minor_total == 0 and not queens_on and rook_w == 1 and rook_b == 1)
    zug_prone    = rook_vs_rook or (minor_total == 0 and rook_total <= 2)

    # --- Static eval (FAST vs FULL policy here) ---
    use_fast = _use_fast_eval(game_state, depth, is_pv=(is_pv or is_root), is_root=is_root)
    static_eval_pawns = game_state.static_eval(fast=use_fast)
    static_cp = to_cp(turn_multiplier * static_eval_pawns)
    side_in_check = in_check()

    # Razoring (skip in zugzwang-prone endings)
    if (depth == 1) and (not side_in_check) and (static_cp + RAZOR_MARGIN <= alpha) and (not zug_prone):
        return quiescenceSearch(game_state, alpha, beta, turn_multiplier, start_time, ply=ply)

    # Static beta pruning
    if (depth <= 3) and (not side_in_check) and (static_cp - STATIC_BETA_MARGIN * depth >= beta):
        return static_cp

    # ----------------------- Null-move pruning -----------------------
    danger = _king_danger_flag(game_state)
    if depth >= NULLMOVE_MIN_DEPTH and (not side_in_check) and _has_non_pawn_material(game_state, game_state.white_to_move):
        allow = True

        # R-only / zugzwang-prone endings → disable NMP entirely
        if zug_prone:
            allow = False

        R = NULLMOVE_R_BASE + (1 if depth >= NULLMOVE_R_BONUS_D else 0)
        if danger and depth >= 5:
            R = 1
        else:
            allow = False

        if allow:
            token = game_state.makeNullMove()
            try:
                score = -findMoveNegaMaxAlphaBeta(
                    game_state, None, depth - 1 - R, -beta, -beta + 1,
                    -turn_multiplier, start_time,
                    is_root=False, ply=ply+1, check_ext_used=False, iid_allowed=True, prev_move_id=None,
                    is_pv=False  # null-move search is never PV
                )
            finally:
                game_state.undoNullMove(token)
            if score >= beta:
                return score
    # ----------------------------------------------------------------

    # --- Ordering: TT move first, then captures MVV-LVA, then killers/history/counter-move ---
    tt_move_id = entry.best_move if entry else None
    moves.sort(key=lambda m: score_move_local(m, tt_move_id, ply, prev_move_id), reverse=True)

    max_score = -CHECKMATE
    alpha_orig = alpha
    first = True
    best_move_local = None

    for idx, move in enumerate(moves):
        check_time()

        mover_is_white = game_state.white_to_move  # save BEFORE make()
        make(move)
        try:
            next_moves = get_moves()  # compute once on the child
            gives_check = in_check()

            # Single check extension (very conservative)
            new_depth = depth - 1
            if gives_check and depth >= 2 and not check_ext_used:
                new_depth += 1
                next_check_ext_used = True
            else:
                next_check_ext_used = check_ext_used

            # Promotion / near-promotion extension
            if getattr(move, "is_pawn_promotion", False):
                new_depth += 1
            else:
                # near-promotion = pawn reaching the 7th rank from the mover’s POV (quiet or capture)
                to_r = move.end_row
                if move.piece_moved[1] == 'p':
                    if (mover_is_white and to_r == 1) or ((not mover_is_white) and to_r == 6):
                        new_depth += 1

            # Classify quiet (prevents pruning of captures/promo/castles or checking moves)
            is_quiet = (
                move.piece_captured == "--"
                and not getattr(move, "is_pawn_promotion", False)
                and not getattr(move, 'is_castle_move', getattr(move, 'isCastleMove', False))
                and not gives_check
            )

            # Futility pruning for late quiets at shallow depth (skip in zugzwang-prone endings)
            if is_quiet and (new_depth <= 2) and (not side_in_check) and (not gives_check) and (not zug_prone):
                fut_margin = FUTILITY_BASE_MARGIN * new_depth + 100
                if static_cp + fut_margin <= alpha:
                    # prune
                    score = -CHECKMATE  # dummy; won't beat max_score
                    raise _PrunedQuiet  # jump to finally/undo and continue
            # --- LMR on late quiets ---
            # Allow mild reduction even in zugzwang-prone endings, but only for very late moves (idx >= 8).
            can_reduce = (not first) and (new_depth >= 2) and is_quiet and (idx >= 4)
            if can_reduce and ((not zug_prone) or (idx >= 8)):
                reduction = 1 + (1 if (idx >= 12 and not zug_prone) else 0)
                # Slightly stronger reduction for non-zug-prone trees on every 4th late move
                if (idx & 3) == 0 and (not zug_prone):
                    reduction += 1
                red_depth = max(1, new_depth - reduction)

                # reduced-depth null-window search (non-PV)
                score = -findMoveNegaMaxAlphaBeta(
                    game_state, next_moves, red_depth,
                    -alpha - 1, -alpha, -turn_multiplier, start_time,
                    is_root=False, ply=ply+1, check_ext_used=next_check_ext_used, iid_allowed=True,
                    prev_move_id=move.moveID, is_pv=False
                )
                # re-search if promising (still treat as non-PV for eval policy)
                if score > alpha:
                    score = -findMoveNegaMaxAlphaBeta(
                        game_state, next_moves, new_depth,
                        -beta, -alpha, -turn_multiplier, start_time,
                        is_root=False, ply=ply+1, check_ext_used=next_check_ext_used, iid_allowed=True,
                        prev_move_id=move.moveID, is_pv=False
                    )
            else:
                # --- PVS ---
                if first:
                    # full-window on first move of a PV node → child is PV
                    score = -findMoveNegaMaxAlphaBeta(
                        game_state, next_moves, new_depth,
                        -beta, -alpha, -turn_multiplier, start_time,
                        is_root=False, ply=ply+1, check_ext_used=next_check_ext_used, iid_allowed=True,
                        prev_move_id=move.moveID, is_pv=pv
                    )
                else:
                    # null-window first (non-PV)
                    score = -findMoveNegaMaxAlphaBeta(
                        game_state, next_moves, new_depth,
                        -alpha - 1, -alpha, -turn_multiplier, start_time,
                        is_root=False, ply=ply+1, check_ext_used=next_check_ext_used, iid_allowed=True,
                        prev_move_id=move.moveID, is_pv=False
                    )
                    # re-search on fail-high; now this child becomes PV
                    if alpha < score < beta:
                        score = -findMoveNegaMaxAlphaBeta(
                            game_state, next_moves, new_depth,
                            -beta, -alpha, -turn_multiplier, start_time,
                            is_root=False, ply=ply+1, check_ext_used=next_check_ext_used, iid_allowed=True,
                            prev_move_id=move.moveID, is_pv=True
                        )
        except _PrunedQuiet:
            pass
        finally:
            undo()

        first = False

        # Fail-soft keep best
        if score > max_score:
            max_score = score
            best_move_local = move.moveID
            if is_root:
                next_move = move.moveID

        # Alpha-beta update
        if score > alpha:
            alpha = score
        if alpha >= beta:
            # quiet cut → history & killers + learn counter-move
            if move.piece_captured == "--":
                history_scores.add(move.moveID, depth * depth)
                k0, k1 = killers[ply]
                if move.moveID != k0:
                    killers[ply][1] = k0
                    killers[ply][0] = move.moveID
                if prev_move_id is not None:
                    counter_move[prev_move_id] = move.moveID
            break

    # TT store (mate-normalised score)
    if max_score <= alpha_orig:
        flag = UPPERBOUND
    elif max_score >= beta:
        flag = LOWERBOUND
    else:
        flag = EXACT
    TT[zobrist] = TTEntry(depth, flag, score_to_tt(max_score, ply), best_move_local)
    return max_score


_START_BOARD = [
    ["bR","bN","bB","bQ","bK","bB","bN","bR"],
    ["bp","bp","bp","bp","bp","bp","bp","bp"],
    ["--","--","--","--","--","--","--","--"],
    ["--","--","--","--","--","--","--","--"],
    ["--","--","--","--","--","--","--","--"],
    ["--","--","--","--","--","--","--","--"],
    ["wp","wp","wp","wp","wp","wp","wp","wp"],
    ["wR","wN","wB","wQ","wK","wB","wN","wR"],
]

def _rc_to_pc_sq(r: int, c: int) -> int:
    return (7 - r) * 8 + c

def _pc_sq_to_rc(sq: int) -> tuple[int, int]:
    return (7 - (sq // 8), sq % 8)

def _castling_san_for_fen(gs) -> str:
    """Only include rights that make sense for the current piece placement."""
    b = gs.board
    cr = gs.current_castling_rights
    rights = []
    # White
    if cr.wks and b[7][4] == "wK" and b[7][7] == "wR":
        rights.append("K")
    if cr.wqs and b[7][4] == "wK" and b[7][0] == "wR":
        rights.append("Q")
    # Black
    if cr.bks and b[0][4] == "bK" and b[0][7] == "bR":
        rights.append("k")
    if cr.bqs and b[0][4] == "bK" and b[0][0] == "bR":
        rights.append("q")
    return "".join(rights) if rights else "-"

def _board_to_fen(gs) -> str:
    """Build a FEN from the *current* GameState board + flags."""
    # 1) piece placement (r=0 is rank 8)
    rows = []
    for r in range(8):
        empties = 0
        row_str = []
        for c in range(8):
            p = gs.board[r][c]
            if p == "--":
                empties += 1
            else:
                if empties:
                    row_str.append(str(empties))
                    empties = 0
                col, typ = p[0], p[1]
                row_str.append(typ.upper() if col == "w" else typ.lower())
        if empties:
            row_str.append(str(empties))
        rows.append("".join(row_str))
    placement = "/".join(rows)

    # 2) active color
    active = "w" if gs.white_to_move else "b"

    # 3) castling rights (sanitised against current piece placement)
    castling = _castling_san_for_fen(gs)

    # 4) en-passant target (if set)
    if gs.enpassant_possible:
        r, c = gs.enpassant_possible
        ep = chess.square_name(_rc_to_pc_sq(r, c))
    else:
        ep = "-"

    # 5) halfmove / fullmove (Polyglot ignores fullmove, but include something sane)
    halfmove = str(getattr(gs, "halfmove_clock", 0))
    fullmove = str(1 + sum(1 for m in gs.move_log if m.piece_moved[0] == "b"))

    return f"{placement} {active} {castling} {ep} {halfmove} {fullmove}"

def _looks_like_custom_start(gs) -> bool:
    """True if we didn't start from the normal initial setup."""
    if gs.move_log:
        return False
    # Compare piece placement only
    return gs.board != _START_BOARD

def _gs_to_pyboard(gs) -> chess.Board:
    """
    Create a python-chess Board matching gs:
      - If we look like a custom setup (no moves + non-start board): build from FEN.
      - Otherwise: replay the move log from the standard start (preserves EP/castling).
    """
    if _looks_like_custom_start(gs):
        fen = _board_to_fen(gs)
        try:
            return chess.Board(fen=fen)
        except Exception:
            # If something is inconsistent (e.g., impossible castling flags),
            # fall back to stripping castling and EP.
            placement, side, _, _, half, full = fen.split(" ")
            safe_fen = f"{placement} {side} - - {half} {full}"
            return chess.Board(fen=safe_fen)

    # Normal games/undos: reconstruct by replay (guarantees EP/castling fidelity)
    b = chess.Board()
    for mv in gs.move_log:
        from_sq = _rc_to_pc_sq(mv.start_row, mv.start_col)
        to_sq   = _rc_to_pc_sq(mv.end_row,   mv.end_col)
        promo = None
        if getattr(mv, "is_pawn_promotion", False):
            ch = getattr(mv, "promotion_choice", "Q") or "Q"
            promo = {"Q": chess.QUEEN, "R": chess.ROOK, "B": chess.BISHOP, "N": chess.KNIGHT}.get(ch, chess.QUEEN)
        u = chess.Move(from_sq, to_sq, promotion=promo)
        if u not in b.legal_moves:
            # If replay breaks (e.g., the UI injected a custom mid-game FEN), use FEN route as a fallback.
            return chess.Board(fen=_board_to_fen(gs))
        b.push(u)
    return b

def _polyglot_to_engine_move(gs, pc_move: chess.Move):
    sr, sc = _pc_sq_to_rc(pc_move.from_square)
    er, ec = _pc_sq_to_rc(pc_move.to_square)
    promo_letter = None
    if pc_move.promotion == chess.QUEEN:  promo_letter = 'Q'
    elif pc_move.promotion == chess.ROOK: promo_letter = 'R'
    elif pc_move.promotion == chess.BISHOP: promo_letter = 'B'
    elif pc_move.promotion == chess.KNIGHT: promo_letter = 'N'

    for m in gs.getValidMoves():
        if (m.start_row, m.start_col, m.end_row, m.end_col) == (sr, sc, er, ec):
            if promo_letter and getattr(m, "is_pawn_promotion", False):
                m.promotion_choice = promo_letter
                if hasattr(m, "recompute_id"):
                    m.recompute_id()
            return m
    return None


class EvalContext:
    __slots__ = (
        'gs','is_white','own','opp','enemy','full_moves','move_log',
        'piece_positions','pawn_files','enemy_pawn_positions',
        'all_moves','self_capture_values','opp_attack_values',
        'opp_min_attacker_value','small_endgame','material_adv',
        'eval',   # ← NEW: white-positive eval snapshot (pawns)
    )

    def __init__(self, gs, is_white, light: bool = False):
        self.gs = gs
        self.is_white = is_white
        self.own, self.opp = ('w','b') if is_white else ('b','w')
        self.enemy = self.opp
        self.full_moves = len(gs.move_log)//2 + 1
        self.move_log = gs.move_log

        # --- piece locations snapshot (cheap)
        from collections import defaultdict, Counter
        pp = defaultdict(list)
        board = gs.board
        for r in range(8):
            row = board[r]
            for c in range(8):
                p = row[c]
                if p != "--":
                    pp[p].append((r,c))
        self.piece_positions = pp

        # small endgame if phase is low OR (no queens and at most one rook each)
        phase_now = _phase(gs)
        wR = len(pp.get('wR', ())); bR = len(pp.get('bR', ()))
        wMin = len(pp.get('wN',())) + len(pp.get('wB',()))
        bMin = len(pp.get('bN',())) + len(pp.get('bB',()))
        noQ  = (not pp.get('wQ')) and (not pp.get('bQ'))

        self.small_endgame = (phase_now <= 0.30) or (noQ and (wMin + bMin) <= 2 and wR <= 1 and bR <= 1)

        # pawn helpers
        self.pawn_files = Counter(c for (_r,c) in pp[self.own+'p'])
        self.enemy_pawn_positions = set(pp[self.opp+'p'])

        # defaults for heavy fields (so FAST features can access safely)
        self.all_moves = ()
        self.self_capture_values = {}
        self.opp_attack_values = {}
        self.opp_min_attacker_value = {}

        # material advantage (cheap)
        def _mat(side):
            total = 0.0
            for t in ('p','N','B','R','Q'):
                total += piece_score[t] * len(pp.get(side + t, ()))
            return total
        self.material_adv = _mat(self.own) - _mat(self.opp)

        # initial eval snapshot (white-positive, in pawns). We overwrite/update this
        # inside scoreBoard() as we accumulate features.
        self.eval = float(getattr(gs, 'current_eval', 0.0))

        if light:
            return  # ← skip heavy maps entirely in FAST mode

        # ---------- heavy section (FULL only) ----------
        # Snapshot mutable state
        saved_to_move  = gs.white_to_move
        saved_pins     = getattr(gs, 'pins', [])[:]
        saved_checks   = getattr(gs, 'checks', [])[:]
        saved_in_check = getattr(gs, 'in_check', False)
        saved_ep       = getattr(gs, 'enpassant_possible', ())
        saved_pmap     = dict(getattr(gs, 'pinned_map', {}))

        def _restore():
            gs.white_to_move = saved_to_move
            if hasattr(gs, 'pins'):     gs.pins = saved_pins[:]
            if hasattr(gs, 'checks'):   gs.checks = saved_checks[:]
            if hasattr(gs, 'in_check'): gs.in_check = saved_in_check
            gs.enpassant_possible = saved_ep
            gs.pinned_map = dict(saved_pmap)

        def _gen_pseudo_for(side_is_white):
            gs.white_to_move = side_is_white
            gs.enpassant_possible = saved_ep if (side_is_white == saved_to_move) else ()
            gs.checkForPinsAndChecks()
            return gs.getAllPossibleMoves()

        # our pseudo
        self.all_moves = _gen_pseudo_for(is_white)
        _restore()

        # opp pseudo
        opp_pseudo = _gen_pseudo_for(not is_white)
        _restore()

        # self capture values (destination -> max victim value)
        scv = {}
        for m in self.all_moves:
            if m.piece_captured != "--":
                sq = (m.end_row, m.end_col)
                val = piece_score[m.piece_captured[1]]
                if val > scv.get(sq, -1):
                    scv[sq] = val
        self.self_capture_values = scv

        # opponent capture values
        oav = {}
        for m in opp_pseudo:
            if m.piece_captured != "--":
                sq = (m.end_row, m.end_col)
                val = piece_score[m.piece_captured[1]]
                if val > oav.get(sq, -1):
                    oav[sq] = val
        self.opp_attack_values = oav

        # opponent min attacker value (cheap SEE-ish)
        min_att = {}
        for m in opp_pseudo:
            pm = m.piece_moved[1]
            # treat both attribute spellings for castles
            is_castle = getattr(m, 'is_castle_move', getattr(m, 'isCastleMove', False))
            if pm == 'K' and is_castle:
                continue
            if pm == 'p':
                continue
            v = piece_score[pm]
            sq = (m.end_row, m.end_col)
            prev = min_att.get(sq)
            min_att[sq] = v if prev is None else min(prev, v)

        pawn_dir = (-1 if self.opp == 'w' else 1)
        for (r, c) in pp[self.opp+'p']:
            rr = r + pawn_dir
            if 0 <= rr < 8:
                v = piece_score['p']
                if c-1 >= 0:
                    sq = (rr, c-1)
                    prev = min_att.get(sq)
                    min_att[sq] = v if prev is None else min(prev, v)
                if c+1 < 8:
                    sq = (rr, c+1)
                    prev = min_att.get(sq)
                    min_att[sq] = v if prev is None else min(prev, v)
        self.opp_min_attacker_value = min_att

# Evaluation Enhancements - so that engine makes stronger choices at leaves

"""
Num | Function                       | What it does                                          | Bonus/Penalty
----|--------------------------------|-------------------------------------------------------|----------------------------
 1  | mobility_score                 | MG mobility from pseudo-moves (per piece-type)        | +0.01–0.025 per move, cap +0.40; tapered by phase (EG 0)
 2  | king_safety_score              | Pawn shield + king-ring pressure                      | Shield −0.25 per missing pawn (3-square) + extra −0.15 if enemy pawn occupies shield; Ring −0.05 per attacked ring square (cap −035), overall MG cap −1.0; full ×phase with both Qs; ×0.50×phase with 1 queen; ×0.30×phase when queenless (tapered, never vanishes)
 3  | pawn_structure_score           | Iso/doubled/IQP; passers; extras                      | Iso: −0.20/−0.15/−0.10 (c–f/b–g/a–h) + EG 0.55×; Doubled: −0.10 MG, −0.05 EG per extra; Passer EG by rank [0.00, 0.10, 0.25, 0.45, 0.65, 0.90] (r2..r7), MG 0.40×; Supported +0.15 EG/+0.05 MG; Rook behind +0.40 EG/+0.10 MG; Rook in front −0.10 EG; Free path +0.10 EG/+0.05 MG; Blockaded by minor −0.08 EG; Connected passers ±(0.08 MG / 0.15 EG) per own link, harsher for enemy (−0.10/−0.18); Defend behind enemy passer +0.15 EG; King toward enemy passer nonlinear up to +0.20 EG (≤2 steps), +0.10 (≤4); IQP −0.10 MG/−0.03 EG; a/b overextend −0.06 each (cap −0.12) MG
 4  | bishop_pair_score              | Bishop pair stronger as pawns vanish                  | Base +0.35 MG / +0.25 EG; extra up to +0.25 MG / +0.40 EG with 0 pawns
 5  | rook_open_file_score           | Rook on fully open file                               | +0.30 per rook on file with no pawns (either side)
 6  | center_control_score           | Control d4/e4 (W) or d5/e5 (B)                        | +0.07 per target controlled, cap +0.30, MG-weighted
 7  | castling_score                 | Reward being castled                                  | +0.40 MG-only if king on g/c file
 8  | rook_seventh_rank_score        | Rooks on 7th/2nd rank                                 | +0.25 per rook, cap +0.50
 9  | early_queen_development_penalty| Punish very early queen moves                         | −0.30 × phase if queen moved before ply 20 (FM<10)
10  | minor_piece_development_score  | Reward developed N/B                                  | +0.30 each off back rank, cap +1.20, MG-weighted
11  | castling_urgency_score         | Reward fast, penalise late castling                   | Castled by FM≤8: +0.30 × phase; Uncastled FM≥16: −0.35 × phase
12  | rook_connection_score          | Connected rooks on back rank                          | +0.35 × phase if no blockers
13  | central_pawn_duo_score         | d/e pawns advanced together                           | +0.25 × phase if duo on d4+e4 (W) / d5+e5 (B)
14  | king_move_retention_score      | Penalize early king wander if not castled             | −0.25 × phase after non-castling K move if still uncastled
15  | queen_exposure_penalty         | Queen sitting on attacked center                      | −0.20 per d4/e4/d5/e5 if attacked, MG-weighted
16  | queen_premature_release_penalty| Queen moved before minors                             | −0.25 × phase per home minor not developed if first Q move < ply 16
17  | king_centralisation_score      | King controls d4/e4/d5/e5 in EG                       | +0.10 per square, cap +0.50 (EG-only)
18  | king_opposition_score          | Classic opposition in king+pawn endgames              | +0.20 if opp to move, else +0.10 (EG-only)
19  | king_tropism_score             | Pieces approach enemy king                            | +0.02/(1+dist) × weight, cap +0.25 (MG-heavy → early EG)
20  | knight_outpost_score           | Supported, unchaseable knight on c–f4/5               | +0.20 (MG) → +0.10 (EG) per outpost
21  | bad_bishop_penalty             | Bishop stuck behind fixed pawns                       | −0.15 × phase per bishop on majority pawn color, MG-only
22  | king_wing_pawn_weakening_penalty| f/g-pawn push with king on e1/e8                     | −0.25 (f moved), −0.20 (g moved); cap −0.40 × phase
23  | uncastled_open_center_penalty  | Open/semi-open d/e with king on e1/e8                 | −0.16 open, −0.10 semi-open (per file), MG-weighted
24  | uncastled_queen_on_board_penalty| Staying uncastled while both queens on               | Up to −0.15 × phase (fades after ~FM14)
25  | early_BxN_without_damage_penalty| Early B×N without doubling c–f pawns                 | −0.30 × phase (≈ before FM10–14 unless doubled pawns)
26  | simplify_when_ahead_score      | Prefer fewer enemy pieces when up material            | +0.15 × (4−pieces_left) × min(2,adv) × EG, much stronger
27  | kaufman_pawncount_piece_tweak  | N↑, R↓ per pawn above/below 5                         | +0.0625×Δpawns×#N − 0.125×Δpawns×#R
28  | kaufman_B_vs_N_pawncount_tweak | B vs N with few/many pawns                            | If no BP: ≥6 pawns → −0.125×(B−N); ≤4 pawns → +0.125×(B−N)
29  | kaufman_ex_context_correction  | Contextual value of the exchange                      | Majors on (Q on & ≥3R): −0.25×units; Majors off (no Q & ≤2R): +0.25×; Opp BP when up exchange: −0.10×; Pawn-count slope −0.03×(avg_p−5)×units; clamp ±0.50
30  | kaufman_q_vs_2r_correction     | Q vs 2R context                                       | Many minors: Q side +0.25 / 2R side −0.25; Few pawns: Q side −0.25 / 2R side +0.25
31  | rook_pawn_discount_score       | Slightly devalue a/h pawns unless strong              | Base ≈ −0.15 (≈0.06 MG + 0.09 EG); halve if rank ≥6; ×0.7 if supported; ×0.7 if passed
32	| rook_cutoff_king_score	     | Rook cuts off enemy king (queenless)	                 | Same rank +0.20, same file +0.25; EG-weighted, cap +0.40
33	| rook_activity_endgame_score	 | Count empty rook-ray squares in EG	                 | +0.01 per reachable empty square; cap +0.30, EG-only
34	| king_center_distance_score	 | Pull king toward center in EG-ish	                 | +0.20 − 0.05×d (Chebyshev); floor 0
35	| king_edge_penalty_score	     | Push king off edge/corner in EG-ish	                 | Edge −0.15, corner −0.25
36	| king_support_own_passed_score	 | King close to square in front of own passer	         | +0.25 − 0.04×dist (Manhattan to front square); floor 0
37	| anti_shuffling_score	         | Penalize endless repetition in won positions	         | −0.05 per 2 plies without pawn/capture, cap −0.25 (if eval > +1.5)
38	| pawn_push_urgency_score	     | Encourage pushing passed pawns when ahead	         | +0.04 × rank (per passer), cap +0.40; only if eval > +1.5
39	| game_phase_factor (utility)	 | Returns game phase factor for tapering	             | 1.0 = pure opening, 0.0 = pure endgame
"""

# --- tiny helper used by all three: material phase in [0..1] (1 = opening/MG, 0 = pure EG)
def _phase(gs):
    """
    Cheap material-based phase score.
    N=1, B=1, R=2, Q=4; pawns don't affect phase.
    Start sum ~= 24, taper toward 0 as material disappears.
    """
    bb = gs.bitboards
    cnt = (bb['wN'].bit_count() + bb['bN'].bit_count()
           + bb['wB'].bit_count() + bb['bB'].bit_count()
           + 2 * (bb['wR'].bit_count() + bb['bR'].bit_count())
           + 4 * (bb['wQ'].bit_count() + bb['bQ'].bit_count()))
    return min(24, cnt) / 24.0

# 1) Mobility Bonus (middlegame-weighted, small)
def mobility_score(ctx):
    """
    Middlegame-only mobility.
    Weigh mobility by piece type so R/Q mobility counts more than N.
    Uses your engine's pseudo-legal moves in ctx.all_moves.
    """
    # Only used in FULL mode → ctx.all_moves is populated
    phase = _phase(ctx.gs)  # 1 → MG, 0 → EG
    if phase <= 0.0 or not ctx.all_moves:
        return 0.0

    # Tunable weights per piece type (engine letters: 'p','N','B','R','Q','K')
    weights = {"N": 0.01, "B": 0.015, "R": 0.02, "Q": 0.025}

    score = 0.0
    for m in ctx.all_moves:
        t = m.piece_moved[1]   # your Move stores piece type at index 1
        w = weights.get(t)
        if w:
            score += w

    mg = min(score, 0.40)  # cap mobility influence
    return phase * mg  # EG term = 0

# 2) King safety: pawn shield + king ring pressure (MG-heavy)
def king_safety_score(ctx):
    """
    Pawn shield + king-ring pressure.

    MG policy:
      - With BOTH queens on: use full weight (as before).
      - With NO queens on (queenless middlegame): use 30% of MG weight.
      - With ONE queen only: use 50% of MG weight (single-queen middlegames can still be sharp).
      - In late MG/EG: taper smoothly with phase, never fully vanish.

    Shield: −0.20 per missing pawn in the 3-square shield.
             Extra −0.15 if enemy pawn occupies a shield square.
    Ring:   −0.04 per enemy-attacked ring square, capped at −0.28.
    Overall MG cap: −0.75.
    """
    gs = ctx.gs
    phase = _phase(gs)  # 1 → MG, 0 → EG
    if phase <= 0.1:  # deep endgame: safety irrelevant
        return 0.0

    bb = gs.bitboards
    queens_on_both = (bb['wQ'] != 0) and (bb['bQ'] != 0)
    queenless_both = (bb['wQ'] == 0) and (bb['bQ'] == 0)

    # King square
    kr, kc = (gs.white_king_location if ctx.is_white else gs.black_king_location)

    # Pawn shield (three squares in front of king)
    dr = -1 if ctx.is_white else 1
    r0 = kr + dr
    pawn = ctx.own + 'p'
    opp_pawn = ('w' if not ctx.is_white else 'b') + 'p'
    board = gs.board

    shield = 0
    shield_penalty_extra = 0
    if 0 <= r0 < 8:
        for cc in (kc - 1, kc, kc + 1):
            if 0 <= cc < 8:
                piece = board[r0][cc]
                if piece == pawn:
                    shield += 1
                elif piece == opp_pawn:
                    shield_penalty_extra += 0.15
    shield_term = -0.25 * (3 - shield) - shield_penalty_extra

    # King ring under attack (9 squares incl. king square)
    ring_pen = 0.0
    opp_is_white = not ctx.is_white
    for rr in (kr - 1, kr, kr + 1):
        if 0 <= rr < 8:
            for cc in (kc - 1, kc, kc + 1):
                if 0 <= cc < 8 and gs.is_square_attacked_bb(rr * 8 + cc, by_white=opp_is_white):
                    ring_pen += 0.05
    ring_pen = -min(ring_pen, 0.35)

    mg = shield_term + ring_pen
    mg = max(mg, -1.0)  # overall MG cap

    # Scaling by queen presence
    if queens_on_both:
        scale = phase
    elif queenless_both:
        scale = 0.30 * max(phase, 0.3)  # taper but don’t vanish too early
    else:
        scale = 0.50 * max(phase, 0.3)  # single queen middlegames: half weight

    return scale * mg

# 3) Pawn structure (isolated/doubled/IQP; passed pawns; tiny extras)
def pawn_structure_score(ctx):
    """
    Evaluate pawn structure:
    a) Isolated: no friendly pawn on adjacent files → penalty (MG-weighted)
    b) Doubled: penalty per extra pawn on a file (MG-weighted)
    c) Passed pawns: EG bonus by rank (now [0.00, 0.10, 0.25, 0.45, 0.65, 0.90] on ranks 2..7)
       with MG shadow (0.40× EG), plus extras:
         - supported passer  (+0.15 EG / +0.05 MG)
         - rook behind passer (+0.40 EG / +0.10 MG)
         - rook in front of passer (−0.10 EG)
         - free path (+0.10 EG / +0.05 MG)
         - blockaded by enemy minor in front (−0.08 EG)
         - connected passers synergy: +0.08 MG / +0.15 EG per adjacent-file link (own),
           subtract slightly stronger for enemy (−0.10 MG / −0.18 EG)
         - defensive: rook behind enemy passer (+0.15 EG)
         - king toward enemy passer: nonlinear bonus up to +0.20 EG if ≤2 away, +0.10 if ≤4 away
    d) Static IQP penalty on d4 (W) / d5 (B)
    e) Wing overextension: unsupported a/b pawn on 5th+ rank → −0.06 each (cap −0.12), MG-only
    """
    gs    = ctx.gs
    phase = _phase(gs)   # 1 (MG) → 0 (EG)
    board = gs.board
    is_w  = ctx.is_white
    ownp  = ctx.own + 'p'
    enemc = ctx.opp
    pf    = ctx.pawn_files
    ep    = set(ctx.enemy_pawn_positions)
    pos   = ctx.piece_positions

    mg = 0.0
    eg = 0.0

    # a) Isolated & b) Doubled
    get = pf.get
    for f, cnt in pf.items():
        if get(f-1, 0) + get(f+1, 0) == 0:  # isolated
            if   2 <= f <= 5: iso = -0.20
            elif f in (1, 6): iso = -0.15
            else:             iso = -0.10
            mg += iso
            eg += 0.55 * iso
        if cnt > 1:  # doubled
            mg += -0.10 * (cnt - 1)
            eg += -0.05 * (cnt - 1)

    # c) Passed pawns
    PASSED_EG = [0.00, 0.10, 0.25, 0.45, 0.65, 0.90]  # smoother scale
    fwd = -1 if is_w else 1
    rooks = pos.get(ctx.own + 'R', ())

    def _any_enemy_pawn_same_file_ahead(r, c):
        rr = r + fwd
        while 0 <= rr < 8:
            if (rr, c) in ep:
                return True
            rr += fwd
        return False

    own_pawns = list(pos.get(ownp, ()))
    own_pass_files = set()

    for (r, c) in own_pawns:
        rr = r + fwd
        blocked = False
        while 0 <= rr < 8:
            if ((rr, c) in ep or
                (c > 0 and (rr, c-1) in ep) or
                (c < 7 and (rr, c+1) in ep)):
                blocked = True
                break
            rr += fwd
        if blocked:
            continue

        own_pass_files.add(c)
        rank = (8 - r) if is_w else (r + 1)
        if 2 <= rank <= 7:
            eg_bonus = PASSED_EG[rank - 2]
            mg_bonus = 0.40 * eg_bonus
            eg += eg_bonus
            mg += mg_bonus

            # Supported passer
            br = r + (1 if is_w else -1)
            if 0 <= br < 8:
                if (c > 0 and board[br][c-1] == ownp) or (c < 7 and board[br][c+1] == ownp):
                    eg += 0.15
                    mg += 0.05

            # Rook behind passer
            for rrk, crk in rooks:
                if crk == c and ((is_w and rrk > r) or (not is_w and rrk < r)):
                    eg += 0.40
                    mg += 0.10
                    break

            # Rook in front
            for rrk, crk in rooks:
                if crk == c and ((is_w and rrk < r) or ((not is_w) and rrk > r)):
                    eg -= 0.10
                    break

            # Free path
            if not _any_enemy_pawn_same_file_ahead(r, c):
                mg += 0.05
                eg += 0.10

            # Blockaded by minor
            fr = r + fwd
            if 0 <= fr < 8:
                sq = board[fr][c]
                if sq != '--' and sq[0] == enemc and sq[1] in ('N', 'B'):
                    eg -= 0.08

    # Connected passers synergy
    if own_pass_files:
        cnt_links = sum(1 for f in sorted(own_pass_files) if (f+1) in own_pass_files)
        mg += 0.08 * cnt_links
        eg += 0.15 * cnt_links

    # Enemy connected passers (harsher penalty)
    oppp = ctx.opp + 'p'
    opp_pawns = list(pos.get(oppp, ()))
    own_set = set(own_pawns)
    opp_pass_files = set()
    opp_pass_pos = set()
    fwd_opp = -1 if (not is_w) else 1

    for (r, c) in opp_pawns:
        rr = r + fwd_opp
        blocked = False
        while 0 <= rr < 8:
            if ((rr, c) in own_set or
                (c > 0 and (rr, c-1) in own_set) or
                (c < 7 and (rr, c+1) in own_set)):
                blocked = True
                break
            rr += fwd_opp
        if not blocked:
            opp_pass_files.add(c)
            opp_pass_pos.add((r, c))

    if opp_pass_files:
        cnt_links = sum(1 for f in sorted(opp_pass_files) if (f+1) in opp_pass_files)
        mg -= 0.10 * cnt_links
        eg -= 0.18 * cnt_links

    # Rook behind enemy passer
    if opp_pass_pos and rooks:
        for (r, c) in opp_pass_pos:
            for rrk, crk in rooks:
                if crk != c:
                    continue
                if (is_w and rrk < r) or ((not is_w) and rrk > r):
                    eg += 0.15
                    break

    # King toward enemy passer (nonlinear)
    if opp_pass_pos:
        kr, kc = (gs.white_king_location if is_w else gs.black_king_location)
        best = min(abs(kr - r) + abs(kc - c) for (r, c) in opp_pass_pos)
        if best <= 2:
            eg += 0.20
        elif best <= 4:
            eg += 0.10

    # d) IQP penalty
    iqr, iqc = (4, 3) if is_w else (3, 3)
    if (iqr, iqc) in pos.get(ownp, ()):
        have_c = get(2, 0) > 0
        have_e = get(4, 0) > 0
        if not have_c and not have_e:
            mg -= 0.10
            eg -= 0.03

    # e) Wing pawn overextension
    wing_hits = 0
    back = 1 if is_w else -1
    for (r, c) in own_pawns:
        if c not in (0, 1):
            continue
        rank = (8 - r) if is_w else (r + 1)
        if rank < 5:
            continue
        br = r + back
        supported = False
        if 0 <= br < 8:
            if (c > 0 and board[br][c-1] == ownp) or (c < 7 and board[br][c+1] == ownp):
                supported = True
        if not supported:
            wing_hits += 1
    if wing_hits:
        mg += -min(0.12, 0.06 * wing_hits)

    return phase * mg + (1.0 - phase) * eg

# 4) Bishop-pair (tapered)
def bishop_pair_score(ctx):
    """
    Bishop pair bonus that grows as pawns disappear (Kaufman-inspired, tuned).
    Base: +0.35 (MG) / +0.25 (EG);
    Extra: up to +0.25 (MG) / +0.40 (EG) when total pawns ≈ 0.
    """
    bb = ctx.gs.bitboards
    if len(ctx.piece_positions.get(ctx.own + 'B', ())) < 2:
        return 0.0

    phase = _phase(ctx.gs)
    total_pawns = bb['wp'].bit_count() + bb['bp'].bit_count()   # 0..16
    pawn_scarcity = (16 - total_pawns) / 16.0                   # 0..1

    base_mg, base_eg = 0.35, 0.25
    extra_mg = 0.25 * pawn_scarcity
    extra_eg = 0.40 * pawn_scarcity   # ↑ allow EG up to +0.65 total

    return phase * (base_mg + extra_mg) + (1.0 - phase) * (base_eg + extra_eg)

# 5) Rook on open file (no pawns of either side on that file)
def rook_open_file_score(ctx):
    """
    +0.30 pawn for each rook on a fully open file (no friendly or enemy pawns).
    Stronger weight since rooks are much more valuable on open files in practical play.
    """
    pf = ctx.pawn_files
    ep = ctx.enemy_pawn_positions
    score = 0.0
    for _, file in ctx.piece_positions.get(ctx.own + 'R', ()):
        if pf.get(file, 0) == 0 and all(c != file for (_r, c) in ep):
            score += 0.30
    return score

# 6) Small-centre control (MG-only)
def center_control_score(ctx):
    """
    +0.07 pawn per controlled small-centre square (W: d4/e4; B: d5/e5), cap +0.30.
    Middlegame-weighted.
    """
    phase = _phase(ctx.gs)
    targets = {(4, 3), (4, 4)} if ctx.is_white else {(3, 3), (3, 4)}

    # Build a lightweight control set from pseudo-legal moves (+ pawn diagonals always)
    control = set()
    for m in ctx.all_moves:
        pm = m.piece_moved[1]
        if pm == 'p':
            continue
        # normalize castle flag
        is_castle = getattr(m, 'is_castle_move', getattr(m, 'isCastleMove', False))
        if pm == 'K' and is_castle:
            continue
        control.add((m.end_row, m.end_col))

    pawn_dir = -1 if ctx.is_white else 1
    for (r, c) in ctx.piece_positions.get(ctx.own + 'p', ()):
        rr = r + pawn_dir
        if 0 <= rr < 8:
            if c - 1 >= 0: control.add((rr, c - 1))
            if c + 1 < 8: control.add((rr, c + 1))

    bonus = 0.07 * sum(1 for sq in targets if sq in control)
    return phase * min(bonus, 0.30)

# 7) Castled king bonus (MG-only)
def castling_score(ctx):
    """
    +0.40 pawn if king sits on the castled square (g/c-file), middlegame-weighted.
    """
    phase = _phase(ctx.gs)
    if ctx.is_white:
        kr, kc = ctx.gs.white_king_location
        castled = (kr == 7 and kc in (6, 2))
    else:
        kr, kc = ctx.gs.black_king_location
        castled = (kr == 0 and kc in (6, 2))
    return 0.40 * phase if castled else 0.0

# 8) Rooks on the 7th/2nd
def rook_seventh_rank_score(ctx):
    """
    +0.25 pawn per rook on the 7th (W row=1) / 2nd (B row=6), cap +0.50.
    """
    target = 1 if ctx.is_white else 6
    cnt = sum(1 for r, _ in ctx.piece_positions.get(ctx.own + 'R', ()) if r == target)
    return min(cnt * 0.25, 0.50)

# 9) Early queen development penalty (MG-weighted)
def early_queen_development_penalty(ctx):
    """
    If your queen moved before full move 10 (20 plies), apply −0.30 * phase.
    """
    phase = _phase(ctx.gs)
    ownq = ctx.own + 'Q'
    for ply, mv in enumerate(ctx.gs.move_log):
        if ply >= 20:      # 20 plies = 10 full moves
            break
        if mv.piece_moved == ownq:
            return -0.30 * phase
    return 0.0

# 10) Minor-piece development (middlegame-weighted)
def minor_piece_development_score(ctx):
    """
    +0.30 per own N/B that is OFF the back rank (cap +1.20), scaled by phase.
    """
    phase = _phase(ctx.gs)
    home = 7 if ctx.is_white else 0
    minors = list(ctx.piece_positions.get(ctx.own + 'N', ())) + \
             list(ctx.piece_positions.get(ctx.own + 'B', ()))
    cnt = sum(1 for (r, _c) in minors if r != home)
    return min(cnt * 0.30, 1.20) * phase

# 11) Castling urgency (carrot/stick, MG-only)
def castling_urgency_score(ctx):
    """
    +0.30 if already castled by FM ≤ 8, −0.35 if still uncastled after FM >= 16 (MG-weighted).
    """
    phase = _phase(ctx.gs)
    fm = ctx.full_moves
    if ctx.is_white:
        kr, kc = ctx.gs.white_king_location
        castled = (kr == 7 and kc in (6, 2))
    else:
        kr, kc = ctx.gs.black_king_location
        castled = (kr == 0 and kc in (6, 2))

    if castled and fm <= 8:
        return 0.30 * phase
    if not castled and fm >= 16:
        return -0.35 * phase
    return 0.0

# 12) Rook connection (MG-weighted)
def rook_connection_score(ctx):
    """
    +0.35 if two own rooks sit on the back rank with no pieces between (MG-weighted).
    """
    phase = _phase(ctx.gs)
    back = 7 if ctx.is_white else 0
    cols = [c for r, c in ctx.piece_positions.get(ctx.own + 'R', ()) if r == back]
    if len(cols) < 2:
        return 0.0
    a, b = min(cols), max(cols)
    row = ctx.gs.board[back]
    for c in range(a + 1, b):
        if row[c] != '--':
            return 0.0
    return 0.35 * phase

# 13) Central pawn duo (MG-weighted)
def central_pawn_duo_score(ctx):
    """
    +0.25 for a pawn duo on d4+e4 (W) / d5+e5 (B), MG-weighted.
    """
    phase = _phase(ctx.gs)
    pos = set(ctx.piece_positions.get(ctx.own + 'p', ()))
    targets = {(4, 3), (4, 4)} if ctx.is_white else {(3, 3), (3, 4)}
    return (0.25 * phase) if targets.issubset(pos) else 0.0

# 14) King-move retention (discourage early wandering if not castled later)
def king_move_retention_score(ctx):
    """
    −0.25 if the king made a non-castling move and is NOT castled now (MG-weighted).
    """
    phase = _phase(ctx.gs)
    ownk = ctx.own + 'K'
    castled_now = (
        (ctx.gs.white_king_location in ((7, 6), (7, 2)))
        if ctx.is_white else
        (ctx.gs.black_king_location in ((0, 6), (0, 2)))
    )
    for mv in ctx.move_log:
        if mv.piece_moved == ownk:
            is_castle = getattr(mv, 'is_castle_move', getattr(mv, 'isCastleMove', False))
            if not is_castle and not castled_now:
                return -0.25 * phase
            break
    return 0.0

# 15) Queen centre exposure (MG-weighted)
def queen_exposure_penalty(ctx):
    """
    −0.20 per central square (d4/e4/d5/e5) where our queen currently sits
    AND that square is attacked by the opponent (MG-weighted).
    """
    phase = _phase(ctx.gs)
    q_squares = ctx.piece_positions.get(ctx.own + 'Q', ())
    if not q_squares:
        return 0.0

    opp_is_white = (not ctx.is_white)
    centres = ((4, 3), (4, 4), (3, 3), (3, 4))

    pen = 0.0
    for (r, c) in q_squares:
        if (r, c) in centres:
            if ctx.gs.is_square_attacked_bb(r*8 + c, by_white=opp_is_white):
                pen += 0.20
    return -pen * phase

# 16) Queen-premature release (if queen moves before minors are out; MG)
def queen_premature_release_penalty(ctx):
    """
    Penalise if the queen moves before N/B leave home squares.
    −0.25 per undeveloped home minor, only if the first queen move happens within 14 plies.
    Middlegame-weighted.
    """
    phase = _phase(ctx.gs)
    own = ctx.own
    ownQ = own + 'Q'
    home = 7 if ctx.is_white else 0
    home_squares = {(home,1), (home,6), (home,2), (home,5)}  # Nb,Ng,Bc,Bf

    # index (ply) of first queen move by this side
    first_q_idx = None
    for i, mv in enumerate(ctx.move_log):
        if mv.piece_moved == ownQ:
            first_q_idx = i
            break
    if first_q_idx is None or first_q_idx >= 16:
        return 0.0

    # which home squares were vacated by own minors BEFORE that move?
    vacated = set()
    for mv in ctx.move_log[:first_q_idx]:
        if mv.piece_moved[0] == own and (mv.start_row, mv.start_col) in home_squares:
            vacated.add((mv.start_row, mv.start_col))

    undeveloped = len(home_squares - vacated)
    return (-0.25 * undeveloped) * phase

# 17) Endgame king centralisation (EG-only)
def king_centralisation_score(ctx):
    """
    +0.10 per central square (d4,e4,d5,e5) that your king controls,
    cap +0.50 (EG only).
    """
    if not ctx.small_endgame:
        return 0.0
    kr, kc = ctx.gs.white_king_location if ctx.is_white else ctx.gs.black_king_location
    central = ((3,3),(3,4),(4,3),(4,4))
    cnt = 0
    for r, c in central:
        if max(abs(r - kr), abs(c - kc)) == 1:  # king controls 1-step
            cnt += 1
    return min(cnt * 0.10, 0.50)

# 18) King opposition (EG-only)
def king_opposition_score(ctx):
    """
    +0.20 if kings oppose and opponent to move, else +0.10 (EG only).
    """
    if not ctx.small_endgame:
        return 0.0
    wk = ctx.gs.white_king_location
    bk = ctx.gs.black_king_location
    has_opp = (wk[0] == bk[0] and abs(wk[1]-bk[1]) == 2) or \
              (wk[1] == bk[1] and abs(wk[0]-bk[0]) == 2)
    if not has_opp:
        return 0.0
    opp_to_move = (ctx.gs.white_to_move != ctx.is_white)
    return 0.20 if opp_to_move else 0.10

# 19) King tropism (MG-heavy → early EG)
def king_tropism_score(ctx):
    """
    Reward pieces that can move closer to the enemy king.
    For each own non-king piece, take its single best move
    that lands closest to the enemy king.
    Weighted by piece type, capped at +0.25 and scaled by phase (MG-heavy).
    """
    phase = _phase(ctx.gs)
    if phase <= 0.0:
        return 0.0

    # enemy king square
    ekr, ekc = (ctx.gs.black_king_location if ctx.is_white else ctx.gs.white_king_location)

    # piece-type weights
    w = {'Q': 1.00, 'R': 0.75, 'B': 0.65, 'N': 0.70, 'p': 0.35}

    # take ONE best contribution per piece
    best_by_piece = {}
    for m in ctx.all_moves:
        t = m.piece_moved[1]
        if t == 'K' or t not in w:
            continue
        d = abs(m.end_row - ekr) + abs(m.end_col - ekc)  # Manhattan distance
        if d > 4:
            continue
        contrib = w[t] * (0.02 / (1 + d))
        pid = (m.start_row, m.start_col)   # identity of the moving piece
        if contrib > best_by_piece.get(pid, 0.0):
            best_by_piece[pid] = contrib

    base = sum(best_by_piece.values())
    return min(base, 0.25) * phase

# 20) Knight outpost (MG-heavy → early EG)
def knight_outpost_score(ctx):
    """
    Knight outpost on c/d/e/f 4–5 (from White’s perspective),
    supported by own pawn and cannot be chased by enemy pawn.
    +0.20 MG → +0.10 EG per outpost.
    """
    phase = _phase(ctx.gs)
    if phase <= 0.0:
        return 0.0

    target_rows = {3, 4}
    target_cols = {2, 3, 4, 5}  # c,d,e,f files

    ownN = ctx.own + 'N'
    ownp = ctx.own + 'p'
    oppp = ctx.opp + 'p'
    board = ctx.gs.board

    def supported_by_pawn(r, c):
        rr = r + (1 if ctx.is_white else -1)
        if 0 <= rr < 8:
            return ((c > 0 and board[rr][c-1] == ownp) or
                    (c < 7 and board[rr][c+1] == ownp))
        return False

    def can_be_chased(r, c):
        if ctx.is_white:
            rows_ok = range(0, r)
        else:
            rows_ok = range(r+1, 8)
        files = ([c-1] if c > 0 else []) + ([c+1] if c < 7 else [])
        for cc in files:
            for rr in rows_ok:
                if board[rr][cc] == oppp:
                    return True
        return False

    bonus = 0.0
    for (r, c) in ctx.piece_positions.get(ownN, ()):
        if r in target_rows and c in target_cols:
            if supported_by_pawn(r, c) and not can_be_chased(r, c):
                bonus += 0.10 + 0.10 * phase  # 0.20 MG → 0.10 EG
    return bonus

# 21) Bad bishop penalty (MG-only)
def bad_bishop_penalty(ctx):
    """
    Penalize if bishop’s color matches majority color of fixed own pawns.
    Fixed pawn = pawn locked by enemy pawn in front.
    Stronger penalty now: −0.15 × phase (MG-only).
    """
    phase = _phase(ctx.gs)
    if phase <= 0.0:
        return 0.0

    ownp = ctx.own + 'p'
    oppp = ctx.opp + 'p'
    board = ctx.gs.board

    fixed_light = fixed_dark = 0
    direction = -1 if ctx.is_white else 1
    for (r, c) in ctx.piece_positions.get(ownp, ()):
        rr = r + direction
        if 0 <= rr < 8 and board[rr][c] == oppp:  # pawn lock
            if (r + c) % 2 == 0:
                fixed_light += 1
            else:
                fixed_dark += 1

    total_fixed = fixed_light + fixed_dark
    if total_fixed == 0:
        return 0.0

    majority_color = 0 if fixed_light >= fixed_dark else 1
    penalty = 0.0
    for (r, c) in ctx.piece_positions.get(ctx.own + 'B', ()):
        if (r + c) % 2 == majority_color:
            penalty -= 0.15 * phase  # Stronger than before

    return penalty

# 22) King wing pawn weakening penalty (MG-heavy)
def king_wing_pawn_weakening_penalty(ctx):
    """
    Penalise early f/g-pawn pushes while king still on e1/e8 and uncastled.
    Middlegame-weighted. Max about −0.30 pawn.
    """
    phase = _phase(ctx.gs)
    if phase <= 0.0:
        return 0.0

    board = ctx.gs.board
    is_w = ctx.is_white
    home_row = 7 if is_w else 0
    king_now = ctx.gs.white_king_location if is_w else ctx.gs.black_king_location
    castled = (king_now == (home_row, 6)) or (king_now == (home_row, 2))

    if king_now != (home_row, 4) or castled:
        return 0.0

    fp_home = (6, 5) if is_w else (1, 5)
    gp_home = (6, 6) if is_w else (1, 6)
    ownp = ctx.own + 'p'

    pen = 0.0
    if board[fp_home[0]][fp_home[1]] != ownp:
        pen -= 0.25
    if board[gp_home[0]][gp_home[1]] != ownp:
        pen -= 0.20

    return max(pen, -0.40) * phase

# 23) Uncastled open center penalty (MG-heavy)
def uncastled_open_center_penalty(ctx):
    """
    Penalize king on e1/e8 if d/e files are open or semi-open.
    −0.16 open, −0.10 semi. Middlegame-weighted.
    """
    gs = ctx.gs
    phase = _phase(gs)
    is_w = ctx.is_white
    kr, kc = (gs.white_king_location if is_w else gs.black_king_location)
    home_row = 7 if is_w else 0
    if (kr, kc) != (home_row, 4):
        return 0.0

    def file_state(file_idx):
        filesq = [gs.board[r][file_idx] for r in range(8)]
        ownp   = ('w' if is_w else 'b') + 'p'
        anyp   = any(sq.endswith('p') for sq in filesq if sq != '--')
        own_on = any(sq == ownp for sq in filesq)
        if not anyp: return 'open'
        if not own_on: return 'semi'
        return 'closed'

    pen = 0.0
    for f in (3, 4):  # d,e
        st = file_state(f)
        if st == 'semi': pen -= 0.10
        elif st == 'open': pen -= 0.16
    return phase * pen

# 24) Uncastled queen on board penalty (MG)
def uncastled_queen_on_board_penalty(ctx):
    """
    Mild MG penalty for not castling while both queens remain.
    Slightly stronger (−0.15 max) than before.
    """
    gs = ctx.gs
    phase = _phase(gs)
    if ctx.gs.bitboards['wQ'] == 0 or ctx.gs.bitboards['bQ'] == 0:
        return 0.0

    is_w = ctx.is_white
    kr, kc = (gs.white_king_location if is_w else gs.black_king_location)
    home_row = 7 if is_w else 0
    if (kr, kc) in ((home_row, 6), (home_row, 2)):
        return 0.0

    fm = 1 + sum(1 for m in gs.move_log if m.piece_moved[0] == 'b')
    late = max(0.0, min(1.0, (14 - fm) / 14.0))
    return -0.15 * phase * late

# 25) Early BxN without damage penalty (MG-heavy)
def early_BxN_without_damage_penalty(ctx):
    """
    Penalize giving up bishop for knight before ~FM10 unless
    it doubled enemy pawns on c–f files.
    """
    gs = ctx.gs
    phase = _phase(gs)
    fm = 1 + sum(1 for m in gs.move_log if m.piece_moved[0] == 'b')
    if fm > 14 or phase < 0.5:
        return 0.0
    if not gs.move_log:
        return 0.0
    mv = gs.move_log[-1]

    if mv.piece_moved[0] != ctx.own or mv.piece_moved[1] != 'B':
        return 0.0
    if not mv.piece_captured or not mv.piece_captured.endswith('N'):
        return 0.0

    file_c = mv.end_col
    enemy = 'b' if ctx.is_white else 'w'
    cnt = sum(1 for r in range(8) if gs.board[r][file_c] == enemy+'p')
    if cnt < 2:
        return -0.30 * phase
    return 0.0

# 26) Simplify when ahead (stronger EG bias)
def simplify_when_ahead_score(ctx):
    """
    If up material by ≥1.0 pawn, prefer fewer enemy pieces.
    Now much stronger: +0.15 instead of +0.05 scaling.
    """
    mat_adv = ctx.material_adv
    if mat_adv < 1.0:
        return 0.0
    gs = ctx.gs
    enemy = 'b' if ctx.is_white else 'w'
    enemy_minors = gs.bitboards[enemy+'N'].bit_count() + gs.bitboards[enemy+'B'].bit_count()
    enemy_rooks  = gs.bitboards[enemy+'R'].bit_count()
    pieces_left = enemy_minors + enemy_rooks
    eg = 1.0 - _phase(gs)
    return +0.15 * (4 - pieces_left) * min(2.0, mat_adv) * eg

# 27) Kaufman pawncount piece tweak
def kaufman_pawncount_piece_tweak(ctx):
    """
    Kaufman: N↑ by 1/16, R↓ by 1/8 per pawn above 5.
    Opposite if below 5. EG-weighted.
    """
    np = len(ctx.piece_positions.get(ctx.own + 'p', ()))
    delta = np - 5
    if delta == 0:
        return 0.0
    nN = len(ctx.piece_positions.get(ctx.own + 'N', ()))
    nR = len(ctx.piece_positions.get(ctx.own + 'R', ()))
    eg = 1.0 - _phase(ctx.gs)
    return eg * (0.0625 * delta * nN - 0.125 * delta * nR)

# 28) Kaufman B vs N tweak
def kaufman_B_vs_N_pawncount_tweak(ctx):
    """
    Without bishop pair:
    - With ≥6 pawns: knights stronger (−0.125 per bishop vs knight).
    - With ≤4 pawns: bishops stronger (+0.125 per).
    """
    nb = len(ctx.piece_positions.get(ctx.own + 'B', ()))
    if nb >= 2:
        return 0.0
    nn = len(ctx.piece_positions.get(ctx.own + 'N', ()))
    diff = nb - nn
    if diff == 0:
        return 0.0
    np = len(ctx.piece_positions.get(ctx.own + 'p', ()))
    if np >= 6:
        return -0.125 * diff
    if np <= 4:
        return +0.125 * diff
    return 0.0

# 29) Exchange context tweak (Larry Kaufman style, EG-weighted)
def kaufman_ex_context_correction(ctx):
    """
    Exchange value context:
      - less valuable with many majors on (both Qs on & ≥3 rooks total): −0.25 per exchange unit
      - more valuable with majors off (no Qs & ≤2 rooks total): +0.25 per exchange unit
      - tiny synergy if opponent (down-exchange side) has bishop pair: −0.10 per unit
      - pawn-count slope: more pawns → exchange a bit less valuable for rook side
      - clamped ±0.50 pawns
    Returns pawns (from ctx side).
    """
    own, opp = ctx.own, ctx.opp
    nR_own = len(ctx.piece_positions.get(own + 'R', ()))
    nR_opp = len(ctx.piece_positions.get(opp + 'R', ()))
    nMin_own = len(ctx.piece_positions.get(own + 'N', ())) + len(ctx.piece_positions.get(own + 'B', ()))
    nMin_opp = len(ctx.piece_positions.get(opp + 'N', ())) + len(ctx.piece_positions.get(opp + 'B', ()))
    exch_units = (nR_own - nR_opp) - (nMin_own - nMin_opp)  # + if we're "up the exchange"
    if exch_units == 0:
        return 0.0

    bb = ctx.gs.bitboards
    queens_on = (bb['wQ'] != 0) and (bb['bQ'] != 0)
    total_rooks = bb['wR'].bit_count() + bb['bR'].bit_count()

    corr = 0.0
    if queens_on and total_rooks >= 3:
        corr -= 0.25 * exch_units
    elif (bb['wQ'] == 0 and bb['bQ'] == 0) and total_rooks <= 2:
        corr += 0.25 * exch_units

    # Opponent (down-exchange side) has bishop pair → shave our edge
    if exch_units > 0 and len(ctx.piece_positions.get(opp + 'B', ())) >= 2:
        corr -= 0.10 * exch_units

    # Pawn-count influence
    own_p = len(ctx.piece_positions.get(own + 'p', ()))
    opp_p = len(ctx.piece_positions.get(opp + 'p', ()))
    avg_p = 0.5 * (own_p + opp_p)
    corr += (-0.03 * (avg_p - 5)) * exch_units  # ≈0.15 swing from 10→0 pawns

    return max(-0.50, min(0.50, corr))

# 30) Q vs 2R context tweak (Larry Kaufman style, EG-weighted)
def kaufman_q_vs_2r_correction(ctx):
    """
    Q vs 2R context:
      - queen better on crowded boards (many minors)
      - rooks better with few pawns (open files)
    Returns pawns (from ctx side).
    """
    own, opp = ctx.own, ctx.opp
    ownQ = len(ctx.piece_positions.get(own + 'Q', ()))
    oppQ = len(ctx.piece_positions.get(opp + 'Q', ()))
    ownR = len(ctx.piece_positions.get(own + 'R', ()))
    oppR = len(ctx.piece_positions.get(opp + 'R', ()))

    # total minors on board
    minors_total = (len(ctx.piece_positions.get('wN', ())) + len(ctx.piece_positions.get('wB', ())) +
                    len(ctx.piece_positions.get('bN', ())) + len(ctx.piece_positions.get('bB', ())))

    own_p = len(ctx.piece_positions.get(own + 'p', ()))
    opp_p = len(ctx.piece_positions.get(opp + 'p', ()))
    few_pawns = (own_p <= 4 and opp_p <= 4)
    many_minors = (minors_total >= 4)

    corr = 0.0
    if ownQ >= 1 and oppQ == 0 and oppR >= 2:
        if many_minors: corr += 0.25
        if few_pawns:   corr -= 0.25
    elif ownR >= 2 and ownQ == 0 and oppQ >= 1:
        if many_minors: corr -= 0.25
        if few_pawns:   corr += 0.25
    return corr

# 31) Rook pawn discount (Kaufman ~15% weaker on average)
def rook_pawn_discount_score(ctx):
    """
    Light discount for a/h pawns (Kaufman ~15% weaker on average).
    We *reduce* the penalty if the rook pawn is far advanced, supported by another pawn,
    or a passed pawn (those cases are often quite strong).
    Applies in both phases (slightly more in EG).
    """
    gs = ctx.gs
    phase = _phase(gs)
    board = gs.board
    ownp = ctx.own + 'p'
    is_w = ctx.is_white

    pawns = ctx.piece_positions.get(ownp, ())
    if not pawns:
        return 0.0

    total = 0.0
    for (r, c) in pawns:
        if c not in (0, 7):   # only a/h files
            continue

        # rank from side’s POV: 1..8
        rank = (8 - r) if is_w else (r + 1)

        # support by a neighbor pawn one rank behind (diagonal)
        back = 1 if is_w else -1
        supported = False
        br = r + back
        if 0 <= br < 8:
            if (c > 0 and board[br][c-1] == ownp) or (c < 7 and board[br][c+1] == ownp):
                supported = True

        # is passed? (no enemy pawns ahead on same/adjacent files)
        oppp = ctx.opp + 'p'
        fwd = -1 if is_w else 1
        rr = r + fwd
        blocked = False
        while 0 <= rr < 8:
            if board[rr][c] == oppp or (c and board[rr][c-1] == oppp) or (c < 7 and board[rr][c+1] == oppp):
                blocked = True
                break
            rr += fwd
        is_passed = not blocked

        # base discount ~0.15 pawn, slightly more in EG
        mg_part = 0.06 * phase
        eg_part = 0.09 * (1.0 - phase)
        pen = mg_part + eg_part

        # reduce penalty if far advanced / supported / passed
        if rank >= 6:         # 6th/7th from our POV
            pen *= 0.5
        if supported:
            pen *= 0.7
        if is_passed:
            pen *= 0.7

        total -= pen

    return total

# 32) Rook cutting off enemy king (EG-weighted)
def rook_cutoff_king_score(ctx):
    """
    In queenless positions, reward a rook that cuts the enemy king off
    along a rank or file with no pieces in between. EG-weighted.
    """
    gs = ctx.gs
    # Need queenless to avoid false positives in attacks
    if gs.bitboards['wQ'] != 0 or gs.bitboards['bQ'] != 0:
        return 0.0

    board = gs.board
    (ekr, ekc) = gs.black_king_location if ctx.is_white else gs.white_king_location
    bonus = 0.0
    for (rr, cc) in ctx.piece_positions.get(ctx.own + 'R', ()):
        if rr == ekr:
            # same rank: clear path between rook and king
            a, b = sorted((cc, ekc))
            if all(board[rr][c] == '--' for c in range(a+1, b)):
                bonus += 0.20  # was 0.10 → doubled
        if cc == ekc:
            # same file
            a, b = sorted((rr, ekr))
            if all(board[r][cc] == '--' for r in range(a+1, b)):
                bonus += 0.25  # was 0.12 → doubled
    # EG-weighted only, higher cap
    return (1.0 - _phase(gs)) * min(bonus, 0.40)

# 33) Rook activity in endgame (EG-only)
def rook_activity_endgame_score(ctx):
    """
    Endgame-only, bonus for rook mobility without generating moves.
    Count empty squares reachable along rook rays. Cheap and FAST-safe.
    """
    if not ctx.small_endgame:
        return 0.0
    board = ctx.gs.board
    rooks = ctx.piece_positions.get(ctx.own + 'R', ())
    if not rooks:
        return 0.0

    total = 0
    for (r, c) in rooks:
        for dr, dc in ((1,0),(-1,0),(0,1),(0,-1)):
            rr, cc = r + dr, c + dc
            while 0 <= rr < 8 and 0 <= cc < 8:
                if board[rr][cc] != '--':
                    break
                total += 1
                rr += dr; cc += dc

    # ~0.01 pawn per square, cap at 0.30 (was 0.006 cap 0.14)
    return min(total * 0.01, 0.30)

def _is_egish(ctx):
    """EG-ish if small_endgame flag or phase very low."""
    return ctx.small_endgame or (_phase(ctx.gs) <= 0.35)

# 34) King centralisation in EG
def king_center_distance_score(ctx):
    """
    EG-only: pull king toward the 4 central squares (d4,e4,d5,e5).
    +0.20 at center, tapering ~0.05 per Chebyshev step (to 0 by dist ≥4).
    """
    if not _is_egish(ctx):
        return 0.0
    kr, kc = ctx.gs.white_king_location if ctx.is_white else ctx.gs.black_king_location
    centres = ((3,3),(3,4),(4,3),(4,4))
    d = min(max(abs(kr-r), abs(kc-c)) for (r,c) in centres)
    return max(0.0, 0.20 - 0.05 * d)

# 35) King edge penalty in EG
def king_edge_penalty_score(ctx):
    """
    EG-only: push king off the edge/corner.
    −0.15 on edge, −0.25 in corner.
    """
    if not _is_egish(ctx):
        return 0.0
    kr, kc = ctx.gs.white_king_location if ctx.is_white else ctx.gs.black_king_location
    on_edge = (kr in (0,7)) or (kc in (0,7))
    in_corner = (kr in (0,7)) and (kc in (0,7))
    return -0.25 if in_corner else (-0.15 if on_edge else 0.0)

# 36) King support of own passed pawn in EG
def king_support_own_passed_score(ctx):
    """
    EG-only: encourage king to shepherd *own* passed pawn.
    Up to +0.25 when adjacent, −0.04 per step away (Manhattan distance).
    """
    if not _is_egish(ctx):
        return 0.0
    gs   = ctx.gs
    board= gs.board
    ownp = ctx.own + 'p'
    oppp = ctx.opp + 'p'
    is_w = ctx.is_white
    fwd  = -1 if is_w else 1

    # find own passers
    passers = []
    for (r,c) in ctx.piece_positions.get(ownp, ()):
        rr = r + fwd
        blocked = False
        while 0 <= rr < 8:
            if board[rr][c] == oppp or (c>0 and board[rr][c-1]==oppp) or (c<7 and board[rr][c+1]==oppp):
                blocked = True
                break
            rr += fwd
        if not blocked:
            passers.append((r,c))
    if not passers:
        return 0.0

    kr,kc = gs.white_king_location if is_w else gs.black_king_location

    # distance to the square in front of our “best” passer
    best = 999
    for (r,c) in passers:
        fr, fc = r + fwd, c
        if 0 <= fr < 8:
            d = abs(kr - fr) + abs(kc - fc)
            if d < best: best = d

    # +0.25 when adjacent, −0.04 per step; floor 0
    return max(0.0, 0.25 - 0.04 * best)

# 37) Anti-shuffling / Progress heuristic
def anti_shuffling_score(ctx):
    """
    If clearly ahead (eval > +1.5 pawns) but no pawn moves/captures
    in last 8 plies → apply small penalty. Encourages progress in won games.
    """
    if getattr(ctx, 'eval', 0.0) < 1.5:  # only if winning
        return 0.0
    # Require phase not to be opening
    if _phase(ctx.gs) > 0.6:
        return 0.0

    # Track recent moves (depends on your move-history logic)
    no_progress = getattr(ctx.gs, 'no_progress_plies', 0)
    if no_progress >= 8:
        # −0.05 per 2 plies without progress, cap −0.25
        return -min(0.25, 0.05 * (no_progress // 2))
    return 0.0

# 38) Pawn push urgency when winning
def pawn_push_urgency_score(ctx):
    """
    If winning (>+1.5 eval) and owning a passed pawn,
    encourage advancing it (unless blocked by strong enemy).
    """
    if getattr(ctx, 'eval', 0.0) < 1.5 or not _is_egish(ctx):
        return 0.0

    gs = ctx.gs
    board = gs.board
    ownp = ctx.own + 'p'
    oppp = ctx.opp + 'p'
    is_w = ctx.is_white
    fwd  = -1 if is_w else 1

    bonus = 0.0
    for (r,c) in ctx.piece_positions.get(ownp, ()):
        # Quick test for passer
        rr = r + fwd
        blocked = False
        while 0 <= rr < 8:
            if board[rr][c] == oppp or (c>0 and board[rr][c-1]==oppp) or (c<7 and board[rr][c+1]==oppp):
                blocked = True
                break
            rr += fwd
        if blocked:
            continue

        # rank-based urgency
        rank = (8 - r) if is_w else (r + 1)
        bonus += 0.04 * (rank-1)  # more advanced → higher bonus

    # Cap urgency bonus
    return min(bonus, 0.40)

# 39) Phase-aware evaluation helper (utility)
def game_phase_factor(ctx):
    """
    Returns a factor in [0,1] representing phase of the game:
    1.0 → pure opening, 0.0 → pure endgame.
    Uses material-based tapering (like Stockfish).
    """
    return _phase(ctx.gs)  # if you already have _phase, alias it here


def eval_cache_clear():
    """Call on reset/new game (optional)."""
    EVAL_CACHE.clear()

# -------------------- Feature wiring --------------------
def _collect_features(names):
    """Resolve feature names → callables that actually exist (skips missing)."""
    g = globals()
    out = []
    for n in names:
        fn = g.get(n)
        if callable(fn):
            out.append(fn)
    return tuple(out)

# Keep these light → used in FAST and FULL
_FAST_FEATURES = _collect_features([
    'king_safety_score',                # 2         
    'pawn_structure_score',             # 3  
    'bishop_pair_score',                # 4
    'castling_score',                   # 7
    'early_queen_development_penalty',  # 9
    'minor_piece_development_score',    # 10
    'castling_urgency_score',           # 11
    'king_move_retention_score',        # 14
    'queen_premature_release_penalty',  # 16
    'king_centralisation_score',        # 17
    'king_opposition_score',            # 18  
    'king_wing_pawn_weakening_penalty', # 22  
    'uncastled_open_center_penalty',    # 23
    'uncastled_queen_on_board_penalty', # 24
    'simplify_when_ahead_score',        # 26
    'kaufman_pawncount_piece_tweak',    # 27  
    'kaufman_ex_context_correction',    # 29
    'kaufman_q_vs_2r_correction',       # 30  
    'rook_pawn_discount_score',         # 31  
    'rook_cutoff_king_score',           # 32  
    'rook_activity_endgame_score',      # 33
    'king_center_distance_score',       # 34
    'king_edge_penalty_score',          # 35
    'king_support_own_passed_score',    # 36
    'anti_shuffling_score',             # 37
    'pawn_push_urgency_score',          # 38
])

# --- FULL (extra/richer; DO NOT include the ones also in FAST) ---
_FULL_ONLY_FEATURES = _collect_features([
    'mobility_score',                   # 1
    'rook_open_file_score',             # 5
    'center_control_score',             # 6
    'rook_seventh_rank_score',          # 8
    'rook_connection_score',            # 12
    'central_pawn_duo_score',           # 13
    'queen_exposure_penalty',           # 15
    'king_tropism_score',               # 19
    'knight_outpost_score',             # 20
    'bad_bishop_penalty',               # 21 
    'early_BxN_without_damage_penalty', # 25
    'kaufman_B_vs_N_pawncount_tweak',   # 28
    # Utility like game_phase_factor (#39) is not a feature → leave out
])

# -------------------- Main evaluator (pawns) --------------------
def scoreBoard(gs, fast=False):
    """
    Two-tier static evaluator (white-positive, in pawns).
    Base = gs.current_eval (material + PST).
    FAST: cheap core features only.
    FULL: FAST + richer features.

    Note: cache key includes a coarse epoch bucket (early/mid/late)
    to remain safe for history-sensitive features that look at move_log.
    """
    # --- History-safe cache key (epoch buckets) ---
    fm = 1 + sum(1 for m in gs.move_log if m.piece_moved[0] == 'b')
    epoch = 0 if fm <= 8 else (1 if fm <= 14 else 2)  # early / mid / late
    key = (EVAL_VERSION, gs.zobrist_key, bool(fast), epoch)

    cached = EVAL_CACHE.get(key)
    if cached is not None:
        return cached

    if 'PROFILE' in globals():
        PROFILE["score_calls_fast" if fast else "score_calls_full"] += 1

    # Base (white-positive)
    score = float(gs.current_eval)

    # Build contexts (light/heavy chosen upstream via `fast`)
    wctx = get_eval_context(gs, True,  fast=fast)
    bctx = get_eval_context(gs, False, fast=fast)

    # Let features see the *current* total (start from base)
    wctx.eval = score
    bctx.eval = score

    def _sum_feats(feats, ctx):
        return sum(f(ctx) for f in feats)

    # FAST layer
    fast_w = _sum_feats(_FAST_FEATURES, wctx)
    fast_b = _sum_feats(_FAST_FEATURES, bctx)
    score += fast_w - fast_b

    # Update eval snapshot after FAST layer
    wctx.eval = score
    bctx.eval = score

    # FULL layer (if enabled)
    if not fast:
        full_w = _sum_feats(_FULL_ONLY_FEATURES, wctx)
        full_b = _sum_feats(_FULL_ONLY_FEATURES, bctx)
        score += full_w - full_b

        # Final snapshot (after FULL)
        wctx.eval = score
        bctx.eval = score

    EVAL_CACHE[key] = score
    return score