TimeManager

Pure, platform-agnostic time manager for the bots' game clock.

This is layer (a) of time control: it maps a ClockState to a per-turn budget in milliseconds. Layer (b) — the actual search under a deadline — stays untouched in TimeBudgetedSearch; the caller turns the budget returned here into a System.nanoTime deadline. Keeping the manager here (rather than in each consumer) means the JS API, the offline arena, and any future server share one tested implementation instead of re-inventing it.

The policy is pure Long/Double math — no clocks, no randomness — so it is identical on the JVM and Scala.js and is exhaustively unit-testable without wall-clock flakiness (see TimeBudgetedSearch for why the search path cannot be).

How the budget is derived

From the spendable time (remaining minus a safety reserve) and an estimated moves-to-go:

reserve = max(ReserveFloorMs, ReserveFraction * remaining)
spendable = max(0, remaining - reserve)
target = increment + spendable / movesToGo // increment == 0 ⇒ sudden death

then clamped to [MinThinkMs, hardCap] where hardCap = MaxFraction * remaining, with a tighter panic clamp once spendable falls below TimeManager.PanicThresholdMs.

Behaviour across controls

• Sudden death (1+0): target ≈ spendable / movesToGo, decaying as the clock drains; near zero the bot blitzes legal moves (panic floor) instead of flagging.
• Fischer (10+10): the increment term keeps per-turn time high while the clock is healthy. As remaining shrinks the hardCap (a fraction of the remaining clock) takes over and throttles the target below the increment — deliberately conservative, since the increment is only credited after the turn completes, so a bot that overspends now can still flag before it is refunded. This trades a little time-utilisation for a guarantee of never losing on time; the constants are tunable.