@cubingcenter/scrambler 0.6.3 → 0.8.0

package/dist/puzzles/cube4/reduction/phase3-search.js

@@ -6,6 +6,7 @@
  */
 import { CENTER3_MOVES } from "./center3.js";
 import { getSymTables, getMvSymFrom, MOVE3_STD } from "./edge3.js";
+import { HC_PDB_MOVES } from "./hc-pdb.js";
 /** The 17 exploration moves (the reference's m < 17 bound). */
 export const SEARCH_MOVES = CENTER3_MOVES.slice(0, 17);
 // Commutation / move-cancellation pruning tables
@@ -33,85 +34,510 @@ for (let i = 0; i < 20; i++) {
         }
     }
 }
-/**
- * Fast table-driven Phase 3 IDA* solver class.
- */
+/** Popcount of 12-bit masks (the inlined sym-coordinate rank). */
+const POPC12 = new Uint8Array(4096);
+for (let i = 1; i < 4096; i++)
+    POPC12[i] = POPC12[i >> 1] + (i & 1);
+/** Flat row-major ckmv3 (21x20) + typed skipAxis3 for the hot recursion. */
+const ckmv3Flat = new Uint8Array(21 * 20);
+for (let i = 0; i < 21; i++) {
+    for (let j = 0; j < 20; j++)
+        ckmv3Flat[i * 20 + j] = ckmv3[i][j] ? 1 : 0;
+}
+const skipAxis3Fast = Int32Array.from(skipAxis3);
+const F_SLOT_MAP = [
+    [4, 5, 2, 3, 1, 0, 6, 7, 8, 9, 10, 11],
+    [1, 0, 2, 3, 5, 4, 6, 7, 8, 9, 10, 11],
+    [5, 4, 2, 3, 0, 1, 6, 7, 8, 9, 10, 11],
+    [0, 1, 2, 3, 4, 6, 5, 7, 8, 9, 11, 10],
+    [11, 1, 2, 8, 4, 5, 6, 7, 0, 9, 10, 3],
+    [3, 1, 2, 0, 4, 5, 6, 7, 11, 9, 10, 8],
+    [8, 1, 2, 11, 4, 5, 6, 7, 3, 9, 10, 0],
+    [0, 1, 7, 6, 4, 5, 2, 3, 8, 9, 10, 11],
+    [0, 1, 3, 2, 4, 5, 7, 6, 8, 9, 10, 11],
+    [0, 1, 6, 7, 4, 5, 3, 2, 8, 9, 10, 11],
+    [0, 1, 2, 3, 7, 5, 6, 4, 9, 8, 10, 11],
+    [0, 9, 10, 3, 4, 5, 6, 7, 8, 2, 1, 11],
+    [0, 2, 1, 3, 4, 5, 6, 7, 8, 10, 9, 11],
+    [0, 10, 9, 3, 4, 5, 6, 7, 8, 1, 2, 11],
+    [1, 0, 2, 3, 5, 4, 6, 7, 8, 11, 10, 9],
+    [0, 3, 2, 1, 4, 6, 5, 7, 8, 9, 11, 10],
+    [3, 1, 2, 0, 4, 7, 6, 5, 11, 9, 10, 8]
+];
+const H_SLOT_MAP = [
+    [4, 5, 2, 3, 1, 0, 6, 7, 8, 9, 10, 11],
+    [1, 0, 2, 3, 5, 4, 6, 7, 8, 9, 10, 11],
+    [5, 4, 2, 3, 0, 1, 6, 7, 8, 9, 10, 11],
+    [0, 1, 2, 3, 4, 6, 5, 7, 8, 9, 11, 10],
+    [11, 1, 2, 8, 4, 5, 6, 7, 0, 9, 10, 3],
+    [3, 1, 2, 0, 4, 5, 6, 7, 11, 9, 10, 8],
+    [8, 1, 2, 11, 4, 5, 6, 7, 3, 9, 10, 0],
+    [0, 1, 7, 6, 4, 5, 2, 3, 8, 9, 10, 11],
+    [0, 1, 3, 2, 4, 5, 7, 6, 8, 9, 10, 11],
+    [0, 1, 6, 7, 4, 5, 3, 2, 8, 9, 10, 11],
+    [0, 1, 2, 3, 7, 5, 6, 4, 9, 8, 10, 11],
+    [0, 9, 10, 3, 4, 5, 6, 7, 8, 2, 1, 11],
+    [0, 2, 1, 3, 4, 5, 6, 7, 8, 10, 9, 11],
+    [0, 10, 9, 3, 4, 5, 6, 7, 8, 1, 2, 11],
+    [1, 0, 2, 3, 5, 4, 6, 7, 10, 9, 8, 11],
+    [2, 1, 0, 3, 4, 6, 5, 7, 8, 9, 11, 10],
+    [3, 1, 2, 0, 6, 5, 4, 7, 11, 9, 10, 8]
+];
 export class FastPhase3Solver {
     tempep;
     moveLog;
     sym;
+    /** Transposition Table size: 2^20 = 1,048,576 entries (12 MiB per solve).
+     * The previous 2M table used 24 MiB per process, plus a separate 8 MiB
+     * generation array. The compact 1M table leaves room for concurrent
+     * solvers under the 150 MiB reduction-table budget. */
+    static TT_SIZE = 1 << 20;
+    static TT_MASK = FastPhase3Solver.TT_SIZE - 1;
+    tt = new Uint32Array(FastPhase3Solver.TT_SIZE * 3);
+    // TT info packs (call id:20, previous move:5, remaining depth:6), avoiding
+    // a separate 8 MiB generation array while retaining exact proof tracking.
+    static CALL_ID_LIMIT = 1 << 20;
+    callSeq = 1;
+    callId = 0;
+    contextCenter3;
+    contextEdge3;
+    /** Reset this solver's cumulative node counter (legacy method name). */
+    resetEpochNodes() {
+        this.epochNodes = 0;
+    }
+    clearTranspositionTable() {
+        this.tt.fill(0);
+        this.callSeq = 1;
+    }
+    setTableContext(center3, edge3Distances) {
+        if (this.contextCenter3 === center3 && this.contextEdge3 === edge3Distances)
+            return;
+        this.clearTranspositionTable();
+        this.contextCenter3 = center3;
+        this.contextEdge3 = edge3Distances;
+    }
+    /** Fresh per-call id for TT-generation tagging. */
+    nextCallId() {
+        const id = this.callSeq++;
+        if (this.callSeq >= FastPhase3Solver.CALL_ID_LIMIT) {
+            this.tt.fill(0);
+            this.callSeq = 1;
+        }
+        return id;
+    }
     constructor() {
-        this.tempep = Array.from({ length: 30 }, () => new Uint8Array(12));
-        this.moveLog = new Array(30);
+        // Preallocated to well above the deepest phase-3 sweep (maxLength3 <= 27):
+        // `ensureDepth` stays as a fallback for out-of-band callers.
+        this.tempep = Array.from({ length: 48 }, () => new Uint8Array(12));
+        this.moveLog = new Array(48);
         this.sym = getSymTables();
     }
-    getPrun(distances, idx) {
-        const byte = distances[idx >> 1];
-        return (idx & 1) === 0 ? byte & 0x0f : byte >> 4;
+    ensureDepth(depth) {
+        while (this.tempep.length <= depth) {
+            this.tempep.push(new Uint8Array(12));
+            this.moveLog.push(0);
+        }
     }
+    nodeCount = 0;
+    /** Cumulative nodes across calls (reset per solve generation). */
+    epochNodes = 0;
+    /**
+     * Proof bookkeeping for IDA* threshold propagation (reset per exact-length
+     * call). When a length-L search exhausts its tree WITHOUT hitting any of
+     * these flags, no (center, edge) solution exists at any length below
+     * `minExcess`, so the caller may skip straight to it:
+     * - `capped`: the node budget aborted the search (bounds unknown).
+     * - `limitHit`: goal enumeration hit its cap (tree not exhausted).
+     * - `sawGoal`: a goal was reached (even if the validator rejected it —
+     *   a nearby length may still validate, so only step L+1).
+     * - `ttTouched`: a transposition-table hit from ANOTHER exact-length call
+     *   skipped a subtree, and the hit was not certified goal-free across
+     *   candidate validators.
+     * Bound-based axis skips need no flag: the skipped siblings are
+     * same-face turns, so noteExcess records their triangle-inequality bound.
+     */
+    capped = false;
+    limitHit = false;
+    sawGoal = false;
+    ttTouched = false;
+    minExcess = 0;
     /**
-     * Recursive IDA* worker on table transitions.
+     * Root-length coverage of the tightest TT hit this call (depth +
+     * storedDepth): the pruned subtree proves no goal at or below that root
+     * length under the call's predicate. `Number.MAX_SAFE_INTEGER` when no hit
+     * pruned anything. Feeds `validatedThrough`.
      */
-    async search(eplast, ct, prun, maxl, lm, depth, center3Tables, edge3Distances) {
-        if (maxl === 0)
-            return true;
-        if (depth % 500 === 0)
-            await new Promise(r => setTimeout(r, 0));
+    ttCoverage = Number.MAX_SAFE_INTEGER;
+    /**
+     * Recursive IDA* worker on table transitions with Transposition Table pruning.
+     */
+    search(eplast, ct, prun, maxl, lm, depth, center3Tables, edge3Distances, maxNodes = 15000, collect, hc, hcCoord = -1, c3PairDist) {
+        this.nodeCount++;
+        this.epochNodes++;
+        if (this.nodeCount > maxNodes) {
+            this.capped = true;
+            return false;
+        }
+        // Goal test at EVERY node (any length <= maxl), not only at maxl === 0
+        // leaves: a goal is (edge paired AND center3 at goal) — both PDB
+        // distances zero (the parent's gates guarantee leaves are goals, so this
+        // strictly generalizes the old leaf test). Exact-length-only detection
+        // made shorter goals on the same path invisible ("a nearby length may
+        // still validate"), which both blocked proofs on any raw goal and hid
+        // shorter solutions.
+        if (prun === 0 && center3Tables.pruning[ct] === 0) {
+            this.sawGoal = true;
+            if (!collect)
+                return true;
+            collect.examined++;
+            const moves = this.moveLog.slice(0, depth).map((m) => SEARCH_MOVES[m]);
+            if (collect.validate(moves))
+                return true;
+            if (collect.examined >= collect.limit) {
+                this.limitHit = true;
+                return true;
+            }
+            // A rejected goal is not a goal for the validator's predicate: keep
+            // exploring the subtree — validated goals may sit deeper on the same
+            // branches. At the fringe (maxl === 0) there is no subtree left, so
+            // record the branch's coverage claim here (nothing below `depth` on
+            // this branch was searched): "no validated goal at <= depth".
+            if (maxl === 0 && depth < this.minExcess)
+                this.minExcess = depth + 1;
+        }
+        else if (maxl === 0) {
+            return false;
+        }
+        if (depth >= this.tempep.length)
+            this.ensureDepth(depth);
+        const sym = this.sym;
+        const symMvrot = sym.mvrot;
+        const symMvroto = sym.mvroto;
         const ep = this.tempep[depth];
         if (lm !== 20) {
             const movoBase = (lm << 3) * 12;
-            const movBase = (lm << 3) * 12;
             for (let i = 0; i < 12; i++) {
-                ep[i] = this.sym.mvroto[movoBase + eplast[this.sym.mvrot[movBase + i]]];
+                ep[i] = symMvroto[movoBase + eplast[symMvrot[movoBase + i]]];
             }
         }
         else {
             ep.set(eplast);
         }
+        const hasHc = hc !== undefined && hcCoord >= 0 && hc.moves.length > 0;
+        // HC pruning depends on a second coordinate not represented in the TT
+        // key. The root c3-pair check also varies only at depth zero. Do not reuse
+        // entries in those contexts; all other phase-3 state is key-complete.
+        const useTt = !hasHc && !(depth === 0 && c3PairDist !== undefined);
+        // TT: entries claim "no RAW goal at any length <= maxl from (ep, lm)" —
+        // coordinate-complete and predicate-independent (the validator's
+        // full-state checks are NOT coordinate-complete, so no validator-scoped
+        // claims may be cached). Hits are `<=`-claims and therefore
+        // proof-compatible for `validatedThrough`/`provenThrough` coverage.
+        const ttActive = useTt && maxl >= 2;
+        let keyHigh = 0;
+        let keyLow = 0;
+        let slot = 0;
+        if (ttActive) {
+            keyHigh = ((ct << 16) | (ep[8] | (ep[9] << 4) | (ep[10] << 8) | (ep[11] << 12))) >>> 0;
+            keyLow = (ep[0] | (ep[1] << 4) | (ep[2] << 8) | (ep[3] << 12) |
+                (ep[4] << 16) | (ep[5] << 20) | (ep[6] << 24) | (ep[7] << 28)) >>> 0;
+            slot = (((keyLow ^ Math.imul(keyHigh, 0x9e3779b9)) & FastPhase3Solver.TT_MASK) * 3) >>> 0;
+            const storedHigh = this.tt[slot];
+            const storedLow = this.tt[slot + 1];
+            const storedInfo = this.tt[slot + 2];
+            if (storedHigh === keyHigh && storedLow === keyLow) {
+                const storedCallId = (storedInfo >>> 11) & 0xfffff;
+                const storedLm = (storedInfo >>> 6) & 0x1f;
+                const storedDepth = storedInfo & 0x3f;
+                if (storedDepth >= maxl && storedLm === lm) {
+                    const coverage = depth + storedDepth;
+                    if (coverage < this.ttCoverage)
+                        this.ttCoverage = coverage;
+                    if (storedCallId !== this.callId)
+                        this.ttTouched = true;
+                    return false;
+                }
+            }
+        }
+        const c3Move = center3Tables.moveTable;
+        const c3Prun = center3Tables.pruning;
+        const c3Row = ct * CENTER3_MOVES.length;
+        const sym2Raw = sym.sym2Raw;
+        const sym2Mask = sym.sym2Mask;
+        const raw2Sym = sym.raw2Sym;
+        const hcMoves = hasHc ? hc.moves : null;
+        const hcDist = hasHc ? hc.distances : null;
+        const hcRow = hasHc ? hcCoord * HC_PDB_MOVES.length : 0;
+        // Byte-expanded (tests/generators) vs nibble-packed (loaders) distances.
+        const edgeUnpacked = edge3Distances.length >= 31006080;
+        const examined0 = collect === undefined ? 0 : collect.examined;
+        const ckmvRow = lm * 20;
         for (let m = 0; m < 17; m++) {
-            if (ckmv3[lm][m]) {
-                m = skipAxis3[m];
+            if (ckmv3Flat[ckmvRow + m]) {
+                m = skipAxis3Fast[m];
                 continue;
             }
-            const nc = center3Tables.moveTable[ct * CENTER3_MOVES.length + m];
+            const nc = c3Move[c3Row + m];
             if (nc < 0)
                 continue;
-            const prun1 = center3Tables.pruning[nc];
+            const prun1 = c3Prun[nc];
             if (prun1 >= maxl) {
+                const ex1 = (prun1 > maxl && m < 14) ? depth + prun1 : depth + 1 + prun1;
+                if (ex1 < this.minExcess)
+                    this.minExcess = ex1;
                 if (prun1 > maxl && m < 14)
-                    m = skipAxis3[m];
+                    m = skipAxis3Fast[m];
                 continue;
             }
-            const symIdx = getMvSymFrom(ep, ep, m, this.sym.sym2Raw, this.sym.sym2Mask, this.sym.raw2Sym, this.sym.mvrot, this.sym.mvroto);
-            const prunx = this.getPrun(edge3Distances, symIdx >> 3);
+            let nhc = -1;
+            if (hasHc) {
+                nhc = hcMoves[hcRow + m];
+                if (nhc >= 0) {
+                    const prunh = hcDist[nhc];
+                    if (prunh >= maxl) {
+                        const exH = (prunh > maxl && m < 14) ? depth + prunh : depth + 1 + prunh;
+                        if (exH < this.minExcess)
+                            this.minExcess = exH;
+                        if (prunh > maxl && m < 14)
+                            m = skipAxis3Fast[m];
+                        continue;
+                    }
+                }
+            }
+            if (c3PairDist && depth === 0) {
+                const c3Base = nc * 144;
+                const fSlot = F_SLOT_MAP[m];
+                const hSlot = H_SLOT_MAP[m];
+                let prunPair = 0;
+                for (let s = 0; s < 12; s++) {
+                    const idx = c3Base + fSlot[s] * 12 + hSlot[ep[s]];
+                    const d = (idx & 1) === 0 ? (c3PairDist[idx >> 1] & 0x0f) : (c3PairDist[idx >> 1] >> 4);
+                    if (d >= maxl) {
+                        prunPair = d;
+                        break;
+                    }
+                    if (d > prunPair)
+                        prunPair = d;
+                }
+                if (prunPair >= maxl) {
+                    const exP = (prunPair > maxl && m < 14) ? depth + prunPair : depth + 1 + prunPair;
+                    if (exP < this.minExcess)
+                        this.minExcess = exP;
+                    if (prunPair > maxl && m < 14)
+                        m = skipAxis3Fast[m];
+                    continue;
+                }
+            }
+            // Inlined getMvSymFrom(ep, ep, m, ...) (bit-identical; masks here are
+            // 12-bit, so one popcount lookup replaces bitCount's three).
+            let mrIdx = m << 3;
+            let movoBase = mrIdx * 12;
+            let raw = 0;
+            let bits = 0;
+            for (let i = 0; i < 4; i++) {
+                const val = symMvroto[movoBase + ep[symMvrot[movoBase + i]]];
+                raw = raw * (12 - i) + val - POPC12[bits & ((1 << val) - 1)];
+                bits |= 1 << val;
+            }
+            const symBase = raw2Sym[raw];
+            mrIdx |= symBase & 7;
+            let symOut = symBase >> 3;
+            bits = sym2Mask[symOut];
+            movoBase = mrIdx * 12;
+            for (let i = 4; i < 10; i++) {
+                const val = symMvroto[movoBase + ep[symMvrot[movoBase + i]]];
+                symOut = symOut * (12 - i) + val - POPC12[bits & ((1 << val) - 1)];
+                bits |= 1 << val;
+            }
+            const symIdx = ((symOut << 3) | (mrIdx & 7)) >>> 0;
+            // Format-aware read: loaders keep the nibble-packed table (15.5MB);
+            // tests and generators may pass byte-expanded buffers instead.
+            const eIdx = symIdx >> 3;
+            const prunx = edgeUnpacked
+                ? edge3Distances[eIdx]
+                : (edge3Distances[eIdx >> 1] >> ((eIdx & 1) * 4)) & 0x0f;
             if (prunx >= maxl) {
+                const exE = (prunx > maxl && m < 14) ? depth + prunx : depth + 1 + prunx;
+                if (exE < this.minExcess)
+                    this.minExcess = exE;
                 if (prunx > maxl && m < 14)
-                    m = skipAxis3[m];
+                    m = skipAxis3Fast[m];
                 continue;
             }
-            if (await this.search(ep, nc, prunx, maxl - 1, m, depth + 1, center3Tables, edge3Distances)) {
-                this.moveLog[depth] = m;
+            this.moveLog[depth] = m;
+            if (this.search(ep, nc, prunx, maxl - 1, m, depth + 1, center3Tables, edge3Distances, maxNodes, collect, hc, nhc, c3PairDist)) {
                 return true;
             }
         }
+        // Cache only subtrees with NO raw goal reached in them (the examined
+        // count is the goal counter — rejections included, since the claim is
+        // raw). Goal-free subtrees are safe to reuse across calls, candidates
+        // and predicates.
+        if (ttActive &&
+            this.nodeCount <= maxNodes &&
+            (collect?.examined ?? 0) === examined0) {
+            this.tt[slot] = keyHigh;
+            this.tt[slot + 1] = keyLow;
+            this.tt[slot + 2] = ((this.callId << 11) | (lm << 6) | maxl) >>> 0;
+        }
         return false;
     }
     /**
-     * Search for a phase-3 solution with exact target length.
+     * Record an IDA* bound prune (inlined at the four gate sites): the child at
+     * `depth + 1` needs at least `childBound` more moves, so no solution exists
+     * through this branch below root threshold `depth + 1 + childBound`. When a
+     * bound-based axis skip also fires, the skipped siblings are same-face turns
+     * (verified: every non-empty skipAxis3 run under m < 14 is a same-base
+     * triple), hence at most 1 legal move apart — their bound is at least
+     * `childBound - 1` by the triangle inequality on the exact PDBs, so the
+     * recorded excess `depth + childBound` stays a true lower bound.
+     */
+    /**
+     * Search for a phase-3 solution with exact target length (first found).
      */
-    async solveLength(edge, ct3, edist, length3, center3Tables, edge3Distances) {
+    solveLength(edge, ct3, edist, length3, center3Tables, edge3Distances, maxNodes = 15000, hc, hcCoord = -1, c3PairDist) {
+        this.setTableContext(center3Tables, edge3Distances);
         this.tempep[0].set(edge);
-        if (await this.search(this.tempep[0], ct3, edist, length3, 20, 0, center3Tables, edge3Distances)) {
+        this.nodeCount = 0;
+        this.callId = this.nextCallId();
+        this.ttCoverage = Number.MAX_SAFE_INTEGER;
+        if (this.search(this.tempep[0], ct3, edist, length3, 20, 0, center3Tables, edge3Distances, maxNodes, undefined, hc, hcCoord, c3PairDist)) {
             return this.moveLog.slice(0, length3).map((m) => SEARCH_MOVES[m]);
         }
         return null;
     }
+    /**
+     * Search for a phase-3 solution with exact target length, accepting the
+     * first goal sequence that passes `validate` (up to `limit` examined,
+     * sharing `maxNodes`). With a validator that enforces the downstream
+     * requirements (reduction + standard orientation + 3x3 conversion), hard
+     * states whose first-found solutions are unusable get more draws from
+     * the same budget instead of an immediate miss.
+     */
+    solveLengthValid(edge, ct3, edist, length3, center3Tables, edge3Distances, maxNodes = 15000, limit = 16, validate, hc, hcCoord = -1, c3PairDist) {
+        return this.solveLengthProven(edge, ct3, edist, length3, center3Tables, edge3Distances, maxNodes, limit, validate, hc, hcCoord, c3PairDist).moves;
+    }
+    /**
+     * Exact-length validated search that also reports what the call proved.
+     * `provenThrough` is the greatest length with provably no (center, edge)
+     * solution: set only when the tree was exhaustively explored with no goal
+     * reached, no node-cap abort, no TT hit, and complete excess info — the
+     * caller may then skip every shorter length for this candidate. Otherwise
+     * it is `length3 - 1` at most (only the attempted length is settled).
+     */
+    solveLengthProven(edge, ct3, edist, length3, center3Tables, edge3Distances, maxNodes = 15000, limit = 16, validate, hc, hcCoord = -1, c3PairDist) {
+        this.setTableContext(center3Tables, edge3Distances);
+        if (c3PairDist) {
+            const c3Base = ct3 * 144;
+            let maxPairDist = 0;
+            for (let s = 0; s < 12; s++) {
+                const idx = c3Base + s * 12 + edge[s];
+                const d = (idx & 1) === 0 ? (c3PairDist[idx >> 1] & 0x0f) : (c3PairDist[idx >> 1] >> 4);
+                if (d > maxPairDist)
+                    maxPairDist = d;
+            }
+            if (maxPairDist > length3) {
+                return { moves: null, provenThrough: maxPairDist - 1, validatedThrough: maxPairDist - 1, nodesUsed: 0 };
+            }
+        }
+        this.tempep[0].set(edge);
+        this.nodeCount = 0;
+        this.capped = false;
+        this.limitHit = false;
+        this.sawGoal = false;
+        this.ttTouched = false;
+        this.minExcess = Number.MAX_SAFE_INTEGER;
+        this.ttCoverage = Number.MAX_SAFE_INTEGER;
+        this.callId = this.nextCallId();
+        let accepted = null;
+        const collect = {
+            limit,
+            examined: 0,
+            validate: (moves) => {
+                if (validate(moves)) {
+                    accepted = moves;
+                    return true;
+                }
+                // A rejected goal is not a validated solution. Enumeration callers
+                // may collect it themselves, but cannot use it as a search proof.
+                return false;
+            }
+        };
+        this.search(this.tempep[0], ct3, edist, length3, 20, 0, center3Tables, edge3Distances, maxNodes, collect, hc, hcCoord, c3PairDist);
+        if (accepted)
+            return { moves: accepted, provenThrough: length3, validatedThrough: length3, nodesUsed: this.nodeCount };
+        if (typeof process !== "undefined" && process.env?.CUBE4_PROOF_STATS === "1") {
+            proofStats.total++;
+            if (this.capped)
+                proofStats.capped++;
+            if (this.limitHit)
+                proofStats.limitHit++;
+            if (this.sawGoal)
+                proofStats.sawGoal++;
+            if (this.ttTouched)
+                proofStats.ttTouched++;
+        }
+        // `provenThrough` keeps its conservative raw-goal contract: it may only
+        // claim a depth when NO raw goal was reached at all (a rejected goal IS
+        // a raw goal), no TT hit intervened, and the bound prunes cover past the
+        // attempted length.
+        let provenThrough = -1;
+        if (!this.capped &&
+            !this.limitHit &&
+            !this.sawGoal &&
+            !this.ttTouched &&
+            this.minExcess > length3 &&
+            this.minExcess !== Number.MAX_SAFE_INTEGER) {
+            if (typeof process !== "undefined" && process.env?.CUBE4_PROOF_STATS === "1") {
+                proofStats.clean++;
+                proofStats.jumpSum += this.minExcess - 1 - length3;
+            }
+            provenThrough = this.minExcess - 1;
+        }
+        // `validatedThrough` is scoped to THIS call's validator predicate (all
+        // calls sharing one solver instance use one predicate): rejected raw
+        // goals are not goals for it, and TT hits are proof-compatible (entries
+        // mean "no goal under the call's predicate at any length <= stored").
+        // Every walked branch leaves a claim: bound prunes record their
+        // threshold (noteExcess), fringe rejections record `length3 + 1` below,
+        // and TT-hit subtrees record `ttCoverage`.
+        let validatedThrough = -1;
+        if (!this.capped && !this.limitHit) {
+            let bound = length3;
+            if (this.minExcess !== Number.MAX_SAFE_INTEGER && this.minExcess - 1 > bound) {
+                bound = this.minExcess - 1;
+            }
+            if (this.ttCoverage < bound)
+                bound = this.ttCoverage;
+            validatedThrough = bound;
+        }
+        return { moves: null, provenThrough, validatedThrough, nodesUsed: this.nodeCount };
+    }
+}
+/** Temporary instrumentation for proof-statistics (CUBE4_PROOF_STATS=1). */
+export const proofStats = {
+    total: 0,
+    capped: 0,
+    limitHit: 0,
+    sawGoal: 0,
+    ttTouched: 0,
+    clean: 0,
+    jumpSum: 0
+};
+export function resetProofStats() {
+    proofStats.total = 0;
+    proofStats.capped = 0;
+    proofStats.limitHit = 0;
+    proofStats.sawGoal = 0;
+    proofStats.ttTouched = 0;
+    proofStats.clean = 0;
+    proofStats.jumpSum = 0;
 }
-const defaultSolver = new FastPhase3Solver();
 /**
  * Solve Phase 3 with iterative deepening on a single Phase3Start.
  */
-export async function solvePhase3(start, center3Tables, edge3Tables, maxLength = 20) {
+export async function solvePhase3(start, center3Tables, edge3Tables, maxLength = 20, maxNodes = 80_000) {
+    const solver = new FastPhase3Solver();
     const sym = getSymTables();
     const symIdx = getMvSymFrom(start.edge, start.edge, 20, sym.sym2Raw, sym.sym2Mask, sym.raw2Sym, sym.mvrot, sym.mvroto);
     const edist = (edge3Tables.distances[(symIdx >> 3) >> 1] >> (((symIdx >> 3) & 1) * 4)) & 0x0f;
@@ -120,7 +546,7 @@ export async function solvePhase3(start, center3Tables, edge3Tables, maxLength =
         return null;
     const minLength = Math.max(cdist, edist);
     for (let l = minLength; l <= maxLength; l++) {
-        const moves = await defaultSolver.solveLength(start.edge, start.ct3, edist, l, center3Tables, edge3Tables.distances);
+        const moves = solver.solveLength(start.edge, start.ct3, edist, l, center3Tables, edge3Tables.distances, maxNodes);
         if (moves) {
             return {
                 moves,

package/dist/puzzles/cube4/reduction/rotation-fix.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Placement of the whole-cube rotation fix inside a 4x4 solution.
+ *
+ * The reduction ends with the cube solved in some orientation, so the solve
+ * is `P ++ W(R) ++ Q` where `W(R)` are the 2-4 wide moves of the rotation R
+ * (`x` = `Rw Lw'`, ...). A rotation commutes with any move sequence once the
+ * sequence's faces are re-mapped:
+ *
+ *   X ++ W(R)  ≡  W(R) ++ rotateAlgorithm(X, R)
+ *
+ * so the fix can sit at ANY point of the solution (with the moves after it
+ * re-mapped), and a two-rotation fix can be split across two points. The
+ * total is unchanged except at the insertion junctions, where the fix can
+ * cancel against same-axis wide moves (`Uw2 · y2` = `Uw2 · Uw2 Dw2` = `Dw2`).
+ * `placeRotationFix` picks the placement with the shortest simplified total.
+ */
+import type { Cube4Move } from "../types.js";
+/** Wide-move words of the 9 single rotations. */
+export declare const ROTATION_WORDS: Readonly<Record<string, readonly Cube4Move[]>>;
+/**
+ * Shortest simplified solution equivalent to `prefix ++ W(rotation) ++
+ * suffix` (same effect on every state), over every run-boundary insertion
+ * point of the fix and every minimal factorization of the rotation. Only
+ * run boundaries matter: the fix can only merge with runs on its own axis,
+ * and re-mapping preserves the run structure of what follows it.
+ */
+export declare function placeRotationFix(prefix: readonly Cube4Move[], rotation: readonly string[], suffix: readonly Cube4Move[]): Cube4Move[];
+//# sourceMappingURL=rotation-fix.d.ts.map

package/dist/puzzles/cube4/reduction/rotation-fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation-fix.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/rotation-fix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,iDAAiD;AACjD,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC,CAUzE,CAAC;AA0FF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,SAAS,EAAE,CA0Fb"}