@cubingcenter/scrambler 0.6.3 → 0.7.0

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

@@ -6,10 +6,12 @@
  * and all 12 wing pairs paired (sym-index == 0), using the 17-move exploration set.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FastPhase3Solver = exports.skipAxis3 = exports.ckmv3 = exports.SEARCH_MOVES = void 0;
+exports.proofStats = exports.FastPhase3Solver = exports.skipAxis3 = exports.ckmv3 = exports.SEARCH_MOVES = void 0;
+exports.resetProofStats = resetProofStats;
 exports.solvePhase3 = solvePhase3;
 const center3_js_1 = require("./center3.js");
 const edge3_js_1 = require("./edge3.js");
+const hc_pdb_js_1 = require("./hc-pdb.js");
 /** The 17 exploration moves (the reference's m < 17 bound). */
 exports.SEARCH_MOVES = center3_js_1.CENTER3_MOVES.slice(0, 17);
 // Commutation / move-cancellation pruning tables
@@ -37,81 +39,399 @@ for (let i = 0; i < 20; i++) {
         }
     }
 }
-/**
- * Fast table-driven Phase 3 IDA* solver class.
- */
+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]
+];
 class FastPhase3Solver {
     tempep;
     moveLog;
     sym;
+    /** Transposition Table size: 2^21 = 2,097,152 entries (24 MB in RAM).
+     *  NOTE: doubling to 4M was tried and reverted (-0.07% nodes on the
+     *  corpus — the 2M working set already captures the hit locality). */
+    static TT_SIZE = 1 << 21;
+    static TT_MASK = FastPhase3Solver.TT_SIZE - 1;
+    static tt = new Uint32Array(FastPhase3Solver.TT_SIZE * 3);
+    static epoch = 1;
+    /**
+     * Per-slot exact-length-call tag (8 MB transient). TT pruning stays
+     * epoch-scoped (unchanged traversal), but threshold proofs only trust
+     * same-call hits: a hit from another call may have validated under a
+     * different candidate, so it still prunes yet marks the proof dirty.
+     */
+    static ttGen = new Uint32Array(FastPhase3Solver.TT_SIZE);
+    static callSeq = 1;
+    callId = 0;
+    /** Reset the per-attempt cumulative node counter. */
+    resetEpochNodes() {
+        this.epochNodes = 0;
+    }
+    static nextEpoch() {
+        FastPhase3Solver.epoch = (FastPhase3Solver.epoch + 1) & 0xffff;
+        if (FastPhase3Solver.epoch === 0) {
+            FastPhase3Solver.tt.fill(0);
+            FastPhase3Solver.ttGen.fill(0);
+            FastPhase3Solver.callSeq = 1;
+            FastPhase3Solver.epoch = 1;
+        }
+    }
+    /** Fresh per-call id for TT-generation tagging (epoch wrap resets it). */
+    static nextCallId() {
+        const id = FastPhase3Solver.callSeq++;
+        if (FastPhase3Solver.callSeq > 0xfffffffe) {
+            FastPhase3Solver.ttGen.fill(0);
+            FastPhase3Solver.callSeq = 1;
+            return 1;
+        }
+        return id;
+    }
     constructor() {
         this.tempep = Array.from({ length: 30 }, () => new Uint8Array(12));
         this.moveLog = new Array(30);
         this.sym = (0, edge3_js_1.getSymTables)();
     }
+    nodeCount = 0;
+    /** Cumulative nodes across calls (reset per attempt via resetEpochNodes). */
+    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 (same-call hits replay this call's own exhausted
+     *   subtree and stay clean; other calls may validate under a different
+     *   candidate, so their stored proof does not transfer).
+     * 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;
     getPrun(distances, idx) {
-        const byte = distances[idx >> 1];
-        return (idx & 1) === 0 ? byte & 0x0f : byte >> 4;
+        return distances.length >= 31006080
+            ? distances[idx]
+            : (distances[idx >> 1] >> ((idx & 1) * 4)) & 0x0f;
     }
     /**
-     * Recursive IDA* worker on table transitions.
+     * Recursive IDA* worker on table transitions with Transposition Table pruning.
      */
-    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));
+    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;
+        }
+        if (maxl === 0) {
+            if (!collect)
+                return true;
+            this.sawGoal = true;
+            collect.examined++;
+            const moves = this.moveLog.slice(0, depth).map((m) => exports.SEARCH_MOVES[m]);
+            if (collect.validate(moves))
+                return true;
+            if (collect.examined >= collect.limit)
+                this.limitHit = true;
+            return collect.examined >= collect.limit;
+        }
+        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);
         }
+        // TT lookup (for depths >= 2 where TT hit prunes multi-move subtrees)
+        const keyHigh = ((ct << 16) | (ep[8] | (ep[9] << 4) | (ep[10] << 8) | (ep[11] << 12))) >>> 0;
+        const 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;
+        const slot = (((keyLow ^ Math.imul(keyHigh, 0x9e3779b9)) & FastPhase3Solver.TT_MASK) * 3) >>> 0;
+        if (maxl >= 2) {
+            const storedHigh = FastPhase3Solver.tt[slot];
+            const storedLow = FastPhase3Solver.tt[slot + 1];
+            const storedInfo = FastPhase3Solver.tt[slot + 2];
+            if (storedHigh === keyHigh && storedLow === keyLow) {
+                const storedEpoch = storedInfo >>> 16;
+                const storedLm = (storedInfo >> 8) & 0xff;
+                const storedDepth = storedInfo & 0xff;
+                if (storedEpoch === FastPhase3Solver.epoch && storedDepth >= maxl && storedLm === lm) {
+                    // Same-call hits replay this call's own exhausted subtree (proof
+                    // stays clean); cross-call hits still prune but dirty the proof.
+                    // NOTE: ignoring cross-call entries was tried and reverted — they
+                    // carry most of the pruning power (3.82s vs 2.39s on the corpus).
+                    if (FastPhase3Solver.ttGen[(slot / 3) | 0] !== this.callId)
+                        this.ttTouched = true;
+                    return false;
+                }
+            }
+        }
+        const c3Move = center3Tables.moveTable;
+        const c3Prun = center3Tables.pruning;
+        const c3Row = ct * center3_js_1.CENTER3_MOVES.length;
+        const sym2Raw = sym.sym2Raw;
+        const sym2Mask = sym.sym2Mask;
+        const raw2Sym = sym.raw2Sym;
+        const hasHc = hc !== undefined && hcCoord >= 0 && hc.moves.length > 0;
+        const hcMoves = hasHc ? hc.moves : null;
+        const hcDist = hasHc ? hc.distances : null;
+        const hcRow = hasHc ? hcCoord * hc_pdb_js_1.HC_PDB_MOVES.length : 0;
+        // Byte-expanded (tests/generators) vs nibble-packed (loaders) distances.
+        const edgeUnpacked = edge3Distances.length >= 31006080;
         for (let m = 0; m < 17; m++) {
             if (exports.ckmv3[lm][m]) {
                 m = exports.skipAxis3[m];
                 continue;
             }
-            const nc = center3Tables.moveTable[ct * center3_js_1.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) {
+                this.noteExcess(depth, prun1, prun1 > maxl && m < 14);
                 if (prun1 > maxl && m < 14)
                     m = exports.skipAxis3[m];
                 continue;
             }
-            const symIdx = (0, edge3_js_1.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) {
+                        this.noteExcess(depth, prunh, prunh > maxl && m < 14);
+                        if (prunh > maxl && m < 14)
+                            m = exports.skipAxis3[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) {
+                    this.noteExcess(depth, prunPair, prunPair > maxl && m < 14);
+                    if (prunPair > maxl && m < 14)
+                        m = exports.skipAxis3[m];
+                    continue;
+                }
+            }
+            const symIdx = (0, edge3_js_1.getMvSymFrom)(ep, ep, m, sym2Raw, sym2Mask, raw2Sym, symMvrot, symMvroto);
+            // 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) {
+                this.noteExcess(depth, prunx, prunx > maxl && m < 14);
                 if (prunx > maxl && m < 14)
                     m = exports.skipAxis3[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;
             }
         }
+        // Record failure in TT if node didn't abort due to node cap
+        if (this.nodeCount <= maxNodes && maxl >= 2) {
+            FastPhase3Solver.tt[slot] = keyHigh;
+            FastPhase3Solver.tt[slot + 1] = keyLow;
+            FastPhase3Solver.tt[slot + 2] = (FastPhase3Solver.epoch << 16) | (lm << 8) | maxl;
+            FastPhase3Solver.ttGen[(slot / 3) | 0] = this.callId;
+        }
         return false;
     }
     /**
-     * Search for a phase-3 solution with exact target length.
+     * Record an IDA* bound prune: 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.
      */
-    async solveLength(edge, ct3, edist, length3, center3Tables, edge3Distances) {
+    noteExcess(depth, childBound, skippedSiblings) {
+        const excess = skippedSiblings ? depth + childBound : depth + 1 + childBound;
+        if (excess < this.minExcess)
+            this.minExcess = excess;
+    }
+    /**
+     * Search for a phase-3 solution with exact target length (first found).
+     */
+    solveLength(edge, ct3, edist, length3, center3Tables, edge3Distances, maxNodes = 15000, hc, hcCoord = -1, c3PairDist) {
         this.tempep[0].set(edge);
-        if (await this.search(this.tempep[0], ct3, edist, length3, 20, 0, center3Tables, edge3Distances)) {
+        this.nodeCount = 0;
+        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) => exports.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) {
+        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, 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.callId = FastPhase3Solver.nextCallId();
+        let accepted = null;
+        const collect = {
+            limit,
+            examined: 0,
+            validate: (moves) => {
+                if (validate(moves)) {
+                    accepted = moves;
+                    return true;
+                }
+                if (!accepted)
+                    accepted = moves;
+                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, nodesUsed: this.nodeCount };
+        if (process.env.CUBE4_PROOF_STATS === "1") {
+            exports.proofStats.total++;
+            if (this.capped)
+                exports.proofStats.capped++;
+            if (this.limitHit)
+                exports.proofStats.limitHit++;
+            if (this.sawGoal)
+                exports.proofStats.sawGoal++;
+            if (this.ttTouched)
+                exports.proofStats.ttTouched++;
+        }
+        if (!this.capped &&
+            !this.limitHit &&
+            !this.sawGoal &&
+            !this.ttTouched &&
+            this.minExcess > length3 &&
+            this.minExcess !== Number.MAX_SAFE_INTEGER) {
+            if (process.env.CUBE4_PROOF_STATS === "1") {
+                exports.proofStats.clean++;
+                exports.proofStats.jumpSum += this.minExcess - 1 - length3;
+            }
+            return { moves: null, provenThrough: this.minExcess - 1, nodesUsed: this.nodeCount };
+        }
+        return { moves: null, provenThrough: length3, nodesUsed: this.nodeCount };
+    }
 }
 exports.FastPhase3Solver = FastPhase3Solver;
+/** Temporary instrumentation for proof-statistics (CUBE4_PROOF_STATS=1). */
+exports.proofStats = {
+    total: 0,
+    capped: 0,
+    limitHit: 0,
+    sawGoal: 0,
+    ttTouched: 0,
+    clean: 0,
+    jumpSum: 0
+};
+function resetProofStats() {
+    exports.proofStats.total = 0;
+    exports.proofStats.capped = 0;
+    exports.proofStats.limitHit = 0;
+    exports.proofStats.sawGoal = 0;
+    exports.proofStats.ttTouched = 0;
+    exports.proofStats.clean = 0;
+    exports.proofStats.jumpSum = 0;
+}
 const defaultSolver = new FastPhase3Solver();
 /**
  * Solve Phase 3 with iterative deepening on a single Phase3Start.