@cubingcenter/scrambler 0.6.3 → 0.8.0

package/dist/puzzles/cube4/scrambler.js

@@ -1,111 +1,89 @@
 /**
  * The 4x4 scramble generator: sample a uniform random state, solve it with
- * the reduction solver (phases 1-4), and invert the solution. The scramble
- * always reproduces the sampled target state and facelets exactly.
+ * the reduction solver (phases 1-4), and invert the solution. The emitted
+ * scramble must reproduce the sampled target state EXACTLY — enforced by
+ * `assertCube4ScrambleReproducesTarget` on every generated result (unless
+ * `skipValidation` is set, which is only for the independent verification
+ * harness in `scripts/verify-scrambles.ts`).
  *
- * 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.
+ * On a target mismatch the error is retryable, so the existing retry loop
+ * re-runs the solve over the SAME sampled target (deep attempt) and throws
+ * once attempts are exhausted. Re-sampling a different target to "make it
+ * fit" and degrading to random moves are forbidden: failing loudly (WCA 4g)
+ * is strictly preferable to emitting a scramble that lies about its seed.
+ *
+ * ── Determinism contract: what defines the output ──────────────────────
+ * `generateCube4Scramble` / `generateCube4Attempt` are pure functions of
+ * (seed, complete options): the emitted `moves` do not depend on wall-clock
+ * time, CPU load, warm-up, batch order, or process identity. This holds
+ * because every budget that can change the search outcome is a
+ * deterministic work counter (nodes visited), never a wall deadline:
+ *   - reduction phases: node budgets inside `reduction/solve.ts`;
+ *   - the 3x3 finish: node caps below (`finish.phase2MaxNodes`,
+ *     `finish.improveMaxNodes`, per-candidate cap), which replace the old
+ *     150/50 ms wall budgets that made the same seed yield different move
+ *     counts under CPU contention.
+ * Options are PART of the key: `restarts`/`bestOf`, `threeAxes`, `deep`,
+ * the beam knobs and `finish.*` legitimately change the result for the same
+ * seed — the output is reproducible within each configuration (documented
+ * behavior, not nondeterminism).
+ *
+ * Residual wall-clock backstop (hang guard only; never observed to bind —
+ * max measured solve 36.5 s): the 90 s
+  * `Promise.race` below. It cannot preempt the synchronous search — it
+ * can only fire at an event-loop tick — so if one ever fired, that attempt
+ * fails loudly (as a retryable error) instead of hanging. Making that bound
+  * exact deadline support would require cooperative search checkpoints.
  */
-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 { formatCube4Facelets, toCube4Facelets } from "./facelets.js";
-import { solveCube4State } from "./reduction/solve.js";
-import { solveCube3State } from "../cube3/solver/index.js";
-import { createRandomSource } from "../../random/index.js";
-// ────────────────────────────────────────────────────────────
-// cubing.js fallback (random-state, WCA-compliant)
+import { solveCube4State, applyCubeRotation, Cube4FinishCapError, Cube4Phase2CapError, Cube4Phase3CapError } from "./reduction/solve.js";
+import { solveCube3State, Cube3Phase1SearchError, Cube3Phase2SearchError } from "../cube3/solver/index.js";
+import { loadCube3Phase1Tables, loadCube3Phase2Tables } from "../cube3/solver/tables.js";
+import { solveFinish3, Finish3SearchError } from "./reduction/finish3.js";
+import { placeRotationFix } from "./reduction/rotation-fix.js";
 // ────────────────────────────────────────────────────────────
 /**
- * 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.
+ * Deterministic work caps for the 3x3 finish — nodes visited, never
+ * wall-clock. Calibrated against the former wall budgets (phase-2 50 ms,
+ * improvement 150 ms at a measured ~1.75k nodes/ms warm) so typical
+ * latency and finish length are unchanged, while the stopping point
+ * becomes independent of CPU load: same (seed, options) ⇒ same moves.
+ * A failing first finish call retries once with every cap doubled
+ * (equivalent of the former 150→300 / 50→100 ms retry).
  */
-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
-        }
-    };
+const FINISH_PHASE2_MAX_NODES = 90_000;
+const FINISH_IMPROVE_MAX_NODES = 260_000;
+const FINISH_RETRY_SCALE = 2;
+// Continuous finish defaults (the production finish). Measured on cc:0..15:
+// 6 views × 200k nodes = 44.88 moves @ 1257 ms vs legacy 46.06 @ 1288 ms
+// (50k: 45.50 @ 1102; 100k: 45.31; 300k: 44.88 @ 1371 — no gain past 200k).
+const FINISH3_MAX_NODES = 200_000;
+const FINISH3_HARD_MAX_NODES = 20_000_000;
+// Screening budget for the two-stage finish (every candidate reduction gets
+// this; only the best `finishScreenTop` get FINISH3_MAX_NODES).
+const FINISH3_SCREEN_NODES = 30_000;
+const FINISH3_VIEWS = 6;
+const FINISH3_MAX_PHASE2_LENGTH = 12;
+let cube4TablesPromise;
+/**
+ * Loads the 4x4 reduction tables with a promise-deduplicating cache: the
+ * cache stores the in-flight PROMISE (not a value), so concurrent first
+ * calls share one load instead of racing; a rejected load is purged so the
+ * next call can retry instead of caching the failure forever.
+ */
+function loadCube4Tables(baseUrl) {
+    if (cube4TablesPromise !== undefined)
+        return cube4TablesPromise;
+    cube4TablesPromise = loadCube4TablesOnce(baseUrl).catch((error) => {
+        cube4TablesPromise = undefined;
+        throw error;
+    });
+    return cube4TablesPromise;
 }
-// ────────────────────────────────────────────────────────────
-let cachedTables;
-async function loadCube4Tables(baseUrl) {
-    if (cachedTables)
-        return cachedTables;
+async function loadCube4TablesOnce(baseUrl) {
     const isBrowser = typeof window !== "undefined" ||
         typeof document !== "undefined" ||
         (typeof self !== "undefined" && typeof self.importScripts === "function") ||
@@ -118,20 +96,15 @@ async function loadCube4Tables(baseUrl) {
         "./reduction/browser-loader.js");
         const cached = loader.getCachedCube4Tables();
         if (cached) {
-            cachedTables = cached;
             return cached;
         }
-        const tables = await loader.loadCube4ReductionTablesBrowser(baseUrl);
-        cachedTables = tables;
-        return tables;
+        return await loader.loadCube4ReductionTablesBrowser(baseUrl);
     }
     const loader = await import(
     /* webpackIgnore: true */
     /* @vite-ignore */
     "./reduction/node-loader.js");
-    const tables = await loader.loadCube4ReductionTables();
-    cachedTables = tables;
-    return tables;
+    return await loader.loadCube4ReductionTables();
 }
 export const cube4ScrambleGenerator = {
     info: {
@@ -140,98 +113,363 @@ 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);
     }
 };
+/**
+ * Thrown by the target gate when the emitted scramble does not reproduce
+ * the independently sampled state. Retryable: the retry loop re-solves the
+ * SAME sampled target (deep attempt) — never re-samples.
+ */
+export class Cube4TargetMismatchError extends Error {
+    code = "cube4-target-mismatch";
+    constructor(message) {
+        super(message);
+        this.name = "Cube4TargetMismatchError";
+    }
+}
+/** Thrown by the 90 s hang guard (wall-clock, fires only at a tick). */
+export class Cube4WallTimeoutError extends Error {
+    code = "cube4-wall-timeout";
+    constructor(message) {
+        super(message);
+        this.name = "Cube4WallTimeoutError";
+    }
+}
+/**
+ * Message patterns for errors thrown by `reduction/solve.ts`, which cannot
+ * be classified by type/code without editing that file (reported: it should
+ * grow error codes). Every other retryable path is typed below.
+ */
+const SOLVER_RETRYABLE_MESSAGE_PATTERNS = [
+    "reduction failed", // no candidates / node budget exhausted in a reduction phase
+    "no valid phase 2" // empty phase-2 candidate set
+];
+/**
+ * Retry classification. Typed first (error class / `code`), message
+ * patterns last and only for the reduction solver's own errors. Semantics:
+ * a retry re-runs the solve over the SAME sampled target with deeper work
+ * caps; it never changes the seed's target state.
+ */
+function isFinish3Cap(error) {
+    return error instanceof Error &&
+        error.code === "cube4-finish3-cap" &&
+        (error instanceof Finish3SearchError || error.name === "Finish3SearchError");
+}
+function isRetryableCube4Error(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = error.code;
+    if (code === "cube4-target-mismatch" || code === "cube4-wall-timeout")
+        return true;
+    if (isFinish3Cap(error))
+        return true;
+    if (error instanceof Cube4Phase2CapError ||
+        error instanceof Cube4Phase3CapError ||
+        error instanceof Cube4FinishCapError)
+        return true;
+    // Budget/depth failures of the 3x3 finish phase 2: a deeper attempt may
+    // succeed (historical behavior: any Cube3Phase2* error was retryable).
+    if (error instanceof Cube3Phase2SearchError || error.name === "Cube3Phase2SearchError") {
+        return true;
+    }
+    // Phase-1 failures are deterministic depth failures (phase 1 runs
+    // uncapped in the 444 finish): retrying the same target cannot help.
+    if (error instanceof Cube3Phase1SearchError || error.name === "Cube3Phase1SearchError") {
+        return false;
+    }
+    return SOLVER_RETRYABLE_MESSAGE_PATTERNS.some((pattern) => error.message.includes(pattern));
+}
+/**
+ * The real random-state contract for 444 (non-tautological): replaying the
+ * emitted scramble on the solved cube must reproduce the exact state that
+ * was sampled for the seed — the reference the sampler produced, never a
+ * state derived from the scramble itself. Throws when it does not.
+ *
+ * Used by the production validation path in `solveCube4Attempt` and
+ * exported so tests can prove the gate rejects corrupted scrambles.
+ */
+export function assertCube4ScrambleReproducesTarget(scrambleMoves, targetState, seed) {
+    const replayed = applyCube4Algorithm(createSolvedCube4State(), scrambleMoves);
+    if (!cube4StatesEqual(replayed, targetState)) {
+        throw new Cube4TargetMismatchError("[cube4-scrambler] scramble does not reproduce the sampled target state" +
+            (seed !== undefined ? ` (seed=${seed})` : "") +
+            ": applying the emitted scramble to the solved cube must yield the state " +
+            "sampled for this seed. Refusing to emit it (no re-sampling, no random-move fallback).");
+    }
+}
 export async function generateCube4Scramble(options = {}) {
     let tables;
+    // Optional pair tables are unnecessary for the 444 finish. In browsers,
+    // probing for absent tables on every generation adds a network dependency
+    // before the search even starts (outside its timeout).
+    const pairTables = undefined;
     try {
-        tables = await loadCube4Tables();
+        const continuousFinish = options.finish?.mode !== "legacy";
+        const [loadedTables, cube3P1Tables, cube3P2Tables] = await Promise.all([
+            loadCube4Tables(),
+            loadCube3Phase1Tables(),
+            continuousFinish ? loadCube3Phase2Tables() : Promise.resolve(undefined)
+        ]);
+        tables = loadedTables;
+        tables.cube3Phase1 = cube3P1Tables;
+        if (cube3P2Tables !== undefined)
+            tables.cube3Phase2 = cube3P2Tables;
     }
     catch (error) {
-        console.warn("[cube4-scrambler] Failed to load reduction tables; using fallback.", error);
-        const cubingJsResult = await generateCube4WithCubingJs();
-        if (cubingJsResult)
-            return cubingJsResult;
-        return generateCube4RandomMoves(options);
+        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);
+    const targetState = generateRandomCube4State(options);
     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 solveCube4Attempt(tables, pairTables, {
+            ...options,
+            restarts: totalRestarts
+        }, targetState);
+    }
+    catch (error) {
+        if (!isRetryableCube4Error(error))
+            throw error;
+        lastError = error;
+    }
+    if (!options.deep) {
+        try {
+            return await solveCube4Attempt(tables, pairTables, {
+                ...options,
+                restarts: totalRestarts,
+                deep: true
+            }, targetState);
         }
-        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 — including a
+ * target mismatch ("scramble does not reproduce the sampled target state")
+ * — no resampling; hosts may retry with the same seed, which re-uses the
+ * same target.
+ * 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 = {}) {
+    return solveCube4Attempt(tables, pairTables, options, generateRandomCube4State(options));
+}
+async function solveCube4Attempt(tables, pairTables, options, attemptState) {
+    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, effort) => {
+                // Legacy batch two-phase finish. Budgets are deterministic node
+                // caps (see FINISH_* constants); `capScale` doubles every cap on
+                // the one flaky-finish retry.
+                const solveLegacyFinish = async (capScale) => {
+                    const solution = await solveCube3State(cube3State, {
+                        orientations: finishOpts.orientations ?? 3,
+                        phase1ExtraDepth: finishOpts.phase1ExtraDepth ?? 1,
+                        phase1SolutionLimit: finishOpts.phase1SolutionLimit ?? 24,
+                        // 18 (not 20): the improve loop only runs when the first
+                        // answer exceeds the target, so 20 skipped it for 19-20 move
+                        // answers. Measured: -0.13 moves at ~+3% time.
+                        targetLength: finishOpts.targetLength ?? 18,
+                        improveMaxNodes: Math.round((finishOpts.improveMaxNodes ?? FINISH_IMPROVE_MAX_NODES) * capScale),
+                        ...(finishOpts.improvePhase2MaxNodes !== undefined
+                            ? {
+                                improvePhase2MaxNodes: Math.round(finishOpts.improvePhase2MaxNodes * capScale)
+                            }
+                            : {}),
+                        // 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,
+                            maxNodes: Math.round((finishOpts.phase2MaxNodes ?? FINISH_PHASE2_MAX_NODES) * capScale)
+                        }
+                    });
+                    return { moves: solution.moves };
+                };
+                if (finishOpts.mode !== "legacy") {
+                    // Callers of generateCube4Attempt pass their own table bag,
+                    // which may predate the continuous finish: load what is missing.
+                    tables.cube3Phase1 ??= await loadCube3Phase1Tables();
+                    tables.cube3Phase2 ??= await loadCube3Phase2Tables();
+                    const views = finishOpts.continuousViews ?? FINISH3_VIEWS;
+                    const runContinuous = (capScale) => {
+                        if (tables.cube3Phase1 === undefined || tables.cube3Phase2 === undefined) {
+                            throw new Error("[cube4-scrambler] continuous finish requires cube3 phase-1 and phase-2 tables");
+                        }
+                        return solveFinish3(cube3State, { phase1: tables.cube3Phase1, phase2: tables.cube3Phase2 }, {
+                            targetLength: finishOpts.targetLength ?? 18,
+                            maxNodes: Math.round((effort === "screen"
+                                ? finishOpts.continuousScreenNodes ?? FINISH3_SCREEN_NODES
+                                : finishOpts.continuousMaxNodes ?? FINISH3_MAX_NODES) * capScale),
+                            hardMaxNodes: Math.round((finishOpts.continuousHardMaxNodes ?? FINISH3_HARD_MAX_NODES) * capScale),
+                            maxPhase2Length: finishOpts.continuousMaxPhase2Length ?? FINISH3_MAX_PHASE2_LENGTH,
+                            views
+                        });
+                    };
+                    try {
+                        return runContinuous(1);
+                    }
+                    catch (error) {
+                        if (!isFinish3Cap(error))
+                            throw error;
+                    }
+                    try {
+                        return runContinuous(FINISH_RETRY_SCALE);
+                    }
+                    catch (error) {
+                        if (!isFinish3Cap(error))
+                            throw error;
+                        return solveLegacyFinish(1);
+                    }
+                }
+                // The first legacy call seeds everything, so a flaky finish gets
+                // one retry with doubled caps before the whole finish is declared
+                // failed (formerly 150→300 / 50→100 wall budgets).
+                try {
+                    return await solveLegacyFinish(1);
+                }
+                catch {
+                    return solveLegacyFinish(FINISH_RETRY_SCALE);
                 }
+            }, {
+                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 } : {}),
+                finishScreenTop: finishOpts.mode === "legacy" ? 0 : finishOpts.screenTop ?? 0,
+                ...(options.maxFixMoves !== undefined ? { maxFixMoves: options.maxFixMoves } : {}),
+                ...(options.prepCap !== undefined ? { prepCap: options.prepCap } : {}),
+                ...(options.p1CandCap !== undefined ? { p1CandCap: options.p1CandCap } : {}),
+                ...(options.stagnationCut !== undefined ? { stagnationCut: options.stagnationCut } : {}),
+                maxReductionLen: bestReductionLen
+            });
+            let timeoutHandle;
+            // Honest scope: this race cannot interrupt the synchronous CPU-bound
+            // search — a setTimeout callback only runs at an event-loop tick, so
+            // the guard can fire only if the async solve chain yields for 90 s
+            // total. It exists solely so a pathological hang fails loudly
+            // (retryable Cube4WallTimeoutError) instead of wedging the host; it
+            // has never bound (max measured solve 36.5 s).
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Cube4WallTimeoutError("4x4 solve: timeout")), 90000);
+            });
+            let solveOutcome;
+            try {
+                solveOutcome = await Promise.race([solvePromise, timeoutPromise]);
             }
-            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
+            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 { scramble: scrambleMoves, moves: solutionMoves, phases, timings, nodes } = solveOutcome;
+            const fullSolution = rot.length === 0
+                ? solutionMoves
+                : placeRotationFix([], rot, solutionMoves);
+            const fullScramble = rot.length === 0
+                ? scrambleMoves
+                : invertCube4Algorithm(fullSolution);
+            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;
         }
     }
-    // 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);
+    if (!bestScrambleMoves || !bestSolutionMoves) {
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    const scrambleMoves = bestScrambleMoves;
+    const scrambledState = applyCube4Algorithm(createSolvedCube4State(), scrambleMoves);
+    if (!options.skipValidation) {
+        // Non-tautological gate: compare against `attemptState` — the state
+        // sampled for this seed (the same reference the sampler produced),
+        // NOT a state derived from the scramble. The former check
+        // (`apply(scramble, invert(scramble)) === solved`) passed by
+        // construction and hid frame bugs. A mismatch throws an error the
+        // retry loop classifies as retryable: `generateCube4Scramble` then
+        // re-runs the solve over this SAME `attemptState` (deep) and finally
+        // throws — it never re-samples another target.
+        assertCube4ScrambleReproducesTarget(scrambleMoves, attemptState, options.seed);
+    }
+    const facelets = toCube4Facelets(scrambledState);
+    const result = {
+        eventId: "444",
+        scramble: formatCube4Algorithm(scrambleMoves),
+        moves: scrambleMoves,
+        quality: "random-state",
+        generator: "cube4-reduction",
+        metadata: {
+            generator: "cube4-reduction",
+            // The sampled target — the independent reference the seed stands for
+            // (consistent with the 222/333/pymx/skwb/fto scramblers). When
+            // validation ran, this is exactly `apply(solved, moves)`; with
+            // `skipValidation` it stays the sampled truth so external checks can
+            // compare the emitted scramble against it instead of a derived state.
+            state: attemptState,
+            facelets,
+            faceletString: formatCube4Facelets(facelets),
+            distribution: "random-state",
+            // The scramble's inverse: by construction it solves the state the
+            // scramble actually produces, and (validation on) that state is
+            // `attemptState`.
+            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;
+    }
+    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"}