@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist/puzzles/cube4/reduction/solve.js

@@ -3,17 +3,19 @@
  * (phase 4), returning the move sequence that solves the given state.
  * The scramble for a sampled state is the inverted solution.
  */
-import { applyCube4Algorithm, invertCube4Algorithm, simplifyCube4Algorithm } from "../moves.js";
+import { applyCube4Algorithm, invertCube4Algorithm } from "../moves.js";
 import { center1Mask, getCenter1Distance, applyCenter1Move, CENTER1_MOVES, CENTER1_GOAL_MASKS } from "./center1.js";
-import { center2Bridge, getWingMoveMaps, isCenter2Goal, CENTER2_MOVES, CENTER2_SEARCH_MOVES, CENTER2_SEARCH_MOVES_WIDE, CENTER2_RL_STATES } from "./center2.js";
+import { center2Bridge, getWingMoveMaps, CENTER2_GOAL_RL, CENTER2_MOVES, CENTER2_SEARCH_MOVES, CENTER2_SEARCH_MOVES_WIDE, CENTER2_RL_STATES, encodeCenter2ChiralCt, generateCenter2ChiralTables } from "./center2.js";
 import { encodeCenter3 } from "./center3.js";
-import { encodePairingState, hasPairingTransversal } from "./pairing-coordinate.js";
-import { encodeHcPdb } from "./hc-pdb.js";
+import { encodePairingState, PAIRING_SECOND_HALVES } from "./pairing-coordinate.js";
+import { encodeHcPdb, hcDenseIndex } from "./hc-pdb.js";
 import { getSymTables, getMvSymFrom } from "./edge3.js";
 import { FastPhase3Solver } from "./phase3-search.js";
+import { placeRotationFix } from "./rotation-fix.js";
+import { getTransversalPairPdb, getWingPositionMoves, PAIR_INDEX, PAIR_STATES } from "./pair-transversal.js";
 import { checkCube4Reduction, toCube3State } from "./phase4.js";
 import { encodeCornerOrientation, encodeEdgeOrientation, encodeUdSlice } from "../../cube3/solver/coordinates.js";
-import { createSolvedCube4State } from "../state.js";
+import { createSolvedCube4State, isSolvedCube4State } from "../state.js";
 function mulberry32(seed) {
     let a = seed >>> 0;
     return () => {
@@ -104,6 +106,29 @@ function getTriAxialCube3Heuristic(standardReduced, tables) {
     }
     return minH;
 }
+class Cube4SolveError extends Error {
+}
+export class Cube4Phase2CapError extends Cube4SolveError {
+    code = "cube4-phase2-cap";
+    constructor(message) {
+        super(message);
+        this.name = "Cube4Phase2CapError";
+    }
+}
+export class Cube4Phase3CapError extends Cube4SolveError {
+    code = "cube4-phase3-cap";
+    constructor(message) {
+        super(message);
+        this.name = "Cube4Phase3CapError";
+    }
+}
+export class Cube4FinishCapError extends Cube4SolveError {
+    code = "cube4-finish-cap";
+    constructor(message) {
+        super(message);
+        this.name = "Cube4FinishCapError";
+    }
+}
 function cornerPermutationParity(cp) {
     let parity = 0;
     const seen = new Array(8).fill(false);
@@ -183,6 +208,8 @@ const VALID_24_ORIENTATIONS = (() => {
     }
     return map;
 })();
+/** Centers of the solved state — used to verify a full (not just partial) standard orientation. */
+const SOLVED_CENTERS = createSolvedCube4State().centers;
 const ROT_MAP = {
     "x": { "U": "B", "R": "R", "F": "U", "D": "F", "L": "L", "B": "D" },
     "x'": { "U": "F", "R": "R", "F": "D", "D": "B", "L": "L", "B": "U" },
@@ -218,6 +245,10 @@ export function rotateAlgorithm(alg, rotSeq) {
         return current;
     });
 }
+/** Physical wide-move sequence implementing a whole-cube rotation. */
+export function cubeRotationMoves(rotSeq) {
+    return rotSeq.flatMap((rotation) => ROT_MOVES[rotation]);
+}
 export function invertRotationSequence(rotSeq) {
     return [...rotSeq].reverse().map((r) => INVERT_ROT[r]);
 }
@@ -258,6 +289,49 @@ function isCancelled(previous, current) {
 export const P2_CANCEL = CENTER2_SEARCH_MOVES.map((previous) => CENTER2_SEARCH_MOVES.map((current) => isCancelled(previous, current)));
 // Same over the wide 28-move set (used when `center2Wide` is set).
 const P2_CANCEL_WIDE = CENTER2_SEARCH_MOVES_WIDE.map((previous) => CENTER2_SEARCH_MOVES_WIDE.map((current) => isCancelled(previous, current)));
+/** Flat (row-major) cancel tables for the hot DFS loop; same semantics. */
+function flattenCancel(table) {
+    const n = table.length;
+    const flat = new Uint8Array(n * n);
+    for (let i = 0; i < n; i++) {
+        const row = table[i];
+        for (let j = 0; j < n; j++)
+            flat[i * n + j] = row[j] ? 1 : 0;
+    }
+    return flat;
+}
+const P2_CANCEL_FLAT = flattenCancel(P2_CANCEL);
+const P2_CANCEL_WIDE_FLAT = flattenCancel(P2_CANCEL_WIDE);
+/**
+ * Wing transversal mask: bit k set iff pair k occupies a second-half slot.
+ * `hasPairingTransversal(wp)` is equivalent to `pairingMaskOf(wp) === 0xfff`
+ * (12 slots, 12 pair ids in 0..11: all distinct ⟺ all 12 bits set). The mask
+ * form is O(1) at the millions of phase-2 goal leaves.
+ */
+function pairingMaskOf(wp) {
+    let mask = 0;
+    for (let i = 0; i < 12; i++) {
+        mask |= 1 << (wp[PAIRING_SECOND_HALVES[i]] >> 1);
+    }
+    return mask;
+}
+/** rl side of the phase-2 goal test (same flags as `isCenter2Goal`). */
+const P2_GOAL_RL = (() => {
+    const flags = new Uint8Array(CENTER2_RL_STATES);
+    for (const rl of CENTER2_GOAL_RL)
+        flags[rl] = 1;
+    return flags;
+})();
+/** Chiral phase-2 tables, generated once per loaded center2 table set. */
+const chiralTablesCache = new WeakMap();
+function getCenter2ChiralTables(center2) {
+    let chiral = chiralTablesCache.get(center2);
+    if (!chiral) {
+        chiral = generateCenter2ChiralTables(center2.rlMove);
+        chiralTablesCache.set(center2, chiral);
+    }
+    return chiral;
+}
 const SKIP_AXIS_2 = new Int32Array(CENTER2_SEARCH_MOVES.length);
 for (let i = 0; i < CENTER2_SEARCH_MOVES.length; i++) {
     const m1 = CENTER2_SEARCH_MOVES[i];
@@ -274,7 +348,6 @@ for (let i = 0; i < CENTER2_SEARCH_MOVES.length; i++) {
         }
     }
 }
-const phase3Solver = new FastPhase3Solver();
 /** Temporary instrumentation for F2 goal statistics (CUBE4_F2_STATS=1). */
 export const f2Stats = { goals: 0, transversalPass: 0, axisRejects: 0, minTransversalL2: 99, minChiralL2: 99 };
 export function resetF2Stats() {
@@ -290,13 +363,38 @@ export function resetStagnationStats() {
     stagnationStats.checks = 0;
     stagnationStats.cuts = 0;
 }
+/**
+ * Temporary instrumentation for the finish-skip bound (CUBE4_FINISH_STATS=1):
+ * `gap = totalEst - finalLen` per finished reduction. A skip
+ * `totalEst - SLACK >= minTotalMoves` is only sound while SLACK covers the
+ * observed gap maximum (junction cancellation + finish-vs-h3 slack).
+ */
+export const finishStats = {
+    gapMin: 99,
+    gapMax: -99,
+    gapSum: 0,
+    gapN: 0,
+    finishes: 0,
+    skipped: 0
+};
+/**
+ * Temporary instrumentation for the rotMoves cost (CUBE4_ROT_STATS=1):
+ * per built reduction records the prep frame rotation, the derived
+ * normalization rotation and the emitted fix length.
+ */
+export const rotStats = [];
 export async function solveCube4State(state, tables, solveCube3, options) {
     // NOTE: no wall-clock deadline inside the search — all loops are bounded
-    // by deterministic work caps (node counts, candidate counts, length
-    // caps), so the same state always takes the same path. The caller keeps
-    // its own backstop (`timeoutMs` handled at the call site).
+    // by deterministic work caps (node counts, candidate counts, length caps),
+    // so the same state always takes the same path.
     const sym = getSymTables();
+    // All mutable phase-3 state (TT, epoch-node count, call IDs and search
+    // stacks) belongs to this invocation. The same instance spans its
+    // deterministic restarts, retaining useful goal-free TT entries without
+    // allowing concurrent solves to contaminate one another.
+    const phase3Solver = new FastPhase3Solver();
     phase3Solver.resetEpochNodes();
+    const collectF2Stats = typeof process !== "undefined" && process.env?.CUBE4_F2_STATS === "1";
     const totalRestarts = Math.max(1, Math.floor(options?.restarts ?? 1));
     // Cross-restart work accumulators (reported in nodes/timings).
     let accP2 = 0;
@@ -321,8 +419,8 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         const path = [];
         const p1Extra = options?.phase1ExtraDepths ?? 3;
         const p1Cap = options?.phase1Cap ?? 400;
-        // Per-restart DFS traversal order (identity when rng is null).
-        const p1Order = restartOrder(CENTER1_MOVES.length, rng);
+        // Per-restart DFS traversal order (null = identity fast path when rng is null).
+        const p1Order = rng === null ? null : Int32Array.from(restartOrder(CENTER1_MOVES.length, rng));
         for (let maxD = minOverallH; maxD <= minOverallH + p1Extra; maxD++) {
             for (const urf of [0, 1, 2]) {
                 const minH = urfDistances[urf];
@@ -359,7 +457,7 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                     if (depth + h > maxD)
                         return false;
                     for (let mi = 0; mi < CENTER1_MOVES.length; mi++) {
-                        const mv = p1Order[mi];
+                        const mv = p1Order === null ? mi : p1Order[mi];
                         if (lm >= 0 && Math.floor(lm / 3) === Math.floor(mv / 3))
                             continue;
                         const next = applyCenter1Move(m, tables.center1.moveMaps, mv);
@@ -378,12 +476,24 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         const minP1 = p1Sols[0]?.moves.length ?? 0;
         const tF1End = performance.now();
         const candidates = [];
-        const moveLog = new Array(25);
+        const moveLog = new Int32Array(48);
         // Incremental wing tracking stack for phase-2 goal transversal checks:
         // avoids full 6-7 move replaying from scratch across hundreds of thousands of candidate goals.
-        const wpStack = Array.from({ length: 24 }, () => new Uint8Array(24));
+        // `wpMaskStack[d]` = pairingMaskOf(wpStack[d]) maintained in the same lazy
+        // fill, so the per-leaf transversal test is a single compare.
+        const wpStack = Array.from({ length: 32 }, () => new Uint8Array(24));
+        const wpMaskStack = new Int32Array(32);
         let validWpDepth = 0;
         const wingMaps = getWingMoveMaps();
+        // Transversal pruning (see pair-transversal.ts): wing positions per DFS
+        // depth (`posStack[d][wing]`), checked against the two-pair PDB over 6
+        // disjoint pair-of-pairs in the last TRANSVERSAL_DEPTH levels (the PDB's
+        // maximum). Prunes only branches with no transversal goal, so the
+        // accepted candidates are unchanged.
+        const posStack = Array.from({ length: 33 }, () => new Uint8Array(24));
+        const wingPosMove = getWingPositionMoves();
+        const TRANSVERSAL_DEPTH = 3;
+        let validPosDepth = 0;
         /**
          * Anti-hang work cap for the phase-2 search (successful attempts use
          * ~0.1-0.3M nodes; this only aborts pathological explorations).
@@ -396,11 +506,21 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         // indices in either mode.
         const c2Wide = options?.center2Wide === true;
         const C2_SEARCH = c2Wide ? CENTER2_SEARCH_MOVES_WIDE : CENTER2_SEARCH_MOVES;
-        const C2_CANCEL = c2Wide ? P2_CANCEL_WIDE : P2_CANCEL;
-        // Per-restart child order (identity when rng is null). Entries stay
+        const cancelFlat = c2Wide ? P2_CANCEL_WIDE_FLAT : P2_CANCEL_FLAT;
+        const c2Stride = C2_SEARCH.length;
+        const transversalPdb = getTransversalPairPdb(C2_SEARCH.length);
+        const canSkipAxis = rng === null && !c2Wide;
+        // Per-restart child order (null = identity fast path). Entries stay
         // original move-table indices, so all table lookups are unaffected.
-        const p2Order = restartOrder(C2_SEARCH.length, rng);
-        let c2pruning = tables.center2.pruning;
+        const p2Order = rng === null ? null : Int32Array.from(restartOrder(C2_SEARCH.length, rng));
+        // Default set: chiral tables (goal = ct == 0 && axisDet == 1 exactly, so
+        // wrong-chirality goal paths are pruned instead of enumerated). The wide
+        // set keeps the relative tables + the axisDet filter at the goal.
+        const chiral = c2Wide ? null : getCenter2ChiralTables(tables.center2);
+        const c2ctMove = chiral ? chiral.ctMove : tables.center2.ctMove;
+        const c2rlMove = tables.center2.rlMove;
+        const c2GoalCt = chiral ? chiral.goalCt : 0;
+        let c2pruning = chiral ? chiral.pruning : tables.center2.pruning;
         if (c2Wide) {
             if (!tables.center2.pruningWide) {
                 throw new Error("4x4 solve: center2Wide requested but pruningWide tables are not loaded — regenerate center2 tables.");
@@ -408,6 +528,8 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             c2pruning = tables.center2.pruningWide;
         }
         const P2_MAX_NODES = deep ? 24_000_000 : 8_000_000;
+        // Hoisted out of the goal path (was read per goal leaf).
+        const maxP1Cand = options?.p1CandCap !== undefined ? options.p1CandCap : (deep ? 24 : 16);
         // Smaller pool + shorter extension (was 180/100/14/12 on the fast path):
         // the deep length2 levels are where F2 tails burn. Validated on a 44-state
         // corpus: -16% nodes, identical average length (one +1 in 44).
@@ -421,11 +543,16 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         const EXT_MX = deep ? 20 : 16;
         let p2nodes = 0;
         let f3calls = 0;
+        // Bound the whole sweep, not just each individual IDA* call. A hard
+        // candidate pool can otherwise spend thousands of capped calls before
+        // reaching the deep retry (corpus-73: 114M nodes in the fast attempt).
+        const phase3StartNodes = phase3Solver.epochNodes;
+        const phase3NodeBudget = deep ? 16_000_000 : 4_000_000;
         function searchPhase2(c, r, maxl, lm, depth, bridgeState, prep) {
             p2nodes++;
             if (p2nodes > P2_MAX_NODES)
                 return false;
-            if (isCenter2Goal(c, r)) {
+            if (c === c2GoalCt && P2_GOAL_RL[r] === 1) {
                 if (maxl === 0) {
                     while (validWpDepth < depth) {
                         const m = moveLog[validWpDepth];
@@ -434,30 +561,34 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                         const dst = wpStack[validWpDepth + 1];
                         for (let i = 0; i < 24; i++)
                             dst[i] = src[wingMaps[base + i]];
+                        wpMaskStack[validWpDepth + 1] = pairingMaskOf(dst);
                         validWpDepth++;
                     }
-                    const goalWp = wpStack[depth];
-                    if (process.env.CUBE4_F2_STATS === "1")
+                    if (collectF2Stats)
                         f2Stats.goals++;
-                    if (!hasPairingTransversal(goalWp))
+                    // Bit-identical to `hasPairingTransversal(goalWp)`: all 12 pair bits
+                    // distinct ⟺ the 12-bit mask is full (0xfff).
+                    if (wpMaskStack[depth] !== 0xfff)
                         return false;
-                    if (process.env.CUBE4_F2_STATS === "1")
+                    if (collectF2Stats)
                         f2Stats.transversalPass++;
-                    const moves2 = moveLog.slice(0, depth).map((m) => CENTER2_MOVES[m]);
+                    const moves2 = [];
+                    for (let i = 0; i < depth; i++)
+                        moves2.push(CENTER2_MOVES[moveLog[i]]);
                     const s2 = applyCube4Algorithm(bridgeState, moves2);
                     const uAxis = s2.centers[0] % 3;
                     const rAxis = s2.centers[4] % 3;
                     const fAxis = s2.centers[8] % 3;
-                    if (process.env.CUBE4_F2_STATS === "1") {
+                    if (collectF2Stats) {
                         if (depth < f2Stats.minTransversalL2)
                             f2Stats.minTransversalL2 = depth;
                     }
                     if (axisDet(uAxis, rAxis, fAxis) !== 1) {
-                        if (process.env.CUBE4_F2_STATS === "1")
+                        if (collectF2Stats)
                             f2Stats.axisRejects++;
                         return false;
                     }
-                    if (process.env.CUBE4_F2_STATS === "1") {
+                    if (collectF2Stats) {
                         if (depth < f2Stats.minChiralL2)
                             f2Stats.minChiralL2 = depth;
                     }
@@ -477,7 +608,7 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                             const moves2Remapped = prep.totalRot.length === 0
                                 ? moves2
                                 : rotateAlgorithm(moves2, invertRotationSequence(prep.totalRot));
-                            const hcCoord = tables.hc ? tables.hc.index[encodeHcPdb(s2.centers)] : -1;
+                            const hcCoord = tables.hc ? hcDenseIndex(tables.hc, encodeHcPdb(s2.centers)) : -1;
                             const hcRaw = hcCoord >= 0 && tables.hc ? tables.hc.distances[hcCoord] : 0;
                             const hdist = hcRaw === 0x0f ? 0 : hcRaw;
                             let pdist = 0;
@@ -524,7 +655,6 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                                 }
                             }
                             p1CandCount++;
-                            const maxP1Cand = options?.p1CandCap !== undefined ? options.p1CandCap : (deep ? 96 : 64);
                             if (p1CandCount >= maxP1Cand)
                                 return true;
                         }
@@ -534,27 +664,65 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             }
             if (maxl === 0)
                 return false;
-            const c2ctMove = tables.center2.ctMove;
-            const c2rlMove = tables.center2.rlMove;
             const c2RowC = c * CENTER2_MOVES.length;
             const c2RowR = r * CENTER2_MOVES.length;
             for (let mi = 0; mi < C2_SEARCH.length; mi++) {
-                const m = p2Order[mi];
-                if (lm >= 0 && C2_CANCEL[lm][m]) {
+                const m = p2Order === null ? mi : p2Order[mi];
+                if (lm >= 0 && cancelFlat[lm * c2Stride + m]) {
                     continue;
                 }
                 const nc = c2ctMove[c2RowC + m];
                 const nr = c2rlMove[c2RowR + m];
                 const prun = c2pruning[nc * CENTER2_RL_STATES + nr];
                 if (prun >= maxl) {
-                    if (prun > maxl && rng === null && !c2Wide) {
+                    if (prun > maxl && canSkipAxis) {
                         mi = SKIP_AXIS_2[m] - 1;
                     }
                     continue;
                 }
+                let childPosValid = false;
+                if (maxl - 1 < TRANSVERSAL_DEPTH) {
+                    // Lazy fill (like wpStack): replay the path down to this node.
+                    while (validPosDepth < depth) {
+                        const src = posStack[validPosDepth];
+                        const dst = posStack[validPosDepth + 1];
+                        const row = moveLog[validPosDepth] * 24;
+                        for (let w = 0; w < 24; w++)
+                            dst[w] = wingPosMove[row + src[w]];
+                        validPosDepth++;
+                    }
+                    const parentPos = posStack[depth];
+                    const childPos = posStack[depth + 1];
+                    const posRow = m * 24;
+                    const limit = maxl - 1;
+                    let blocked = false;
+                    // Group by group (4 wings = 2 pairs each), so a blocked child only
+                    // pays for the groups actually checked.
+                    for (let q = 0; q < 24; q += 4) {
+                        const a0 = wingPosMove[posRow + parentPos[q]];
+                        const a1 = wingPosMove[posRow + parentPos[q + 1]];
+                        const b0 = wingPosMove[posRow + parentPos[q + 2]];
+                        const b1 = wingPosMove[posRow + parentPos[q + 3]];
+                        if (transversalPdb[PAIR_INDEX[a0 * 24 + a1] * PAIR_STATES + PAIR_INDEX[b0 * 24 + b1]] > limit) {
+                            blocked = true;
+                            break;
+                        }
+                        childPos[q] = a0;
+                        childPos[q + 1] = a1;
+                        childPos[q + 2] = b0;
+                        childPos[q + 3] = b1;
+                    }
+                    if (blocked)
+                        continue;
+                    childPosValid = true;
+                }
                 moveLog[depth] = m;
                 if (validWpDepth > depth)
                     validWpDepth = depth;
+                if (validPosDepth > depth)
+                    validPosDepth = depth;
+                if (childPosValid)
+                    validPosDepth = depth + 1;
                 if (searchPhase2(nc, nr, maxl - 1, m, depth + 1, bridgeState, prep))
                     return true;
             }
@@ -576,7 +744,8 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                 continue;
             const totalRot = [...p1.rotAlign, ...bridge.rotation];
             const prefix = p1.moves;
-            const prun = c2pruning[bridge.encoded.ct * CENTER2_RL_STATES + bridge.encoded.rl];
+            const ct = chiral ? encodeCenter2ChiralCt(bridge.state) : bridge.encoded.ct;
+            const prun = c2pruning[ct * CENTER2_RL_STATES + bridge.encoded.rl];
             // Paired wings lookahead: check how many wings are already paired in bridge.state
             let pairedWings = 0;
             const wp = bridge.state.wp;
@@ -588,13 +757,13 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             // Lookahead composite score: total estimated centers penalized by already-paired wings
             const estCenters = prefix.length + prun;
             const score = estCenters * 2 - Math.min(4, pairedWings);
-            preps.push({ p1, prefix, bridgeState: bridge.state, totalRot, ct: bridge.encoded.ct, rl: bridge.encoded.rl, prun, score });
+            preps.push({ p1, prefix, bridgeState: bridge.state, totalRot, ct, rl: bridge.encoded.rl, prun, score });
         }
         // Ascending lookahead score (lowest total estimated center moves + wing bonus),
         // tie-broken by lower phase-2 pruning bound then shorter prefix length
         preps.sort((a, b) => (a.score - b.score) || (a.prun - b.prun) || (a.prefix.length - b.prefix.length));
         // Filter: keep the best preps to avoid wasting phase-2 DFS work on suboptimal centers
-        const PREP_CAP = options?.prepCap !== undefined ? options.prepCap : (deep ? 160 : 100);
+        const PREP_CAP = options?.prepCap !== undefined ? options.prepCap : (deep ? 48 : 32);
         if (preps.length > PREP_CAP) {
             preps.length = PREP_CAP;
         }
@@ -626,6 +795,10 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                     searchedL2.add(key);
                     p1CandCount = 0;
                     wpStack[0].set(prep.bridgeState.wp);
+                    for (let p = 0; p < 24; p++)
+                        posStack[0][prep.bridgeState.wp[p]] = p;
+                    validPosDepth = 0;
+                    wpMaskStack[0] = pairingMaskOf(prep.bridgeState.wp);
                     validWpDepth = 0;
                     searchPhase2(prep.ct, prep.rl, length2, -1, 0, prep.bridgeState, prep);
                     if (candidates.length >= CAND_CAP &&
@@ -660,9 +833,13 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             MAX_P2++;
         } while ((candidates.length === 0 && MAX_P2 <= P2_MAX_ABS) || (candidates.length < CAND_MIN && MAX_P2 <= P2_MAX_MIN));
         if (candidates.length === 0) {
-            throw new Error("4x4 solve: no valid phase 2 candidates found.");
+            throw new Cube4Phase2CapError("4x4 solve: no valid phase 2 candidates found.");
         }
         const tF2End = performance.now();
+        // Cheap-fix goal filter (see Cube4SolveOptions.maxFixMoves). The deep
+        // fallback widens it back to 4 (legacy, always satisfiable) so a hard
+        // state can never fail on the filter alone.
+        const maxFixMoves = (options?.maxFixMoves ?? 4) + (deep ? 2 : 0);
         const validReductions = [];
         /**
          * Per-candidate IDA* proofs shared across all sweep stages: the greatest
@@ -691,31 +868,50 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                 return null;
             const rotToStandard = invertRotationSequence(path);
             const standardReduced = applyCubeRotation(reducedOriginal, rotToStandard);
-            const cube3State = toCube3State(standardReduced);
-            if (!cube3State) {
-                console.log("    toCube3State failed!");
+            const rotMoves = rotToStandard.flatMap((r) => ROT_MOVES[r]);
+            if (rotMoves.length > maxFixMoves)
                 return null;
+            if (typeof process !== "undefined" && process.env?.CUBE4_ROT_STATS === "1" && rotStats.length < 200) {
+                rotStats.push({
+                    totalRot: totalRot.join(","),
+                    rotToStandard: rotToStandard.join(","),
+                    rotLen: rotToStandard.reduce((n, rr) => n + ROT_MOVES[rr].length, 0)
+                });
             }
+            // The orientation key only covers 3 of the 24 center slots. A reduced
+            // arrangement outside the rotation orbit (e.g. a reflected one) can
+            // collide with a rotation's key, in which case rotating by `path` does
+            // NOT leave standard centers — the 3x3 finish would solve a different
+            // color scheme and the resulting solution would be garbage. Reject.
+            for (let i = 0; i < 24; i++) {
+                if (standardReduced.centers[i] !== SOLVED_CENTERS[i])
+                    return null;
+            }
+            const cube3State = toCube3State(standardReduced);
+            if (!cube3State)
+                return null;
             const h3 = tables.cube3Phase1 ? getTriAxialCube3Heuristic(standardReduced, tables.cube3Phase1) : 0;
-            const reductionMoves = [
-                ...rotateAlgorithm(cand.moves12, rotToStandard),
-                ...rotateAlgorithm(moves3Remapped, rotToStandard)
-            ];
-            const simplifiedReduction = simplifyCube4Algorithm(reductionMoves);
+            // The reduction + rotation prefix as it will be emitted (original frame):
+            // apply(state, [...moves12, ...moves3Remapped ... rotMoves]) = standardReduced.
+            // Priced with the fix at its best position (see placeRotationFix).
+            const simplifiedReduction = placeRotationFix([...cand.moves12, ...moves3Remapped], rotToStandard, []);
             return {
                 cand,
                 moves3,
                 moves3Remapped,
                 rotPath: path,
                 rotToStandard,
-                rotMoves: rotToStandard.flatMap((r) => ROT_MOVES[r]),
+                rotMoves,
                 standardReduced,
                 h3,
                 totalEst: simplifiedReduction.length + h3
             };
         }
-        const centersBeam = Math.max(1, options?.centersBeam ?? 3);
-        const edgesPerCenter = Math.max(1, options?.edgesPerCenter ?? 3);
+        // Defaults 1 × 5 (was 3 × 3): with the continuous finish, extra center
+        // candidates stopped paying. cc:0..31: 45.19 moves @ 673 ms vs 45.16 @
+        // 1042 ms (2×3: 45.25 @ 799; 1×8: 45.25 @ 691).
+        const centersBeam = Math.max(1, options?.centersBeam ?? 1);
+        const edgesPerCenter = Math.max(1, options?.edgesPerCenter ?? 5);
         const maxReductionsTarget = options?.finishTries !== undefined
             ? Math.max(1, options.finishTries)
             : (centersBeam * edgesPerCenter);
@@ -733,8 +929,14 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             const candReductions = new Map();
             const distinctCenters = new Set();
             let foundAtLength = null;
+            // The rotation fix (rotMoves) is priced INTO totalEst and varies 2-4
+            // moves per goal PATH (the end scheme depends on the path). A goal one
+            // total-step deeper with a 2-move fix beats a shallow goal with a 4-move
+            // fix, so keep collecting a few steps past the first find and let
+            // totalEst decide (was: foundAtLength + 1 with needed + 3 goals per
+            // call, which discarded fix-cheap alternatives).
             OUTER_P3: for (let length123 = pool[0].value; length123 < L123_CAP; length123++) {
-                if (foundAtLength !== null && length123 > foundAtLength + 1)
+                if (foundAtLength !== null && length123 > foundAtLength + 3)
                     break;
                 // Sweep the whole (sorted) pool: see sortTop rationale.
                 for (let i = 0; i < pool.length; i++) {
@@ -755,19 +957,34 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                     if (distinctCenters.size >= centersBeam && !distinctCenters.has(cand))
                         continue;
                     if (cand.edist <= length3 && cand.cdist <= length3 && cand.hdist <= length3 && (cand.pdist ?? 0) <= length3) {
-                        const nodeLimit = length3 <= 12 ? 80000 : Math.max(45000, cfg.maxNodes);
+                        const remainingNodes = phase3NodeBudget - (phase3Solver.epochNodes - phase3StartNodes);
+                        if (remainingNodes <= 0) {
+                            if (validReductions.length > 0)
+                                return;
+                            throw new Cube4Phase3CapError("4x4 solve: phase 3 total node budget exhausted.");
+                        }
+                        const nodeLimit = Math.min(remainingNodes, length3 <= 12 ? 80000 : Math.max(45000, cfg.maxNodes));
                         f3calls++;
-                        const validsBefore = validReductions.length;
                         const needed = edgesPerCenter - candCount;
                         const candReductionsBuffer = [];
-                        const maxToCollect = Math.min(16, needed + 3);
-                        const result = phase3Solver.solveLengthProven(cand.edge, cand.ct3, cand.edist, length3, tables.center3, tables.edge3.distances, nodeLimit, 16, (moves3) => {
+                        // Collect beyond `needed`: goal paths at the same length carry
+                        // different rotation fixes (2 vs 4 moves), and the totalEst sort
+                        // below needs the variety to pick a cheap-fix end.
+                        const maxToCollect = Math.min(24, needed + 9);
+                        const result = phase3Solver.solveLengthProven(cand.edge, cand.ct3, cand.edist, length3, tables.center3, tables.edge3.distances, nodeLimit, 
+                        // Goal budget per call: with the cheap-fix filter most goal ends
+                        // are rejected, so the walk must be allowed to examine more of
+                        // them before giving up on this (candidate, length3).
+                        48, (moves3) => {
                             const red = buildValidReduction(cand, moves3);
                             if (!red)
                                 return false;
                             candReductionsBuffer.push(red);
-                            if (foundAtLength === null)
-                                foundAtLength = length123;
+                            // <=-search: goals may land shorter than the length3 bound —
+                            // track the true total for the post-find collection window.
+                            const total = cand.length12 + moves3.length;
+                            if (foundAtLength === null || total < foundAtLength)
+                                foundAtLength = total;
                             return candReductionsBuffer.length >= maxToCollect;
                         }, 
                         // hc mid-search prune disabled: on a 44-state corpus the per-node
@@ -787,20 +1004,18 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                             candReductions.set(cand, candCount + toAdd.length);
                             distinctCenters.add(cand);
                         }
-                        const proven = result.provenThrough;
-                        if (process.env.CUBE4_SWEEP_STATS === "1") {
-                            // eslint-disable-next-line no-console
-                            console.log(`sweep l12=${cand.length12} l3=${length3} nodes=${result.nodesUsed}/${nodeLimit} ` +
-                                `valid=${validReductions.length > validsBefore} proven=${proven} ` +
-                                `c=${cand.cdist} e=${cand.edist} h=${cand.hdist}`);
-                        }
+                        // Predicate-scoped proof (same buildValidReduction filter for this
+                        // candidate across all its calls): skip every settled length.
+                        const proven = result.validatedThrough;
                         if (result.moves === null && proven >= length3) {
                             const prev = p3Proven.get(cand) ?? -1;
                             if (proven > prev)
                                 p3Proven.set(cand, proven);
                         }
                         // The finish loop attempts reductions up to maxReductionsTarget
-                        if (validReductions.length >= maxReductionsTarget) {
+                        // (with a wider collection cap so cheap-fix ends at later length
+                        // steps can still displace expensive-fix ones by totalEst).
+                        if (validReductions.length >= maxReductionsTarget + 9) {
                             break OUTER_P3;
                         }
                     }
@@ -819,10 +1034,10 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         };
         // Sweeps with growing budgets; longitudes extend dynamically (reference
         // style) while nothing is found, instead of fixed caps. Easy states only
-        // pay the first sweep.
-        // Sweeps with growing budgets; longitudes extend dynamically (reference
-        // style) while nothing is found, instead of fixed caps. Easy states only
-        // pay the first sweep.
+        // pay the first sweep. The length3 caps are NOT redundant re-walks: the
+        // ladder widens the pairing cap ONLY when nothing was found at all, and the
+        // narrower caps keep early sweeps on short pairings (measured: a single
+        // merged sweep with maxLength3 24 is ~20% SLOWER with identical output).
         // NOTE: lowering these caps was tried (20k/16k) and reverted: capped calls
         // change which valids are found (±2 moves on the corpus). Only admissible
         // heuristic strengthenings are length-safe here.
@@ -865,6 +1080,10 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                         searchedL2.add(key);
                         p1CandCount = 0;
                         wpStack[0].set(prep.bridgeState.wp);
+                        for (let p = 0; p < 24; p++)
+                            posStack[0][prep.bridgeState.wp[p]] = p;
+                        validPosDepth = 0;
+                        wpMaskStack[0] = pairingMaskOf(prep.bridgeState.wp);
                         validWpDepth = 0;
                         searchPhase2(prep.ct, prep.rl, length2, -1, 0, prep.bridgeState, prep);
                         if (candidates.length - poolStart >= 40)
@@ -882,7 +1101,7 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             }
         }
         if (validReductions.length === 0) {
-            throw new Error("4x4 solve: reduction failed across all candidates.");
+            throw new Cube4Phase3CapError("4x4 solve: phase 3 reduction failed across all candidates.");
         }
         // Sort reductions by Total Estimated Moves (Reduction length + 3x3 Phase 1 lower bound)
         validReductions.sort((a, b) => a.totalEst - b.totalEst);
@@ -897,28 +1116,56 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         // Best-of among the first three (phase-4 is cheap now); further
         // reductions are only attempted when those all failed.
         const finishTries = options?.finishTries ?? maxReductionsTarget;
-        for (let i = 0; i < validReductions.length; i++) {
-            if (i >= finishTries && bestSolution)
-                break;
-            const red = validReductions[i];
+        const collectFinishStats = typeof process !== "undefined" && process.env?.CUBE4_FINISH_STATS === "1";
+        // Empirical finish lower bound (see finishStats): every observed finish
+        // ran 11-16 moves ABOVE `totalEst` (continuous finish: 67 finishes over 16
+        // seeds, gap = totalEst - finalLen in [-16, -11]; the legacy finish was
+        // [-16, -12]) because `h3` only bounds the cube3 PHASE-1 length while the
+        // finish is two-phase. A reduction whose totalEst + 11 cannot strictly
+        // beat the current best therefore cannot win, and its finish is skipped
+        // entirely. If a state ever lands a finish within 11 of the phase-1 bound,
+        // this degrades to a slightly longer (still exact,
+        // still valid) scramble for that state — never an incorrect one.
+        const FINISH_LB_BIAS = 11;
+        const screenTop = Math.max(0, Math.floor(options?.finishScreenTop ?? 0));
+        const screened = [];
+        /** Finishes one reduction; records it as the best when shorter. */
+        async function finishReduction(red, effort) {
             const cube3State = toCube3State(red.standardReduced);
             if (!cube3State)
-                continue;
+                return null;
             let cube3Solution;
             try {
-                cube3Solution = await solveCube3(cube3State);
+                cube3Solution = await solveCube3(cube3State, effort);
             }
             catch {
-                continue;
+                return null;
+            }
+            // Frame invariant (verified): apply(state, [...moves12, ...moves3Remapped])
+            // is exactly `reducedOriginal`, and `reducedOriginal · rotMoves(r)`
+            // (= applyCubeRotation(_, r)) is `standardReduced`, which the cube3
+            // finish C solves. So the solution in the ORIGINAL frame is
+            //   X ++ rotMoves(r) ++ C.
+            // Two previously-tried assemblies are WRONG:
+            //  - [rot_r(X), C] solves ρ_r(state), not state (the observed adaptive
+            //    whole-cube-rotation bug: apply(solved, invert(moves)) = ρ_r(T));
+            //  - [X, rot_{-r}(C)] lands on ρ_{-r}(solved) ≠ solved, because a
+            //    whole-cube rotation does NOT leave the canonical solved state
+            //    invariant (it permutes face colors in the absolute frame).
+            // `placeRotationFix` keeps that effect but may move the rotMoves(r)
+            // block anywhere in the sequence (re-mapping what follows it) where it
+            // cancels against adjacent wide moves.
+            const simplified = placeRotationFix([...red.cand.moves12, ...red.moves3Remapped], red.rotToStandard, cube3Solution.moves);
+            if (collectFinishStats) {
+                finishStats.finishes++;
+                const gap = red.totalEst - simplified.length;
+                if (gap < finishStats.gapMin)
+                    finishStats.gapMin = gap;
+                if (gap > finishStats.gapMax)
+                    finishStats.gapMax = gap;
+                finishStats.gapSum += gap;
+                finishStats.gapN++;
             }
-            // Rotate the solve algorithm so it is performed from the standard orientation ("hacer los movimientos desde otro lado").
-            // This allows the solve to transition directly to the standard solved state WITHOUT ANY WHOLE-CUBE ROTATIONS (rotMoves)!
-            const rotatedFullSolution = [
-                ...rotateAlgorithm(red.cand.moves12, red.rotToStandard),
-                ...rotateAlgorithm(red.moves3Remapped, red.rotToStandard),
-                ...cube3Solution.moves
-            ];
-            const simplified = simplifyCube4Algorithm(rotatedFullSolution);
             if (simplified.length < minTotalMoves) {
                 minTotalMoves = simplified.length;
                 bestSolution = simplified;
@@ -931,9 +1178,31 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                 };
                 bestRed = red;
             }
+            return simplified;
+        }
+        for (let i = 0; i < validReductions.length; i++) {
+            if (i >= finishTries && bestSolution)
+                break;
+            const red = validReductions[i];
+            if (bestSolution !== null && red.totalEst + FINISH_LB_BIAS >= minTotalMoves) {
+                finishStats.skipped++;
+                continue;
+            }
+            const done = await finishReduction(red, screenTop > 0 ? "screen" : "full");
+            if (done)
+                screened.push({ red, total: done.length });
+        }
+        // Stage 2: the best screened reductions get the full-effort finish.
+        if (screenTop > 0) {
+            screened.sort((a, b) => a.total - b.total);
+            for (const { red } of screened.slice(0, screenTop)) {
+                if (red.totalEst + FINISH_LB_BIAS >= minTotalMoves)
+                    continue;
+                await finishReduction(red, "full");
+            }
         }
         if (!bestSolution || !bestRed) {
-            throw new Error("4x4 solve: reduction failed across all candidates.");
+            throw new Cube4FinishCapError("4x4 solve: reduction failed during the 3x3 finish across all valid reductions.");
         }
         // Polish pass: the sweep takes the first valid sequence per exact
         // length, which is often one above optimal. Retry the winner one length
@@ -953,13 +1222,23 @@ export async function solveCube4State(state, tables, solveCube3, options) {
             // and a full 150k grind on tail states cost seconds for nothing. It is
             // also skipped entirely unless the total is high enough to matter.
             const polishBudget = r === bestRed ? 150000 : 30000;
+            // NOTE: with the <=-length phase-3 search the sweep already enumerates
+            // shorter goals, so the polish is a second-chance pass only (measured:
+            // a wider gate/budget found nothing and cost +32% p3 nodes).
             for (let iter = 0; iter < 4 && (minTotalMoves > 43 || curRed.moves3.length > 11); iter++) {
                 const cand = curRed.cand;
                 const shorterLen = curRed.moves3.length - 1;
                 if (shorterLen < cand.edist || shorterLen < cand.cdist || shorterLen < cand.hdist || shorterLen < (cand.pdist ?? 0))
                     break;
                 f3calls++;
-                const shorter = phase3Solver.solveLengthValid(cand.edge, cand.ct3, cand.edist, shorterLen, tables.center3, tables.edge3.distances, polishBudget, 64, (moves3) => buildValidReduction(cand, moves3) !== null, tables.hc, cand.hcCoord, tables.c3PairDist);
+                // Unified polish: accept any goal path with a strictly better
+                // totalEst at the same or shorter length — covers both a shorter
+                // phase-3 path and a cheaper rotation fix (the fix is priced into
+                // totalEst and varies 2-4 moves per goal path).
+                const shorter = phase3Solver.solveLengthValid(cand.edge, cand.ct3, cand.edist, curRed.moves3.length, tables.center3, tables.edge3.distances, polishBudget, 64, (moves3) => {
+                    const nr = buildValidReduction(cand, moves3);
+                    return nr !== null && nr.totalEst < curRed.totalEst;
+                }, tables.hc, cand.hcCoord, tables.c3PairDist);
                 if (!shorter)
                     break;
                 const red = buildValidReduction(cand, shorter);
@@ -975,11 +1254,8 @@ export async function solveCube4State(state, tables, solveCube3, options) {
                 catch {
                     break;
                 }
-                const simplified = simplifyCube4Algorithm([
-                    ...rotateAlgorithm(red.cand.moves12, red.rotToStandard),
-                    ...rotateAlgorithm(red.moves3Remapped, red.rotToStandard),
-                    ...cube3Solution.moves
-                ]);
+                // Same frame invariant as the finish loop: X ++ rotMoves(r) ++ C.
+                const simplified = placeRotationFix([...red.cand.moves12, ...red.moves3Remapped], red.rotToStandard, cube3Solution.moves);
                 if (simplified.length < minTotalMoves) {
                     minTotalMoves = simplified.length;
                     bestSolution = simplified;
@@ -1004,13 +1280,19 @@ export async function solveCube4State(state, tables, solveCube3, options) {
         accF3Ms += tFinishStart - tF2End;
         accFinishMs += tPolishStart - tFinishStart;
         accPolishMs += performance.now() - tPolishStart;
+        // Final invariant: the emitted solution must solve the INPUT state
+        // exactly (no rotation tolerance). Fail loudly rather than return a
+        // solution that does not resolve. One replay of ~45 moves — negligible
+        // next to the search cost.
+        if (!isSolvedCube4State(applyCube4Algorithm(state, bestSolution))) {
+            throw new Error("4x4 solve: internal verification failed — the solution does not solve the input state.");
+        }
         return { moves: bestSolution, phases: bestPhases };
     };
     let bestMoves = null;
     let bestPhasesOverall;
     let lastRestartError = null;
     for (let restart = 0; restart < totalRestarts; restart++) {
-        FastPhase3Solver.nextEpoch();
         const rng = totalRestarts > 1
             ? mulberry32((hashCube4State(state) ^ Math.imul(restart + 1, 0x9e3779b9)) >>> 0)
             : null;