@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist/puzzles/cube4/scrambler.js

@@ -1,25 +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`).
  *
- * 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.
+ * 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, invertCube4Algorithm } from "./moves.js";
 import { generateRandomCube4State } from "./random-state.js";
-import { createSolvedCube4State, isSolvedCube4State } from "./state.js";
+import { createSolvedCube4State, cube4StatesEqual } from "./state.js";
 import { formatCube4Facelets, toCube4Facelets } from "./facelets.js";
-import { solveCube4State, applyCubeRotation, rotateAlgorithm } from "./reduction/solve.js";
-import { solveCube3State } from "../cube3/solver/index.js";
-import { loadCube3Phase1Tables } from "../cube3/solver/tables.js";
-import { loadCube3PairTables } from "../cube3/solver/pair-tables.js";
+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";
 // ────────────────────────────────────────────────────────────
-let cachedTables;
-async function loadCube4Tables(baseUrl) {
-    if (cachedTables)
-        return cachedTables;
+/**
+ * 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).
+ */
+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;
+}
+async function loadCube4TablesOnce(baseUrl) {
     const isBrowser = typeof window !== "undefined" ||
         typeof document !== "undefined" ||
         (typeof self !== "undefined" && typeof self.importScripts === "function") ||
@@ -32,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: {
@@ -60,65 +119,118 @@ export const cube4ScrambleGenerator = {
         return generateCube4Scramble(options);
     }
 };
-function invertRotationSequence(rotSeq) {
-    return rotSeq.slice().reverse().map((r) => (r.endsWith("'") ? r.slice(0, -1) : r.endsWith("2") ? r : `${r}'`));
+/**
+ * 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";
+    }
 }
-/** 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;
+/** 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";
+    }
 }
-function seedForBestJob(options, job) {
-    if (job === 0)
-        return options;
-    const next = { ...options };
-    if (options.seed !== undefined) {
-        next.seed = `${options.seed}:best${job}`;
+/**
+ * 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;
     }
-    else {
-        delete next.seed;
+    // 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 next;
+    return SOLVER_RETRYABLE_MESSAGE_PATTERNS.some((pattern) => error.message.includes(pattern));
 }
-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")));
+/**
+ * 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 = {}) {
-    const bestOf = Math.max(1, Math.floor(options.bestOf ?? 1) || 1);
     let tables;
-    let pairTables;
+    // 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 {
-        const [loadedTables, cube3P1Tables, loadedPairTables] = await Promise.all([
+        const continuousFinish = options.finish?.mode !== "legacy";
+        const [loadedTables, cube3P1Tables, cube3P2Tables] = await Promise.all([
             loadCube4Tables(),
             loadCube3Phase1Tables(),
-            loadCube3PairTables()
+            continuousFinish ? loadCube3Phase2Tables() : Promise.resolve(undefined)
         ]);
         tables = loadedTables;
         tables.cube3Phase1 = cube3P1Tables;
-        tables.pairTables = loadedPairTables;
-        pairTables = loadedPairTables;
+        if (cube3P2Tables !== undefined)
+            tables.cube3Phase2 = cube3P2Tables;
     }
     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);
+    const targetState = generateRandomCube4State(options);
     let lastError;
     try {
-        return await generateCube4Attempt(tables, pairTables, {
+        return await solveCube4Attempt(tables, pairTables, {
             ...options,
             restarts: totalRestarts
-        });
+        }, targetState);
     }
     catch (error) {
         if (!isRetryableCube4Error(error))
@@ -127,11 +239,11 @@ export async function generateCube4Scramble(options = {}) {
     }
     if (!options.deep) {
         try {
-            return await generateCube4Attempt(tables, pairTables, {
+            return await solveCube4Attempt(tables, pairTables, {
                 ...options,
                 restarts: totalRestarts,
                 deep: true
-            });
+            }, targetState);
         }
         catch (error) {
             if (isRetryableCube4Error(error))
@@ -146,12 +258,17 @@ export async function generateCube4Scramble(options = {}) {
 }
 /**
  * Single-attempt 444 solve: samples ONE state (from `options.seed`) and
- * solves it with the reduction solver. Throws on failure — no resampling.
+ * 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 = {}) {
-    const attemptState = generateRandomCube4State(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;
@@ -168,36 +285,84 @@ export async function generateCube4Attempt(tables, pairTables, options = {}) {
             // 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 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,
-                        targetLength: finishOpts.targetLength ?? 20,
-                        timeoutMs: timeBudget,
+                        // 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, timeoutMs: phase2Budget }
+                        phase2: {
+                            pairTables,
+                            skipPairTables: pairTables === undefined,
+                            maxNodes: Math.round((finishOpts.phase2MaxNodes ?? FINISH_PHASE2_MAX_NODES) * capScale)
+                        }
                     });
                     return { moves: solution.moves };
                 };
-                // The first call seeds everything, so a flaky finish gets one
-                // budgeted retry before the whole finish is declared failed.
+                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 solveFinish(finishOpts.timeoutMs ?? 150, finishOpts.phase2TimeoutMs ?? 50);
+                    return await solveLegacyFinish(1);
                 }
                 catch {
-                    return await solveFinish(finishOpts.retryTimeoutMs ?? 300, finishOpts.retryPhase2TimeoutMs ?? 100);
+                    return solveLegacyFinish(FINISH_RETRY_SCALE);
                 }
             }, {
-                timeoutMs: 75000,
                 deep: options.deep === true,
                 deepPolish: options.deepPolish ?? options.threeAxes,
                 ...(options.finishTries !== undefined ? { finishTries: options.finishTries } : {}),
@@ -207,14 +372,22 @@ export async function generateCube4Attempt(tables, pairTables, options = {}) {
                 ...(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 Error("4x4 solve: timeout")), 90000);
+                timeoutHandle = setTimeout(() => reject(new Cube4WallTimeoutError("4x4 solve: timeout")), 90000);
             });
             let solveOutcome;
             try {
@@ -227,9 +400,12 @@ export async function generateCube4Attempt(tables, pairTables, options = {}) {
                 clearTimeout(timeoutHandle);
             }
             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);
+            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;
@@ -249,13 +425,17 @@ export async function generateCube4Attempt(tables, pairTables, options = {}) {
         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.");
-        }
+        // 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 = {
@@ -266,10 +446,18 @@ export async function generateCube4Attempt(tables, pairTables, options = {}) {
         generator: "cube4-reduction",
         metadata: {
             generator: "cube4-reduction",
-            state: scrambledState,
+            // 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.

package/dist/puzzles/cube4/worker-pool.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Worker pool for 4x4 random-state scrambles (Node.js `worker_threads`).
+ *
+ * Why: generation is CPU-bound in a single event loop — a `Promise.all`
+ * batch of N scrambles does not scale. This pool spreads one batch across
+ * N threads so `generateScrambles`-style batches grow roughly linearly
+ * with core count, while keeping the (seed, complete-options) → moves
+ * contract byte-identical to the inline path: tasks forward the FULL
+ * options object verbatim and `worker.ts` calls the very same
+ * `generateCube4Scramble`.
+ *
+ * Lifecycle:
+ *  - Lazy spawn: threads are created on demand (one per queued job, up to
+ *    `size`), never in the constructor. A cold first generation pays for
+ *    table loading (≈37 MB) per spawned thread, once; the thread then
+ *    reuses its tables for every later job (per-thread promise cache inside
+ *    `scrambler.ts`).
+ *  - Idle threads are `unref()`d, so a pool that is never terminated does
+ *    not keep the process alive; in-flight jobs `ref()` their thread so an
+ *    awaited batch always completes.
+ *  - One task in flight per thread; extra tasks queue FIFO.
+ *  - `terminate()` rejects everything queued/in-flight with
+ *    `Cube4WorkerPoolClosedError` and joins all threads — after it
+ *    resolves there are no open handles.
+ *
+ * Failure: a crashed thread only fails ITS in-flight task and is dropped
+ * from the pool; the next dispatch spawns a fresh thread (which reloads
+ * tables). Typed solver errors from inside a worker arrive as an `Error`
+ * with the original `name`, `message` and `code` preserved (see
+ * `worker-protocol.ts`).
+ *
+ * Dual-build note: this file intentionally contains no bare `import.meta`
+ * (it must also compile in the CommonJS build that `index.ts` is part of).
+ * The worker entry is located from `__filename` (CJS) or this module's top
+ * stack frame (ESM), and `dist-cjs` falls back to the sibling ESM tree,
+ * which always ships `worker.js`.
+ */
+import type { ScrambleResult } from "../../core/types.js";
+import type { Cube4ScrambleOptions } from "./scrambler.js";
+import { type Cube4WorkerGenerationOptions } from "./worker-protocol.js";
+import type { ScrambleOptions } from "../../core/types.js";
+/** Full option surface accepted by the pool and the batch helper. */
+export type Cube4PoolOptions = Cube4WorkerGenerationOptions;
+export interface Cube4WorkerPoolOptions {
+    /**
+     * Maximum number of worker threads. Defaults to
+     * `os.availableParallelism() - 1` (min 1), resolved lazily so importing
+     * this module costs nothing.
+     */
+    size?: number;
+    /**
+     * Explicit path to the worker entry (`worker.ts` / `worker.js`).
+     * Auto-resolved normally; pass this only if the automatic location
+     * fails (e.g. a bundler renamed this module).
+     */
+    workerPath?: string;
+}
+/** Typed rejection used for post-terminate operations and shutdown itself. */
+export declare class Cube4WorkerPoolClosedError extends Error {
+    readonly code: "cube4-pool-closed";
+    constructor(action?: string);
+}
+/**
+ * Batch seed derivation — byte-for-byte the semantics of
+ * `deriveBatchScrambleOptions` in `src/core/api.ts` (`generateScrambles`):
+ * with a `seed` and `count > 1`, item i uses `${seed}:${i}`; otherwise the
+ * options pass through untouched. Exported so tests can assert the pool
+ * batch equals the sequential/core batch for the same inputs.
+ */
+export declare function deriveBatchCube4Options(options: Cube4PoolOptions, index: number, count: number): Cube4PoolOptions;
+export declare class Cube4WorkerPool {
+    private readonly workers;
+    private readonly queue;
+    private readonly explicitSize;
+    private readonly workerPathOption;
+    private sizePromise;
+    /** Last resolved size, kept sync-readable for the pump's headroom check. */
+    private sizeSync;
+    private pumping;
+    private terminatePromise;
+    private nextId;
+    private terminated;
+    constructor(options?: Cube4WorkerPoolOptions);
+    /** Maximum thread count (resolves the default lazily on first use). */
+    get size(): Promise<number>;
+    /** Threads spawned so far (lazily grown; 0 before the first job). */
+    get workerCount(): number;
+    get queuedCount(): number;
+    get busyCount(): number;
+    get closed(): boolean;
+    /**
+     * Generates one scramble on an available thread. Rejects (typed) if the
+     * pool is closed, the worker crashes, the options cannot be
+     * structured-cloned, or generation fails inside the worker.
+     */
+    generate(options?: Cube4PoolOptions): Promise<ScrambleResult>;
+    /**
+     * Batch generation with EXACTLY the seed derivation of core
+     * `generateScrambles` (see `deriveBatchCube4Options`), so results are
+     * identical — move for move — to the sequential path for the same
+     * inputs. Order of the returned array matches request order regardless
+     * of completion order.
+     */
+    generateBatch(count: number, options?: Cube4PoolOptions): Promise<ScrambleResult[]>;
+    /**
+     * Prompt shutdown: rejects queued and in-flight tasks with
+     * `Cube4WorkerPoolClosedError`, terminates every thread and resolves
+     * when none is left. Idempotent.
+     */
+    terminate(): Promise<void>;
+    private resolveSize;
+    /**
+     * Serialised dispatcher: grows the pool (lazy spawn), hands queued jobs
+     * to idle threads, and stops when every thread is busy at capacity.
+     * Re-entry while a spawn is awaited is a no-op — the running loop's
+     * `while` re-checks the queue, and every completion event (`response`,
+     * `crash`) calls `pump()` again.
+     */
+    private pump;
+    private hasDispatchHeadroom;
+    private runPump;
+    private spawnWorker;
+    private dispatch;
+    private handleResponse;
+    private handleWorkerGone;
+    private resolveWorkerEntry;
+}
+/** Shared lazily-created pool (used by `generateCube4ScrambleBatch`). */
+export declare function getDefaultCube4WorkerPool(): Cube4WorkerPool;
+/** Terminates (and forgets) the shared pool — call on process shutdown. */
+export declare function closeDefaultCube4WorkerPool(): Promise<void>;
+/**
+ * Batch convenience mirroring core `generateScrambles` for `444`:
+ *  - `count <= 1` runs INLINE in the caller (no thread spawn, no cold
+ *    start — a single scramble must never get slower);
+ *  - `count > 1` fans out over the shared pool (same seed derivation).
+ */
+export declare function generateCube4ScrambleBatch(count: number, options?: ScrambleOptions & Cube4ScrambleOptions): Promise<ScrambleResult[]>;
+//# sourceMappingURL=worker-pool.d.ts.map

package/dist/puzzles/cube4/worker-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.d.ts","sourceRoot":"","sources":["../../../src/puzzles/cube4/worker-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAEL,KAAK,4BAA4B,EAGlC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAE5D,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8EAA8E;AAC9E,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;gBAEjC,MAAM,SAAc;CAIjC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,gBAAgB,CAKlB;AAsED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,WAAW,CAA8B;IACjD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,GAAE,sBAA2B;IAWhD,uEAAuE;IACvE,IAAI,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1B;IAED,qEAAqE;IACrE,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,QAAQ,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAWjE;;;;;;OAMG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAWvF;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB1B,OAAO,CAAC,WAAW;IAmBnB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;IAiBZ,OAAO,CAAC,mBAAmB;YAKb,OAAO;YAuBP,WAAW;IA6BzB,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,cAAc;IAetB,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,kBAAkB;CAkC3B;AAMD,yEAAyE;AACzE,wBAAgB,yBAAyB,IAAI,eAAe,CAG3D;AAED,2EAA2E;AAC3E,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAIjE;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAe,GAAG,oBAAyB,GACnD,OAAO,CAAC,cAAc,EAAE,CAAC,CAQ3B"}