@cubingcenter/scrambler 0.6.3 → 0.7.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,79 +34,397 @@ 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]
+];
 export 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 = 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) => 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_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_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 (ckmv3[lm][m]) {
                 m = skipAxis3[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) {
+                this.noteExcess(depth, prun1, prun1 > maxl && m < 14);
                 if (prun1 > maxl && m < 14)
                     m = skipAxis3[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) {
+                        this.noteExcess(depth, prunh, prunh > maxl && m < 14);
+                        if (prunh > maxl && m < 14)
+                            m = 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 = skipAxis3[m];
+                    continue;
+                }
+            }
+            const symIdx = 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 = 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) => 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") {
+            proofStats.total++;
+            if (this.capped)
+                proofStats.capped++;
+            if (this.limitHit)
+                proofStats.limitHit++;
+            if (this.sawGoal)
+                proofStats.sawGoal++;
+            if (this.ttTouched)
+                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") {
+                proofStats.clean++;
+                proofStats.jumpSum += this.minExcess - 1 - length3;
+            }
+            return { moves: null, provenThrough: this.minExcess - 1, nodesUsed: this.nodeCount };
+        }
+        return { moves: null, provenThrough: length3, 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();
 /**

package/dist/puzzles/cube4/reduction/solve.d.ts

@@ -7,25 +7,136 @@ import type { Cube4State, Cube4Move } from "../types.js";
 import { type Center1Tables } from "./center1.js";
 import { type Center2Tables } from "./center2.js";
 import { type Center3Tables } from "./center3.js";
+import { type HcDenseTables } from "./hc-pdb.js";
 import { type Edge3Tables } from "./edge3.js";
 import type { Cube3State, Cube3Move } from "../../cube3/types.js";
+import type { Cube3Phase1Tables } from "../../cube3/solver/tables.js";
 export interface Cube4SolveTables {
     center1: Center1Tables;
     center2: Center2Tables;
     center3: Center3Tables;
     edge3: Edge3Tables;
+    cube3Phase1?: Cube3Phase1Tables;
+    /** Half-class exact PDB (optional; tightens the phase-3 root bound and node-level pruning). */
+    hc?: HcDenseTables;
+    /** Joint Center3 x Single Pair PDB distances (optional). */
+    c3PairDist?: Uint8Array;
 }
 export interface Cube4SolveResult {
     /** The complete solve sequence (solves the input state). */
     moves: Cube4Move[];
     /** The scramble (the inverted solution). */
     scramble: Cube4Move[];
+    /** Winning reduction breakdown (unsimplified lengths). */
+    phases?: {
+        length12: number;
+        length1: number;
+        length2: number;
+        length3: number;
+        finish: number;
+    };
+    /** Search work: phase-2 DFS nodes + phase-3 IDA* nodes this attempt. */
+    nodes?: {
+        p2: number;
+        p3: number;
+        f3calls: number;
+    };
+    /** Wall-clock split of this solve (reduction search / finish loop / polish). */
+    timings?: {
+        reductionMs: number;
+        f1Ms: number;
+        f2Ms: number;
+        f3Ms: number;
+        finishMs: number;
+        polishMs: number;
+    };
 }
+export declare function rotateAlgorithm(alg: readonly Cube4Move[], rotSeq: string[]): Cube4Move[];
+export declare function invertRotationSequence(rotSeq: string[]): string[];
+export declare function applyCubeRotation(state: Cube4State, rotSeq: string[]): Cube4State;
+export declare const P2_CANCEL: readonly (readonly boolean[])[];
+/** Temporary instrumentation for F2 goal statistics (CUBE4_F2_STATS=1). */
+export declare const f2Stats: {
+    goals: number;
+    transversalPass: number;
+    axisRejects: number;
+    minTransversalL2: number;
+    minChiralL2: number;
+};
+export declare function resetF2Stats(): void;
+/** Trigger rate for the stagnationCut early-stop (checks vs actual cuts). */
+export declare const stagnationStats: {
+    checks: number;
+    cuts: number;
+};
+export declare function resetStagnationStats(): void;
 /**
  * Solve a 4x4 state with the reduction solver + the cube3 two-phase finish.
  * `solveCube3` is injected (the cube3 solver loads its tables lazily).
+ *
+ * The search is bounded by deterministic work caps (candidate counts, node
+ * budgets, length caps), so `timeoutMs` is only a wall-clock backstop for
+ * pathological cases — not a quality filter. Attempt failures mean the
+ * state is outside the solver's horizon, never "ran out of time".
  */
+export interface Cube4SolveOptions {
+    /**
+     * Accepted for API compatibility but NOT enforced inside the search
+     * (deliberately: every loop is work-capped so the same state always
+     * takes the same path). Callers enforce their own wall-clock backstop
+     * around the call.
+     */
+    timeoutMs?: number;
+    /**
+     * Last-resort effort: widens every work cap (phase-2 depth/nodes,
+     * phase-3 budgets/lengths, pool caps). Only the fast path failing
+     * should trigger this — easy states never pay it.
+     */
+    deep?: boolean;
+    /** Phase-4 attempts among valid reductions (default 3, or centersBeam * edgesPerCenter). */
+    finishTries?: number;
+    /** Number of distinct center candidates from phase 2 to explore in phase 3 (default 3). */
+    centersBeam?: number | undefined;
+    /** Maximum number of distinct edge pairings to collect per center candidate in phase 3 (default 3). */
+    edgesPerCenter?: number | undefined;
+    /** Deep multi-candidate polish pass in Phase 3. */
+    deepPolish?: boolean | undefined;
+    /** Prune searches whose reduction exceeds this bound (branch-and-bound). */
+    maxReductionLen?: number | undefined;
+    /**
+     * Phase-2 wide move set: search all 28 center2 moves (adds
+     * Dw2/Lw/Lw2/Lw'/Bw2) with the `pruningWide` table instead of the
+     * default 23. Requires regenerated center2 tables; default false.
+     * (Measured: ~-0.2 moves for ~+15% time; keep opt-in.)
+     */
+    center2Wide?: boolean | undefined;
+    /**
+     * F1 enumeration depth beyond the per-axis optimum (default 3):
+     * collects up to `phase1Cap` F1 solutions of length <= minH + this,
+     * deliberately supra-optimal, to feed diverse F2/F3 candidates.
+     * (Measured: restricting to 0 shows no consistent benefit and
+     * interacts badly with center2Wide; keep the default.)
+     */
+    phase1ExtraDepths?: number | undefined;
+    /** F1 solution collection cap (default 60). */
+    phase1Cap?: number | undefined;
+    /** Phase-2 prep collection cap (default 100, or 160 in deep mode). */
+    prepCap?: number | undefined;
+    /** Max candidates to collect per (prep, length) DFS call (default 64, or 96 in deep mode). */
+    p1CandCap?: number | undefined;
+    /** Early stop when candidate pool has >= CAND_MIN and best value stagnates across 2 lengths. */
+    stagnationCut?: boolean | undefined;
+    /**
+     * Full-pipeline restarts over the SAME state (default 1): each restart
+     * re-runs phases 1-4 with a reshuffled search order (seeded by the state
+     * hash ^ restart index, so results stay deterministic) and the shortest
+     * simplified total wins. Same-state diversity preserves the sampled
+     * state's distribution — unlike bestOf, which samples new states.
+     * `1` keeps the legacy single deterministic pass bit-identical.
+     */
+    restarts?: number | undefined;
+}
 export declare function solveCube4State(state: Cube4State, tables: Cube4SolveTables, solveCube3: (state: Cube3State) => Promise<{
     moves: Cube3Move[];
-}>): Promise<Cube4SolveResult>;
+}>, options?: Cube4SolveOptions): Promise<Cube4SolveResult>;
 //# sourceMappingURL=solve.d.ts.map

package/dist/puzzles/cube4/reduction/solve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/solve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAKjE,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAIlE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAuKD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,GACjE,OAAO,CAAC,gBAAgB,CAAC,CAqL3B"}
+{"version":3,"file":"solve.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/solve.ts"],"names":[],"mappings":"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"}