Upload folder using huggingface_hub

browser/entry.js

@@ -3607,6 +3607,44 @@ function moveToIndex(fromName, toName, promoLetter) {
 //     algorithm that isn't finalized yet would mean re-porting it again
 //     later. Default behavior here (plain PUCT) matches Python's default
 //     config exactly; nothing is being weakened, just left for later.
+const ADAPTIVE_BATCH_SAFETY = 1.25;
+const ADAPTIVE_BATCH_GUARD_MS = 2;
+const ADAPTIVE_BATCH_EMA_ALPHA = 0.25;
+function clockMs() {
+    if (typeof performance !== "undefined" && typeof performance.now === "function") {
+        return performance.now();
+    }
+    return Date.now();
+}
+/**
+ * Choose the largest halving batch that conservatively fits the remaining
+ * budget. `referenceBatchMs` is an observed duration for
+ * `referenceBatchSize`; lower sizes use a linear estimate plus safety margin.
+ * A null reference preserves the configured batch for cold-start behavior.
+ */
+function adaptiveBatchSizeForBudget(maxBatchSize, remainingMs, referenceBatchMs, referenceBatchSize = maxBatchSize) {
+    if (!Number.isInteger(maxBatchSize) || maxBatchSize <= 0)
+        return 0;
+    if (remainingMs === Infinity)
+        return maxBatchSize;
+    if (!Number.isFinite(remainingMs) || remainingMs <= 0)
+        return 0;
+    if (!Number.isFinite(referenceBatchMs)
+        || referenceBatchMs <= 0
+        || !Number.isInteger(referenceBatchSize)
+        || referenceBatchSize <= 0) {
+        return maxBatchSize;
+    }
+    for (let candidate = maxBatchSize; candidate >= 1; candidate = Math.floor(candidate / 2)) {
+        const estimatedMs = referenceBatchMs * (candidate / referenceBatchSize);
+        const requiredMs = estimatedMs * ADAPTIVE_BATCH_SAFETY + ADAPTIVE_BATCH_GUARD_MS;
+        if (remainingMs >= requiredMs)
+            return candidate;
+        if (candidate === 1)
+            break;
+    }
+    return 0;
+}
 class MCTSConfig {
     constructor({ nSimulations = 800, timeBudgetMs = null, // anytime: stop on whichever hits first
     cPuct = 1.5, batchSize = 1, // >1 enables virtual-loss leaf batching
@@ -3647,6 +3685,19 @@ function wdlToScore(wdlProbs) {
 function isDraw(chess) {
     return chess.isGameOver() && !chess.isCheckmate();
 }
+function rootSnapshot(root, simCount) {
+    return {
+        simCount,
+        candidates: Array.from(root.children.values(), (edge) => ({
+            san: edge.san,
+            from: edge.from,
+            to: edge.to,
+            promotion: edge.promotion,
+            visits: edge.node.visitCount,
+            prior: edge.node.prior,
+        })),
+    };
+}
 class MCTS {
     /**
      * @param {{evaluateBatch(chessInstances): Promise<{policyLogits: Float32Array[], wdlLogits: Float32Array[]}>}} evaluator
@@ -3655,41 +3706,72 @@ class MCTS {
     constructor(evaluator, config) {
         this.evaluator = evaluator;
         this.config = config || new MCTSConfig();
+        this.batchDurationMs = null;
+        this.batchDurationSamples = 0;
     }
     /**
      * Run search from `chess`'s current position. Returns the winning move's
      * SAN string (the most-visited root child). Mutates `chess` internally
      * via move()/undo() during simulation but always leaves it at the
      * original position when it returns.
+     *
+     * `timeBudgetMs` (optional, second-argument object) overrides
+     * `this.config.timeBudgetMs` for this one call only -- lets a caller that
+     * creates one long-lived MCTS instance per game (entry.js does, so root
+     * statistics reset per move but the instance itself persists) still honor
+     * a per-move budget that can change move to move (e.g. a tournament
+     * runner's per-move time limit).
      */
-    async search(chess) {
+    async search(chess, { timeBudgetMs, onRootUpdate } = {}) {
         const cfg = this.config;
+        const effectiveTimeBudgetMs = timeBudgetMs !== undefined ? timeBudgetMs : cfg.timeBudgetMs;
         const root = new Node(1.0);
-        const startTime = Date.now();
+        const notifyRoot = (simCount) => {
+            if (typeof onRootUpdate !== "function" || root.children.size === 0)
+                return;
+            try {
+                onRootUpdate(rootSnapshot(root, simCount));
+            }
+            catch {
+                // Optional diagnostics must never change search behavior.
+            }
+        };
+        const startTime = clockMs();
         let sim = 0;
         if (cfg.batchSize <= 1) {
             while (sim < cfg.nSimulations) {
-                if (cfg.timeBudgetMs !== null && Date.now() - startTime >= cfg.timeBudgetMs) {
+                if (effectiveTimeBudgetMs !== null && clockMs() - startTime >= effectiveTimeBudgetMs) {
                     break;
                 }
                 await this._simulate(root, chess);
                 sim++;
+                if (sim === 1 || sim % 16 === 0)
+                    notifyRoot(sim);
             }
         }
         else {
             // Bootstrap root expansion exactly once, matching serial search.
-            if (sim < cfg.nSimulations && (cfg.timeBudgetMs === null || Date.now() - startTime < cfg.timeBudgetMs)) {
+            if (sim < cfg.nSimulations && (effectiveTimeBudgetMs === null || clockMs() - startTime < effectiveTimeBudgetMs)) {
                 const value = await this._expand(root, chess);
                 this._backup([root], value);
                 sim++;
+                notifyRoot(sim);
             }
             while (sim < cfg.nSimulations) {
-                if (cfg.timeBudgetMs !== null && Date.now() - startTime >= cfg.timeBudgetMs) {
+                if (effectiveTimeBudgetMs !== null && clockMs() - startTime >= effectiveTimeBudgetMs) {
                     break;
                 }
-                const roundBudget = Math.min(cfg.batchSize, cfg.nSimulations - sim);
-                const completed = await this._runBatchedRound(root, chess, roundBudget, startTime);
+                const maxRoundBudget = Math.min(cfg.batchSize, cfg.nSimulations - sim);
+                const remainingMs = effectiveTimeBudgetMs === null
+                    ? Infinity
+                    : effectiveTimeBudgetMs - (clockMs() - startTime);
+                const roundBudget = this._chooseAdaptiveBatchSize(remainingMs, maxRoundBudget);
+                if (roundBudget === 0)
+                    break;
+                const completed = await this._runBatchedRound(root, chess, roundBudget, startTime, effectiveTimeBudgetMs);
                 sim += completed;
+                if (completed > 0)
+                    notifyRoot(sim);
                 if (completed === 0)
                     break;
             }
@@ -3716,6 +3798,21 @@ class MCTS {
         }
         return bestEdge.san;
     }
+    _recordDefaultBatchTiming(elapsedMs) {
+        if (!Number.isFinite(elapsedMs) || elapsedMs <= 0)
+            return;
+        if (this.batchDurationMs === null) {
+            this.batchDurationMs = elapsedMs;
+        }
+        else {
+            this.batchDurationMs = ((1 - ADAPTIVE_BATCH_EMA_ALPHA) * this.batchDurationMs
+                + ADAPTIVE_BATCH_EMA_ALPHA * elapsedMs);
+        }
+        this.batchDurationSamples++;
+    }
+    _chooseAdaptiveBatchSize(remainingMs, maxBatchSize = this.config.batchSize) {
+        return adaptiveBatchSizeForBudget(maxBatchSize, remainingMs, this.batchDurationMs, this.config.batchSize);
+    }
     // -- internals -----------------------------------------------------
     async _simulate(root, chess) {
         let node = root;
@@ -3741,12 +3838,13 @@ class MCTS {
             chess.undo();
         }
     }
-    async _runBatchedRound(root, chess, roundBudget, startTime) {
+    async _runBatchedRound(root, chess, roundBudget, startTime, timeBudgetMs) {
+        const roundStart = clockMs();
         const pending = new Map();
         const order = [];
         let completed = 0;
         for (let i = 0; i < roundBudget; i++) {
-            if (this.config.timeBudgetMs !== null && Date.now() - startTime >= this.config.timeBudgetMs) {
+            if (timeBudgetMs !== null && clockMs() - startTime >= timeBudgetMs) {
                 break;
             }
             const result = this._selectLeafVL(root, chess);
@@ -3772,6 +3870,9 @@ class MCTS {
                 completed += this._finishFreshEntry(entries[i], policyLogits[i], wdlLogits[i]);
             }
         }
+        if (order.length === this.config.batchSize) {
+            this._recordDefaultBatchTiming(clockMs() - roundStart);
+        }
         return completed;
     }
     _selectLeafVL(root, chess) {
@@ -3949,18 +4050,40 @@ const OPENING_BOOK = Object.freeze({ "1nbqkbnr/1ppppppp/8/8/8/1P2P3/1BPP1PPP/rN1
 //
 // Contract (rules technical appendix, schema chess-gpt-package-v1):
 //   export async function loadPackage({ artifacts, config, ort })
-//     -> { newGame({ random }) -> { chooseMove({ history, legalMoves }) -> SAN,
+//     -> { newGame({ random }) -> { chooseMove({ history, legalMoves, moveTimeLimitMs }) -> SAN,
 //                                    dispose() },
 //          dispose() }
 //
+// moveTimeLimitMs (added to the rules 2026-07-31): the runner's wall-clock
+// budget in ms for this move. A submission MAY use it and MAY ignore it;
+// this one uses it to cap MCTS's per-move search so we stay under it (the
+// runner allows a 1.25x grace period before terminating the worker as a
+// loss, but that grace is not extra thinking time and must not be relied
+// on -- see MOVE_TIME_LIMIT_MARGIN below). Packages published before this
+// revision remain valid: the field is additive, and chooseMove falls back
+// to the fixed DEFAULT_TIME_BUDGET_MS/config.timeBudgetMs budget below
+// when it's absent (also how local tests/benchmarks that don't pass it
+// keep working unchanged).
+//
 // Because we only ever return a member of `legalMoves`, this can never lose
 // on an illegal/invalid move -- if anything above goes wrong for a specific
 // position, we fall back to legalMoves[0] rather than throw.
-// ~10s/move budget per the tournament rules; 9.2s leaves margin for
-// encoding/dispatch overhead around each simulation's model call.
-// Overridable via loadPackage's `config` (e.g. { timeBudgetMs: 500 } for
-// fast test iteration) -- see test_smoke.mjs.
+// Fallback budget when the runner doesn't supply moveTimeLimitMs on
+// chooseMove (older runner, or a local test/benchmark harness that omits
+// it -- see test_smoke.mjs). Also overridable via loadPackage's `config`
+// (e.g. { timeBudgetMs: 500 } for fast test iteration); config.timeBudgetMs
+// wins over this default but NOT over a real per-move moveTimeLimitMs,
+// which is the live constraint whenever the runner provides one.
 const DEFAULT_TIME_BUDGET_MS = 9200;
+// Fraction of the runner's per-move moveTimeLimitMs actually budgeted to
+// MCTS search, leaving margin for encoding/dispatch overhead around each
+// simulation's model call before the runner's own clock runs out. Matches
+// the historical 9.2s-of-10s margin (DEFAULT_TIME_BUDGET_MS above, from
+// when the budget was a fixed ~10s/move) so this doesn't change behavior
+// for the moveTimeLimitMs=10000 case. Deliberately stays inside
+// moveTimeLimitMs itself, not the runner's 1.25x grace period -- that
+// grace is for worker-teardown latency, not additional thinking time.
+const MOVE_TIME_LIMIT_MARGIN = 0.92;
 const MAX_SIMULATIONS = 100000; // effectively unbounded; time budget governs
 // Virtual-loss leaf batching (chessdb-4ru): a batchSize sweep (1/2/4/8/
 // 16/32) against the real model via onnxruntime-node
@@ -3981,9 +4104,153 @@ function emitEvent(onEvent, event) {
         // Diagnostics must never change engine behavior.
     }
 }
-function clockMs() {
+function entryClockMs() {
     return typeof performance !== "undefined" ? performance.now() : Date.now();
 }
+const MAX_CANDIDATES = 4;
+const MIN_REFRESH_MS = 150;
+const MAX_COMMANDS_PER_MOVE = 56;
+const ORDINARY_COMMAND_LIMIT = MAX_COMMANDS_PER_MOVE - 1;
+const CANDIDATE_FADE_MS = 900;
+const FINAL_FADE_MS = 1500;
+function selectCandidateArrows(snapshot, legalMoves) {
+    const legal = new Set(Array.isArray(legalMoves) ? legalMoves : []);
+    const candidates = Array.isArray(snapshot?.candidates) ? snapshot.candidates : [];
+    const ranked = candidates
+        .filter((candidate) => candidate && legal.has(candidate.san))
+        .sort((a, b) => {
+        const aVisits = Number.isFinite(a.visits) ? a.visits : 0;
+        const bVisits = Number.isFinite(b.visits) ? b.visits : 0;
+        const aHasVisits = aVisits > 0 ? 1 : 0;
+        const bHasVisits = bVisits > 0 ? 1 : 0;
+        return bHasVisits - aHasVisits
+            || bVisits - aVisits
+            || (Number.isFinite(b.prior) ? b.prior : 0) - (Number.isFinite(a.prior) ? a.prior : 0)
+            || String(a.san).localeCompare(String(b.san));
+    });
+    const selected = [];
+    const keys = new Set();
+    for (const candidate of ranked) {
+        if (typeof candidate.from !== "string" || typeof candidate.to !== "string")
+            continue;
+        const key = `${candidate.from}-${candidate.to}`;
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        selected.push({
+            san: candidate.san,
+            from: candidate.from,
+            to: candidate.to,
+        });
+        if (selected.length === MAX_CANDIDATES)
+            break;
+    }
+    return selected.map((candidate, rank) => ({
+        ...candidate,
+        intensity: selected.length > 1 ? 1 - 0.6 * rank / (selected.length - 1) : 1,
+    }));
+}
+function createThinkingDisplay(thinking) {
+    const emit = typeof thinking?.emit === "function" ? thinking.emit.bind(thinking) : null;
+    const displayed = new Map();
+    let ordinaryCommands = 0;
+    let lastUpdateAt = -Infinity;
+    const safeEmit = (command) => {
+        if (!emit)
+            return;
+        try {
+            emit(command);
+        }
+        catch {
+            // Display diagnostics must never change move selection.
+        }
+    };
+    return {
+        enabled: Boolean(emit),
+        start() {
+            displayed.clear();
+            ordinaryCommands = 1;
+            lastUpdateAt = -Infinity;
+            safeEmit({ type: "clearAll" });
+        },
+        update(snapshot, legalMoves) {
+            const now = entryClockMs();
+            if (now - lastUpdateAt < MIN_REFRESH_MS)
+                return;
+            lastUpdateAt = now;
+            const selected = selectCandidateArrows(snapshot, legalMoves);
+            const next = new Map(selected.map((arrow) => [
+                `${arrow.from}-${arrow.to}`,
+                arrow,
+            ]));
+            const diff = [];
+            for (const [key, arrow] of displayed) {
+                const replacement = next.get(key);
+                if (!replacement) {
+                    diff.push({ type: "clearArrow", from: arrow.from, to: arrow.to, fadeMs: CANDIDATE_FADE_MS });
+                }
+                else if (replacement.intensity !== arrow.intensity) {
+                    diff.push({
+                        type: "drawArrow",
+                        from: replacement.from,
+                        to: replacement.to,
+                        intensity: replacement.intensity,
+                        fadeMs: CANDIDATE_FADE_MS,
+                    });
+                }
+            }
+            for (const [key, arrow] of next) {
+                if (!displayed.has(key)) {
+                    diff.push({
+                        type: "drawArrow",
+                        from: arrow.from,
+                        to: arrow.to,
+                        intensity: arrow.intensity,
+                        fadeMs: CANDIDATE_FADE_MS,
+                    });
+                }
+            }
+            if (ordinaryCommands + diff.length > ORDINARY_COMMAND_LIMIT)
+                return;
+            for (const command of diff) {
+                safeEmit(command);
+                ordinaryCommands++;
+            }
+            displayed.clear();
+            for (const [key, arrow] of next)
+                displayed.set(key, arrow);
+        },
+        commit(move, position) {
+            const san = typeof move === "string" ? move : move?.san;
+            if (ordinaryCommands + displayed.size <= ORDINARY_COMMAND_LIMIT) {
+                for (const arrow of displayed.values()) {
+                    safeEmit({
+                        type: "clearArrow",
+                        from: arrow.from,
+                        to: arrow.to,
+                        fadeMs: CANDIDATE_FADE_MS,
+                    });
+                    ordinaryCommands++;
+                }
+                displayed.clear();
+            }
+            const verbose = position && typeof position.moves === "function"
+                ? position.moves({ verbose: true }).find((candidate) => candidate.san === san)
+                : null;
+            if (verbose) {
+                safeEmit({
+                    type: "drawArrow",
+                    from: verbose.from,
+                    to: verbose.to,
+                    intensity: 1,
+                    fadeMs: FINAL_FADE_MS,
+                });
+            }
+            return san;
+        },
+    };
+}
+export { selectCandidateArrows };
 export function normalizeBookFen(fen) {
     return fen.split(" ").slice(0, 4).join(" ");
 }
@@ -4064,13 +4331,25 @@ export async function loadPackage({ artifacts, ort, config }) {
         async newGame( /* { random } */) {
             const mcts = new MCTS(evaluator, new MCTSConfig({ nSimulations, timeBudgetMs, batchSize: MCTS_BATCH_SIZE }));
             return {
-                async chooseMove({ history, legalMoves }) {
+                async chooseMove({ history, legalMoves, moveTimeLimitMs, thinking }) {
                     if (!legalMoves || legalMoves.length === 0) {
                         throw new Error("chooseMove called with no legalMoves");
                     }
-                    const startedAt = clockMs();
+                    const startedAt = entryClockMs();
+                    const display = createThinkingDisplay(thinking);
+                    display.start();
+                    // moveTimeLimitMs is the runner's live per-move budget when
+                    // provided; margin it down so search itself stops with room to
+                    // encode/return before the runner's own clock (and definitely
+                    // before the 1.25x grace teardown) expires. Falls back to the
+                    // fixed timeBudgetMs (config override or DEFAULT_TIME_BUDGET_MS)
+                    // when the runner doesn't supply it.
+                    const searchTimeBudgetMs = Number.isFinite(moveTimeLimitMs) && moveTimeLimitMs > 0
+                        ? moveTimeLimitMs * MOVE_TIME_LIMIT_MARGIN
+                        : timeBudgetMs;
+                    let chess;
                     try {
-                        const chess = new Chess();
+                        chess = new Chess();
                         for (const san of history) {
                             chess.move(san);
                         }
@@ -4080,6 +4359,7 @@ export async function loadPackage({ artifacts, ort, config }) {
                             history: [...history],
                             fen: chess.fen(),
                             legalMoves: [...legalMoves],
+                            searchTimeBudgetMs,
                         });
                         const bookMove = history.length <= 9
                             ? bookMoveSan(chess, OPENING_BOOK, legalMoves)
@@ -4089,12 +4369,16 @@ export async function loadPackage({ artifacts, ort, config }) {
                                 type: "book_hit",
                                 ply: history.length,
                                 move: bookMove,
-                                elapsedMs: clockMs() - startedAt,
+                                elapsedMs: entryClockMs() - startedAt,
                             });
-                            return bookMove;
+                            return display.commit(bookMove, chess);
+                        }
+                        const searchOptions = { timeBudgetMs: searchTimeBudgetMs };
+                        if (display.enabled) {
+                            searchOptions.onRootUpdate = (snapshot) => display.update(snapshot, legalMoves);
                         }
-                        const chosen = await mcts.search(chess);
-                        const elapsedMs = clockMs() - startedAt;
+                        const chosen = await mcts.search(chess, searchOptions);
+                        const elapsedMs = entryClockMs() - startedAt;
                         // mcts.search() draws its move from chess.js's own legal-move
                         // list at the current position, which should always match the
                         // runner-provided legalMoves -- but if the runner's SAN
@@ -4110,7 +4394,7 @@ export async function loadPackage({ artifacts, ort, config }) {
                                 move: fallback,
                                 elapsedMs,
                             });
-                            return fallback;
+                            return display.commit(fallback, chess);
                         }
                         emitEvent(onEvent, {
                             type: "mcts_move",
@@ -4119,7 +4403,7 @@ export async function loadPackage({ artifacts, ort, config }) {
                             elapsedMs,
                             simCount: mcts.lastSimCount,
                         });
-                        return chosen;
+                        return display.commit(chosen, chess);
                     }
                     catch (error) {
                         const fallback = legalMoves[0];
@@ -4128,9 +4412,9 @@ export async function loadPackage({ artifacts, ort, config }) {
                             reason: "exception",
                             error: String(error instanceof Error ? error.message : error),
                             move: fallback,
-                            elapsedMs: clockMs() - startedAt,
+                            elapsedMs: entryClockMs() - startedAt,
                         });
-                        return fallback;
+                        return display.commit(fallback, chess);
                     }
                 },
                 async dispose() { },

browser/manifest.json

@@ -3,8 +3,8 @@
   "name": "minichess-gpt-student-v1",
   "entrypoint": {
     "path": "entry.js",
-    "bytes": 1004943,
-    "sha256": "080962ccd9b71b7cf7cb8c1793e21ad27737e59002b1b9823bded14b54f6e88e"
+    "bytes": 1017367,
+    "sha256": "ff7875c9f06f6eda265dde2cd2f86811b4a449079c0c1e8fdc1a3d845bc73e8a"
   },
   "artifacts": {
     "model": {
@@ -13,5 +13,35 @@
       "sha256": "aad1bed67c2f3517d30f914bafe9d57f6c7f84194150daa5322f7081f3a1df0f"
     }
   },
-  "config": {}
+  "config": {
+    "release": {
+      "variant": "student-v1",
+      "modelSha256": "aad1bed67c2f3517d30f914bafe9d57f6c7f84194150daa5322f7081f3a1df0f",
+      "modelBytes": 5551177,
+      "sourceCommit": "cdedb20d8348148d9c02ec5ba6fe0d01958da81c",
+      "modelPath": "runs/student_distillation/student-v1/student.onnx",
+      "modelSource": "registry",
+      "modelContract": {
+        "validated": true,
+        "publishable": true,
+        "inputName": "tokens",
+        "inputType": "int64",
+        "sequenceLength": 69,
+        "outputShapes": {
+          "policy": [
+            1,
+            4272
+          ],
+          "wdl": [
+            1,
+            3
+          ],
+          "uncertainty": [
+            1,
+            1
+          ]
+        }
+      }
+    }
+  }
 }