@cubingcenter/scrambler 0.6.2 → 0.7.0

package/dist/puzzles/cube4/scrambler.d.ts

@@ -3,13 +3,114 @@
  * the reduction solver (phases 1-4), and invert the solution. The scramble
  * always reproduces the sampled target state and facelets exactly.
  *
- * If the solver fails after 5 attempts it falls back to cubing.js
- * `randomScrambleForEvent("444")` (also random-state). If that also fails,
- * a WCA-compatible random-moves sequence (40 moves) is returned.
+ * Reduction-only, no resampling: each call runs one round of up to `bestOf`
+ * independent attempts and returns the shortest success (ties keep the
+ * lowest job index). If every attempt fails, the last error is thrown.
  */
 import type { ScrambleGenerator, ScrambleOptions, ScrambleResult } from "../../core/index.js";
 export declare const cube4ScrambleGenerator: ScrambleGenerator;
-export declare function generateCube4Scramble(options?: ScrambleOptions & {
+/**
+ * 444-specific scramble options (pass-through; extra keys are ignored by
+ * the generic `generateScramble` API surface).
+ */
+export interface Cube4ScrambleOptions {
+    /**
+     * Number of reduction passes to run on the SAME sampled state (alias for `restarts`).
+     * `1` (default): single deterministic pass.
+     * Higher values reshuffle the search traversal order on the same physical cube,
+     * returning the shortest valid scramble while strictly preserving uniform random-state
+     * distribution (WCA compliant).
+     */
+    bestOf?: number;
+    /**
+     * Last-resort effort for hard states: widens every solver work cap
+     * (phase-2 depth/nodes, phase-3 budgets/lengths, pool caps).
+     * Default false — the fast caps solve essentially everything at the
+     * same length (measured: identical totals on 54 states, ~-19% time),
+     * and a failed fast attempt automatically retries with `deep: true`
+     * (bestOf 1), so hard states still resolve.
+     */
+    deep?: boolean;
+    /**
+     * Search all 3 axial views (UD, RL, FB) of the same physical cube.
+     * Shaves ~1-2 moves on average without resampling.
+     */
+    threeAxes?: boolean;
+    /**
+     * Phase-4 attempts among valid reductions (default centersBeam * edgesPerCenter, i.e. 9).
+     * Passed through to the reduction solver: the first N reductions each get a 3x3
+     * finish and the shortest simplified total wins.
+     */
+    finishTries?: number;
+    /**
+     * Number of distinct center candidates from phase 2 to explore in phase 3
+     * (default 3). Part of hierarchical beam search.
+     */
+    centersBeam?: number;
+    /**
+     * Maximum number of distinct edge pairings to collect per center candidate
+     * in phase 3 (default 3). Part of hierarchical beam search.
+     */
+    edgesPerCenter?: number;
+    /**
+     * F1 enumeration slack beyond the per-axis optimum (default 3) and
+     * collection cap (default 60). Passed through to the reduction
+     * solver. Reversible A/B knob for the diversity-vs-length trade-off
+     * of phase 1.
+     */
+    phase1ExtraDepths?: number;
+    phase1Cap?: number;
+    /**
+     * Phase-2 wide move set: search all 28 center2 moves (adds
+     * Dw2/Lw/Lw2/Lw'/Bw2) instead of the default 23. Default false
+     * (measured ~-0.2 moves for ~+15% time on typical states; opt-in).
+     * Caution: on some hard states the wider branching can blow a single
+     * attempt past 100 s (no in-search cancellation), delaying every later
+     * bestOf job — prefer `restarts` for length.
+     */
+    center2Wide?: boolean;
+    /**
+     * Deep multi-candidate polish pass in phase 3 (top-3 reductions).
+     * Defaults to the value of `threeAxes`.
+     */
+    deepPolish?: boolean;
+    /**
+     * Full-pipeline restarts over the SAME sampled state (default 1).
+     * Passed through to the reduction solver: each restart reshuffles the
+     * search order deterministically and the shortest total wins.
+     * Same-state diversity (uniformity-preserving), unlike `bestOf`.
+     */
+    restarts?: number;
+    /**
+     * Tuning for the 3x3 finish (cube3 two-phase solver). All fields fall
+     * back to the production defaults, which prioritize short finishes:
+     * `orientations: 6`, `phase1ExtraDepth: 1`, `phase1SolutionLimit: 48`,
+     * `targetLength: 17`, budgets 350/100 ms with one 600/150 ms retry.
+     * A cheaper finish (e.g. `orientations: 3`, `phase1SolutionLimit: 24`)
+     * is much faster per call at a small length cost — the finish runs
+     * dozens of times per attempt, so this dominates attempt latency.
+     */
+    finish?: {
+        orientations?: number;
+        phase1ExtraDepth?: number;
+        phase1SolutionLimit?: number;
+        targetLength?: number;
+        timeoutMs?: number;
+        phase2TimeoutMs?: number;
+        retryTimeoutMs?: number;
+        retryPhase2TimeoutMs?: number;
+    };
+}
+export declare function generateCube4Scramble(options?: ScrambleOptions & Cube4ScrambleOptions & {
+    skipValidation?: boolean;
+}): Promise<ScrambleResult>;
+/**
+ * Single-attempt 444 solve: samples ONE state (from `options.seed`) and
+ * solves it with the reduction solver. Throws on failure — no resampling.
+ * Fan-out primitive for hosts: run with seeds `seed`, `seed:bestN`, ...
+ * across workers and keep the shortest valid result.
+ */
+export declare function generateCube4Attempt(tables: any, pairTables: any, options?: ScrambleOptions & Cube4ScrambleOptions & {
     skipValidation?: boolean;
 }): Promise<ScrambleResult>;
 //# sourceMappingURL=scrambler.d.ts.map

package/dist/puzzles/cube4/scrambler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrambler.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/scrambler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAmJ9F,eAAO,MAAM,sBAAsB,EAAE,iBAYpC,CAAC;AAEF,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,eAAe,GAAG;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,OAAO,CAAC,cAAc,CAAC,CAyFzB"}
+{"version":3,"file":"scrambler.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/scrambler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAiD9F,eAAO,MAAM,sBAAsB,EAAE,iBAYpC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE;QACP,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAuCD,wBAAsB,qBAAqB,CACzC,OAAO,GAAE,eAAe,GAAG,oBAAoB,GAAG;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAClF,OAAO,CAAC,cAAc,CAAC,CA+CzB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,GAAG,EACX,UAAU,EAAE,GAAG,EACf,OAAO,GAAE,eAAe,GAAG,oBAAoB,GAAG;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,GAClF,OAAO,CAAC,cAAc,CAAC,CAgKzB"}

package/dist/puzzles/cube4/scrambler.js

@@ -3,104 +3,18 @@
  * the reduction solver (phases 1-4), and invert the solution. The scramble
  * always reproduces the sampled target state and facelets exactly.
  *
- * If the solver fails after 5 attempts it falls back to cubing.js
- * `randomScrambleForEvent("444")` (also random-state). If that also fails,
- * a WCA-compatible random-moves sequence (40 moves) is returned.
+ * Reduction-only, no resampling: each call runs one round of up to `bestOf`
+ * independent attempts and returns the shortest success (ties keep the
+ * lowest job index). If every attempt fails, the last error is thrown.
  */
-import { formatCube4Algorithm, applyCube4Algorithm } from "./moves.js";
+import { formatCube4Algorithm, applyCube4Algorithm, invertCube4Algorithm } from "./moves.js";
 import { generateRandomCube4State } from "./random-state.js";
-import { createSolvedCube4State, cube4StatesEqual } from "./state.js";
+import { createSolvedCube4State, isSolvedCube4State } from "./state.js";
 import { formatCube4Facelets, toCube4Facelets } from "./facelets.js";
-import { solveCube4State } from "./reduction/solve.js";
+import { solveCube4State, applyCubeRotation, rotateAlgorithm } from "./reduction/solve.js";
 import { solveCube3State } from "../cube3/solver/index.js";
-import { createRandomSource } from "../../random/index.js";
-// ────────────────────────────────────────────────────────────
-// cubing.js fallback (random-state, WCA-compliant)
-// ────────────────────────────────────────────────────────────
-/**
- * Try to generate a 4x4 scramble using cubing.js `randomScrambleForEvent`.
- * Uses a dynamic import so browser bundles can tree-shake it when unused.
- * Returns null if cubing.js is unavailable.
- */
-async function generateCube4WithCubingJs() {
-    try {
-        const { randomScrambleForEvent } = await import(
-        /* webpackIgnore: true */
-        /* @vite-ignore */
-        "cubing/scramble");
-        const alg = await randomScrambleForEvent("444");
-        const scramble = alg.toString();
-        const moves = scramble.trim().split(/\s+/);
-        return {
-            eventId: "444",
-            scramble,
-            moves,
-            quality: "random-state",
-            generator: "cubing-js",
-            metadata: {
-                generator: "cubing-js",
-                distribution: "random-state",
-                note: "Generated by cubing.js randomScrambleForEvent as fallback."
-            }
-        };
-    }
-    catch {
-        return null;
-    }
-}
-// ────────────────────────────────────────────────────────────
-// Last-resort: random-moves (no external dep, always works)
-// ────────────────────────────────────────────────────────────
-const CUBE4_FACES = ["U", "R", "F", "D", "L", "B"];
-// Opposite face indices (U↔D, R↔L, F↔B)
-const CUBE4_OPPOSITE = { U: "D", D: "U", R: "L", L: "R", F: "B", B: "F" };
-const CUBE4_SUFFIXES = ["", "2", "'"];
-const CUBE4_WIDE_FACES = ["Uw", "Rw", "Fw", "Dw", "Lw", "Bw"];
-// Opposite wide-move faces
-const CUBE4_WIDE_OPPOSITE = {
-    Uw: "Dw", Dw: "Uw", Rw: "Lw", Lw: "Rw", Fw: "Bw", Bw: "Fw"
-};
-// All available move bases (outer + wide). Outer and wide turns are treated
-// independently for the same-face/opposite-face check using their base letter.
-const ALL_MOVE_BASES = [...CUBE4_FACES, ...CUBE4_WIDE_FACES];
-function generateCube4RandomMoves(options = {}) {
-    const rng = createRandomSource(options.seed);
-    const moveCount = 40;
-    const moves = [];
-    let lastFace = null;
-    let secondLastFace = null;
-    const getBaseLetter = (face) => face.length > 1 ? face[0] : face;
-    for (let i = 0; i < moveCount; i++) {
-        let face;
-        // Reject same face as last or opposite face when the last two moves
-        // share the same axis (to avoid redundant move pairs like R L R).
-        do {
-            face = ALL_MOVE_BASES[rng.nextInt(ALL_MOVE_BASES.length)];
-        } while (face === lastFace ||
-            (lastFace !== null &&
-                (CUBE4_OPPOSITE[face] === lastFace || CUBE4_WIDE_OPPOSITE[face] === lastFace) &&
-                secondLastFace !== null &&
-                getBaseLetter(secondLastFace) === getBaseLetter(face)));
-        const suffix = CUBE4_SUFFIXES[rng.nextInt(3)];
-        moves.push(`${face}${suffix}`);
-        secondLastFace = lastFace;
-        lastFace = face;
-    }
-    const scramble = moves.join(" ");
-    return {
-        eventId: "444",
-        scramble,
-        moves,
-        quality: "random-moves",
-        generator: "cube4-random-moves-fallback",
-        metadata: {
-            generator: "cube4-random-moves-fallback",
-            distribution: "random-moves",
-            note: "Reduction solver and cubing.js both failed; using random-moves.",
-            ...options.metadata
-        }
-    };
-}
+import { loadCube3Phase1Tables } from "../cube3/solver/tables.js";
+import { loadCube3PairTables } from "../cube3/solver/pair-tables.js";
 // ────────────────────────────────────────────────────────────
 let cachedTables;
 async function loadCube4Tables(baseUrl) {
@@ -140,88 +54,234 @@ export const cube4ScrambleGenerator = {
         puzzle: "cube-4x4",
         quality: "random-state",
         generator: "cube4-reduction",
-        description: "Random-state 4x4 scramble via the reduction solver (centers + pairing + 3x3 finish). Falls back to random-moves if the solver fails."
+        description: "Random-state 4x4 scramble via the reduction solver (centers + pairing + 3x3 finish)."
     },
     generate(options = {}) {
         return generateCube4Scramble(options);
     }
 };
+function invertRotationSequence(rotSeq) {
+    return rotSeq.slice().reverse().map((r) => (r.endsWith("'") ? r.slice(0, -1) : r.endsWith("2") ? r : `${r}'`));
+}
+/** Shortest-first pick (ties keep `a`, i.e. the lowest job index). */
+function shorterScramble(a, b) {
+    if (!a || b.moves.length < a.moves.length)
+        return b;
+    return a;
+}
+function seedForBestJob(options, job) {
+    if (job === 0)
+        return options;
+    const next = { ...options };
+    if (options.seed !== undefined) {
+        next.seed = `${options.seed}:best${job}`;
+    }
+    else {
+        delete next.seed;
+    }
+    return next;
+}
+function isRetryableCube4Error(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    const isPhase2Error = typeof error?.name === "string" &&
+        error.name.includes("Cube3Phase2");
+    return (error instanceof Error &&
+        (msg.includes("reduction failed") ||
+            msg.includes("failed to convert") ||
+            msg.includes("no valid phase 2") ||
+            msg.includes("timeout") ||
+            isPhase2Error ||
+            msg.includes("Phase 2 solution not found")));
+}
 export async function generateCube4Scramble(options = {}) {
-    const tables = await loadCube4Tables();
+    const bestOf = Math.max(1, Math.floor(options.bestOf ?? 1) || 1);
+    let tables;
+    let pairTables;
+    try {
+        const [loadedTables, cube3P1Tables, loadedPairTables] = await Promise.all([
+            loadCube4Tables(),
+            loadCube3Phase1Tables(),
+            loadCube3PairTables()
+        ]);
+        tables = loadedTables;
+        tables.cube3Phase1 = cube3P1Tables;
+        tables.pairTables = loadedPairTables;
+        pairTables = loadedPairTables;
+    }
+    catch (error) {
+        throw new Error("[cube4-scrambler] Failed to load reduction tables; run pnpm cube4:center1:tables etc. " +
+            `(${error instanceof Error ? error.message : String(error)})`);
+    }
+    const totalRestarts = Math.max(1, Math.floor(options.restarts ?? options.bestOf ?? 1) || 1);
     let lastError;
-    // Retry with different states if the solver fails to find a physical
-    // reduction (some random states are outside the solver's effective
-    // horizon with the current candidate/length caps).
-    for (let attempt = 0; attempt < 5; attempt++) {
-        let attemptOptions;
-        if (attempt === 0) {
-            attemptOptions = options;
+    try {
+        return await generateCube4Attempt(tables, pairTables, {
+            ...options,
+            restarts: totalRestarts
+        });
+    }
+    catch (error) {
+        if (!isRetryableCube4Error(error))
+            throw error;
+        lastError = error;
+    }
+    if (!options.deep) {
+        try {
+            return await generateCube4Attempt(tables, pairTables, {
+                ...options,
+                restarts: totalRestarts,
+                deep: true
+            });
         }
-        else {
-            attemptOptions = { ...options };
-            if (options.seed !== undefined) {
-                attemptOptions.seed = `${options.seed}:retry${attempt}`;
-            }
-            else {
-                delete attemptOptions.seed;
-            }
+        catch (error) {
+            if (isRetryableCube4Error(error))
+                lastError = error;
+            else
+                throw error;
         }
-        const attemptState = generateRandomCube4State(attemptOptions);
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`[cube4-scrambler] Reduction solver failed for restarts=${totalRestarts}: ${String(lastError)}`);
+}
+/**
+ * Single-attempt 444 solve: samples ONE state (from `options.seed`) and
+ * solves it with the reduction solver. Throws on failure — no resampling.
+ * Fan-out primitive for hosts: run with seeds `seed`, `seed:bestN`, ...
+ * across workers and keep the shortest valid result.
+ */
+export async function generateCube4Attempt(tables, pairTables, options = {}) {
+    const attemptState = generateRandomCube4State(options);
+    const axes = options.threeAxes ? [[], ["z"], ["y'"]] : [[]];
+    let bestScrambleMoves = null;
+    let bestSolutionMoves = null;
+    let bestPhases;
+    let bestNodes;
+    let bestTimings;
+    let bestReductionLen;
+    let lastError;
+    const tAttemptStart = performance.now();
+    const finishOpts = options.finish ?? {};
+    for (const rot of axes) {
         try {
-            const solvePromise = solveCube4State(attemptState, tables, (cube3State) => solveCube3State(cube3State));
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("4x4 solve: timeout")), 20000));
-            const { scramble: scrambleMoves } = await Promise.race([solvePromise, timeoutPromise]);
-            if (!options.skipValidation) {
-                const scrambledState = applyCube4Algorithm(createSolvedCube4State(), scrambleMoves);
-                if (!cube4StatesEqual(scrambledState, attemptState)) {
-                    throw new Error("Generated 4x4 scramble does not reproduce the target random state.");
+            const sRot = rot.length === 0 ? attemptState : applyCubeRotation(attemptState, rot);
+            // The reduction search is bounded by deterministic work caps (see
+            // solve.ts), so these timeouts are only wall-clock backstops for
+            // pathological cases.
+            const solvePromise = solveCube4State(sRot, tables, async (cube3State) => {
+                // Single solver-side best-of-orientations finish call with
+                // extra phase-1 improvement: same lengths as the former
+                // hand-rolled UD/X/Z triple at a fraction of the cost.
+                const solveFinish = async (timeBudget, phase2Budget) => {
+                    const solution = await solveCube3State(cube3State, {
+                        orientations: finishOpts.orientations ?? 3,
+                        phase1ExtraDepth: finishOpts.phase1ExtraDepth ?? 1,
+                        phase1SolutionLimit: finishOpts.phase1SolutionLimit ?? 24,
+                        targetLength: finishOpts.targetLength ?? 20,
+                        timeoutMs: timeBudget,
+                        // The 54MB pair tables are skipped for the 444 finish: pair
+                        // pruning changes nothing measurable here (identical lengths
+                        // on a 44-state corpus, zero extra finish retries), and
+                        // loading them dominates cold-start I/O. Hosts that already
+                        // hold pairTables can still pass them via generateCube4Attempt.
+                        phase2: { pairTables, skipPairTables: pairTables === undefined, timeoutMs: phase2Budget }
+                    });
+                    return { moves: solution.moves };
+                };
+                // The first call seeds everything, so a flaky finish gets one
+                // budgeted retry before the whole finish is declared failed.
+                try {
+                    return await solveFinish(finishOpts.timeoutMs ?? 150, finishOpts.phase2TimeoutMs ?? 50);
+                }
+                catch {
+                    return await solveFinish(finishOpts.retryTimeoutMs ?? 300, finishOpts.retryPhase2TimeoutMs ?? 100);
                 }
+            }, {
+                timeoutMs: 75000,
+                deep: options.deep === true,
+                deepPolish: options.deepPolish ?? options.threeAxes,
+                ...(options.finishTries !== undefined ? { finishTries: options.finishTries } : {}),
+                ...(options.centersBeam !== undefined ? { centersBeam: options.centersBeam } : {}),
+                ...(options.edgesPerCenter !== undefined ? { edgesPerCenter: options.edgesPerCenter } : {}),
+                ...(options.phase1ExtraDepths !== undefined ? { phase1ExtraDepths: options.phase1ExtraDepths } : {}),
+                ...(options.phase1Cap !== undefined ? { phase1Cap: options.phase1Cap } : {}),
+                ...(options.center2Wide !== undefined ? { center2Wide: options.center2Wide } : {}),
+                ...(options.restarts !== undefined ? { restarts: options.restarts } : {}),
+                ...(options.prepCap !== undefined ? { prepCap: options.prepCap } : {}),
+                ...(options.p1CandCap !== undefined ? { p1CandCap: options.p1CandCap } : {}),
+                ...(options.stagnationCut !== undefined ? { stagnationCut: options.stagnationCut } : {}),
+                maxReductionLen: bestReductionLen
+            });
+            let timeoutHandle;
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error("4x4 solve: timeout")), 90000);
+            });
+            let solveOutcome;
+            try {
+                solveOutcome = await Promise.race([solvePromise, timeoutPromise]);
+            }
+            finally {
+                // The search is work-capped and always settles first: clearing the
+                // backstop avoids leaking a live 90s timer per axis (which kept the
+                // event loop — and CLI/test processes — alive needlessly).
+                clearTimeout(timeoutHandle);
             }
-            const facelets = toCube4Facelets(attemptState);
-            const result = {
-                eventId: "444",
-                scramble: formatCube4Algorithm(scrambleMoves),
-                moves: scrambleMoves,
-                quality: "random-state",
-                generator: "cube4-reduction",
-                metadata: {
-                    generator: "cube4-reduction",
-                    state: attemptState,
-                    facelets,
-                    faceletString: formatCube4Facelets(facelets),
-                    distribution: "random-state",
-                    ...options.metadata
+            const { scramble: scrambleMoves, moves: solutionMoves, phases, timings, nodes } = solveOutcome;
+            const invRot = rot.length === 0 ? [] : invertRotationSequence(rot);
+            const fullScramble = rot.length === 0 ? scrambleMoves : rotateAlgorithm(scrambleMoves, invRot);
+            const fullSolution = rot.length === 0 ? solutionMoves : rotateAlgorithm(solutionMoves, invRot);
+            if (!bestScrambleMoves || fullScramble.length < bestScrambleMoves.length) {
+                bestScrambleMoves = fullScramble;
+                bestSolutionMoves = fullSolution;
+                bestPhases = phases;
+                bestTimings = timings;
+                bestNodes = nodes;
+                if (phases) {
+                    bestReductionLen = phases.length12 + phases.length3;
                 }
-            };
-            if (options.seed !== undefined) {
-                result.seed = options.seed;
             }
-            return result;
         }
-        catch (error) {
-            lastError = error;
-            // Retry on deterministic reduction / 3x3 failures (some random states are
-            // outside the solver's horizon with the current caps).
-            const msg = error instanceof Error ? error.message : String(error);
-            const isPhase2Error = typeof error?.name === "string" &&
-                error.name.includes("Cube3Phase2");
-            if (error instanceof Error &&
-                (msg.includes("reduction failed") ||
-                    msg.includes("failed to convert") ||
-                    msg.includes("no valid phase 2") ||
-                    msg.includes("timeout") ||
-                    isPhase2Error ||
-                    msg.includes("Phase 2 solution not found"))) {
-                continue;
-            }
-            throw error;
+        catch (err) {
+            lastError = err;
+        }
+    }
+    if (!bestScrambleMoves || !bestSolutionMoves) {
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    const scrambleMoves = bestScrambleMoves;
+    const solutionMoves = bestSolutionMoves;
+    const scrambledState = applyCube4Algorithm(createSolvedCube4State(), scrambleMoves);
+    if (!options.skipValidation) {
+        const solvedCheck = applyCube4Algorithm(scrambledState, solutionMoves);
+        if (!isSolvedCube4State(solvedCheck)) {
+            throw new Error("Generated 4x4 scramble does not solve back to solved state.");
+        }
+    }
+    const facelets = toCube4Facelets(scrambledState);
+    const result = {
+        eventId: "444",
+        scramble: formatCube4Algorithm(scrambleMoves),
+        moves: scrambleMoves,
+        quality: "random-state",
+        generator: "cube4-reduction",
+        metadata: {
+            generator: "cube4-reduction",
+            state: scrambledState,
+            facelets,
+            faceletString: formatCube4Facelets(facelets),
+            distribution: "random-state",
+            solutionMoves: invertCube4Algorithm(scrambleMoves),
+            // Winning-reduction breakdown (unsimplified lengths) + wall-clock
+            // split, for tuning and A/B comparisons.
+            phases: bestPhases,
+            phaseTimings: bestTimings,
+            nodes: bestNodes,
+            attemptMs: performance.now() - tAttemptStart,
+            ...options.metadata
         }
+    };
+    if (options.seed !== undefined) {
+        result.seed = options.seed;
     }
-    // All solver attempts exhausted — try cubing.js first, then random-moves.
-    console.warn("[cube4-scrambler] Reduction solver failed after 5 attempts; trying cubing.js fallback.", lastError);
-    const cubingJsResult = await generateCube4WithCubingJs();
-    if (cubingJsResult)
-        return cubingJsResult;
-    console.warn("[cube4-scrambler] cubing.js fallback also failed; using random-moves.");
-    return generateCube4RandomMoves(options);
+    return result;
 }

package/dist/puzzles/cube4/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/state.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,wBAAgB,sBAAsB,IAAI,UAAU,CAanD;AAMD,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU,CAOzD;AAMD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAOtE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAE7D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAS5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAUzD"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/state.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,wBAAgB,sBAAsB,IAAI,UAAU,CAanD;AAMD,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,GAAG,UAAU,CAOzD;AAMD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAOtE;AAMD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAE7D;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAS5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAUzD"}

package/dist/puzzles/cube4/state.js

@@ -36,8 +36,11 @@ export function cube4StatesEqual(a, b) {
         typedArrayEqual(a.wp, b.wp) &&
         typedArrayEqual(a.centers, b.centers));
 }
+// Read-only canonical solved state for comparisons (never mutated, so a
+// single shared instance is safe and avoids allocating 4 arrays per call).
+const SOLVED_STATE = createSolvedCube4State();
 export function isSolvedCube4State(state) {
-    return cube4StatesEqual(state, createSolvedCube4State());
+    return cube4StatesEqual(state, SOLVED_STATE);
 }
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/puzzles/pyraminx/solver/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/pyraminx/solver/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAe/D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAGjF;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAG3F;AAMD,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGlF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAGvE;AAuCD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,EAAE,CAGtE;AAaD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAsCzG;AAKD,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAmCT"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/pyraminx/solver/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAgB/D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAGjF;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAG3F;AAMD,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAGlF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,EAAE,CAGvE;AAoCD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,EAAE,CAGtE;AAaD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAsCzG;AAKD,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,OAAO,CAmCT"}

package/dist/puzzles/pyraminx/solver/search.js

@@ -1,4 +1,4 @@
-import { POLICY_TABLE, CENTERS_TABLE, PERMUTATION_TABLE, ORIENTATION_TABLE, PYRAMINX_MOVES, MOVE_COUNT, PERMUTATION_COUNT, getCentersIndex, getOrientationIndex, getPermutationCompactIndex, ensureTablesLoaded } from "./tables.js";
+import { POLICY_TABLE, POLICY_TABLE_EXPANDED, CENTERS_TABLE, PERMUTATION_TABLE, ORIENTATION_TABLE, PYRAMINX_MOVES, MOVE_COUNT, PERMUTATION_COUNT, getCentersIndex, getOrientationIndex, getPermutationCompactIndex, ensureTablesLoaded } from "./tables.js";
 export async function solvePyraminx(state) {
     await ensureTablesLoaded();
     return solveWithTables(state).moves;
@@ -29,7 +29,7 @@ function solveWithTablesIndices(state) {
     const centersTable = CENTERS_TABLE;
     const permTable = PERMUTATION_TABLE;
     const orientTable = ORIENTATION_TABLE;
-    const policy = POLICY_TABLE;
+    const policy = POLICY_TABLE_EXPANDED;
     let c = getCentersIndex(state.centers);
     let p = getPermutationCompactIndex(state.edgesPerm);
     let o = getOrientationIndex(state.edgesOrient);
@@ -38,10 +38,7 @@ function solveWithTablesIndices(state) {
         return [];
     const moves = [];
     while (stateIndex !== 0) {
-        const bits = stateIndex * 3;
-        const byteIndex = bits >> 3;
-        const offset = bits & 7;
-        const m = ((policy[byteIndex] | ((policy[byteIndex + 1] ?? 0) << 8)) >> offset) & 0x07;
+        const m = policy[stateIndex];
         moves.push(m);
         c = centersTable[c * MOVE_COUNT + m];
         p = permTable[p * MOVE_COUNT + m];

package/dist/puzzles/pyraminx/solver/tables.d.ts

@@ -34,6 +34,12 @@ export declare let CENTERS_TABLE: Uint8Array | null;
 export declare let PERMUTATION_TABLE: Uint16Array | null;
 export declare let ORIENTATION_TABLE: Uint8Array | null;
 export declare let POLICY_TABLE: Uint8Array | null;
+/**
+ * Byte-expanded policy (one optimal move per state, no bit-unpacking in
+ * the hot walk). Built at load from the 3-bit packed table: +0.9 MB RAM,
+ * zero wire/format change.
+ */
+export declare let POLICY_TABLE_EXPANDED: Uint8Array | null;
 export declare function ensureTablesLoaded(): Promise<void>;
 export declare function arePyraminxTablesLoaded(): boolean;
 export declare function getPolicyMove(stateIndex: number): number;

package/dist/puzzles/pyraminx/solver/tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/pyraminx/solver/tables.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/pyraminx/solver/tables.ts"],"names":[],"mappings":"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"}