@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist-cjs/puzzles/cube4/scramble-cache.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Background prefetch buffer for 4x4 scrambles — the Node-side analogue of
+ * TNoodle's `ScrambleCacher`.
+ *
+ * The cache keeps up to `size` scrambles generating AHEAD of consumption:
+ *  - `take()` shifts the OLDEST slot; if it is already settled it resolves
+ *    immediately (no waiting for later slots), otherwise it awaits only
+ *    that slot. Order is FIFO of START (not of completion), so a seeded
+ *    stream hands out `seed:0`, `seed:1`, … in order even when the
+ *    underlying generator finishes out of order (parallel pool).
+ *  - every shift triggers a refill, so the buffer repopulates in the
+ *    background — wire `generate: (o) => pool.generate(o)` and the refill
+ *    itself runs across worker threads (see the pool integration test).
+ *  - failures are FIRST-CLASS slots: a slot that rejects is delivered as a
+ *    rejection to the next `take()` (consumed exactly once) and the cache
+ *    keeps going with the following slots. Every slot promise is wrapped
+ *    at creation so a background failure can NEVER surface as an
+ *    unhandledRejection, and `take()` never hangs: slots always settle
+ *    (the generator contract is "settles eventually").
+ *  - `dispose()` stops refilling and drops buffered slots. In-flight
+ *    generations are left to settle silently (results discarded). There
+ *    are NO timers anywhere, so a disposed (or even forgotten) cache never
+ *    keeps a process alive.
+ *
+ * Seeding: when `options.seed` is defined, slot n is generated with
+ * `${seed}:${n}` — byte-identical to core `generateScrambles("444", …)`
+ * for any count > 1 (slot 0 ↔ item 0 of a batch). Without a seed every
+ * slot uses the base options unchanged (fresh randomness).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cube4ScrambleCache = void 0;
+exports.deriveCube4StreamOptions = deriveCube4StreamOptions;
+exports.createCube4ScrambleCache = createCube4ScrambleCache;
+const scrambler_js_1 = require("./scrambler.js");
+/**
+ * Stream slot derivation (cache analogue of core's batch derivation).
+ * Exported for tests and for hosts that precompute the same sequence.
+ */
+function deriveCube4StreamOptions(options, index) {
+    if (options.seed === undefined)
+        return options;
+    return { ...options, seed: `${options.seed}:${index}` };
+}
+class Cube4ScrambleCache {
+    capacity;
+    baseOptions;
+    generator;
+    /** FIFO of slots (start order); settled or still pending. */
+    slots = [];
+    nextIndex = 0;
+    disposed = false;
+    constructor(options = {}) {
+        const size = options.size ?? 4;
+        if (!Number.isInteger(size) || size < 1) {
+            throw new RangeError(`[cube4] cache size must be an integer >= 1 (got ${size}).`);
+        }
+        this.capacity = size;
+        this.baseOptions = options.options ?? {};
+        this.generator = options.generate ?? scrambler_js_1.generateCube4Scramble;
+        // Prefetch starts immediately: that is the point of constructing a cache.
+        this.pump();
+    }
+    /** Configured buffer capacity. */
+    get size() {
+        return this.capacity;
+    }
+    /** Slots currently buffered (settled + still generating). */
+    get buffered() {
+        return this.slots.length;
+    }
+    /** Buffered slots that have already settled (ready for an instant take()). */
+    get ready() {
+        let count = 0;
+        for (const carrier of this.slots)
+            if (carrier.slot !== undefined)
+                count++;
+        return count;
+    }
+    /** Slots currently generating in the background. */
+    get inFlight() {
+        let count = 0;
+        for (const carrier of this.slots)
+            if (carrier.slot === undefined)
+                count++;
+        return count;
+    }
+    get isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * Resolves once the buffer holds `size` settled results (i.e. a
+     * subsequent `take()` is served instantly). Safe to call at any time;
+     * rejects only if called after `dispose()`.
+     */
+    warmup() {
+        if (this.disposed) {
+            return Promise.reject(new Error("[cube4] scramble cache is disposed (warmup)."));
+        }
+        this.pump();
+        return Promise.all(this.slots.map((carrier) => carrier.promise)).then(() => undefined);
+    }
+    /**
+     * Next scramble in FIFO order. Instant when the front slot is settled;
+     * otherwise waits only for the front slot (never for later ones).
+     * A failed background generation surfaces here as a rejection — exactly
+     * once — and the cache continues with subsequent slots.
+     */
+    take() {
+        if (this.disposed) {
+            return Promise.reject(new Error("[cube4] scramble cache is disposed (take)."));
+        }
+        const carrier = this.slots.shift();
+        this.pump(); // refill BEFORE awaiting, so generation overlaps consumption
+        if (carrier === undefined) {
+            // Only reachable when capacity was somehow drained concurrently;
+            // generate one on the spot rather than hang.
+            return this.generateNow();
+        }
+        return carrier.promise.then((slot) => {
+            if (slot.ok)
+                return slot.result;
+            throw slot.error;
+        });
+    }
+    /**
+     * Stops prefetching, drops buffered slots and ignores in-flight
+     * completions. No timers are involved, so nothing can keep a process
+     * alive afterwards. Idempotent.
+     */
+    dispose() {
+        this.disposed = true;
+        this.slots.length = 0;
+    }
+    // ── internals ────────────────────────────────────────────────────────
+    pump() {
+        while (!this.disposed && this.slots.length < this.capacity) {
+            const index = this.nextIndex++;
+            const promise = this.generator(deriveCube4StreamOptions(this.baseOptions, index)).then((result) => ({ ok: true, result }), (error) => ({ ok: false, error }));
+            const carrier = { promise, slot: undefined };
+            void promise.then((slot) => {
+                carrier.slot = slot;
+            });
+            this.slots.push(carrier);
+        }
+    }
+    generateNow() {
+        const index = this.nextIndex++;
+        return this.generator(deriveCube4StreamOptions(this.baseOptions, index));
+    }
+}
+exports.Cube4ScrambleCache = Cube4ScrambleCache;
+/** Convenience factory mirroring the other cube4 constructors. */
+function createCube4ScrambleCache(options = {}) {
+    return new Cube4ScrambleCache(options);
+}

package/dist-cjs/puzzles/cube4/scrambler.js

@@ -1,12 +1,40 @@
 "use strict";
 /**
  * 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.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -42,7 +70,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cube4ScrambleGenerator = void 0;
+exports.Cube4WallTimeoutError = exports.Cube4TargetMismatchError = exports.cube4ScrambleGenerator = void 0;
+exports.assertCube4ScrambleReproducesTarget = assertCube4ScrambleReproducesTarget;
 exports.generateCube4Scramble = generateCube4Scramble;
 exports.generateCube4Attempt = generateCube4Attempt;
 const moves_js_1 = require("./moves.js");
@@ -52,12 +81,48 @@ const facelets_js_1 = require("./facelets.js");
 const solve_js_1 = require("./reduction/solve.js");
 const index_js_1 = require("../cube3/solver/index.js");
 const tables_js_1 = require("../cube3/solver/tables.js");
-const pair_tables_js_1 = require("../cube3/solver/pair-tables.js");
+const finish3_js_1 = require("./reduction/finish3.js");
+const rotation_fix_js_1 = require("./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") ||
@@ -70,20 +135,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 Promise.resolve().then(() => __importStar(require(
     /* webpackIgnore: true */
     /* @vite-ignore */
     "./reduction/node-loader.js")));
-    const tables = await loader.loadCube4ReductionTables();
-    cachedTables = tables;
-    return tables;
+    return await loader.loadCube4ReductionTables();
 }
 exports.cube4ScrambleGenerator = {
     info: {
@@ -98,65 +158,120 @@ exports.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.
+ */
+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;
+exports.Cube4TargetMismatchError = Cube4TargetMismatchError;
+/** Thrown by the 90 s hang guard (wall-clock, fires only at a tick). */
+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}`;
+exports.Cube4WallTimeoutError = 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 finish3_js_1.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 solve_js_1.Cube4Phase2CapError ||
+        error instanceof solve_js_1.Cube4Phase3CapError ||
+        error instanceof solve_js_1.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 index_js_1.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 index_js_1.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.
+ */
+function assertCube4ScrambleReproducesTarget(scrambleMoves, targetState, seed) {
+    const replayed = (0, moves_js_1.applyCube4Algorithm)((0, state_js_1.createSolvedCube4State)(), scrambleMoves);
+    if (!(0, state_js_1.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).");
+    }
 }
 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(),
             (0, tables_js_1.loadCube3Phase1Tables)(),
-            (0, pair_tables_js_1.loadCube3PairTables)()
+            continuousFinish ? (0, tables_js_1.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 = (0, random_state_js_1.generateRandomCube4State)(options);
     let lastError;
     try {
-        return await generateCube4Attempt(tables, pairTables, {
+        return await solveCube4Attempt(tables, pairTables, {
             ...options,
             restarts: totalRestarts
-        });
+        }, targetState);
     }
     catch (error) {
         if (!isRetryableCube4Error(error))
@@ -165,11 +280,11 @@ 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))
@@ -184,12 +299,17 @@ 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.
  */
 async function generateCube4Attempt(tables, pairTables, options = {}) {
-    const attemptState = (0, random_state_js_1.generateRandomCube4State)(options);
+    return solveCube4Attempt(tables, pairTables, options, (0, random_state_js_1.generateRandomCube4State)(options));
+}
+async function solveCube4Attempt(tables, pairTables, options, attemptState) {
     const axes = options.threeAxes ? [[], ["z"], ["y'"]] : [[]];
     let bestScrambleMoves = null;
     let bestSolutionMoves = null;
@@ -206,36 +326,84 @@ 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 = (0, solve_js_1.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 = (0, solve_js_1.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 (0, index_js_1.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 (0, tables_js_1.loadCube3Phase1Tables)();
+                    tables.cube3Phase2 ??= await (0, tables_js_1.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 (0, finish3_js_1.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 } : {}),
@@ -245,14 +413,22 @@ 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 {
@@ -265,9 +441,12 @@ 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 : (0, solve_js_1.rotateAlgorithm)(scrambleMoves, invRot);
-            const fullSolution = rot.length === 0 ? solutionMoves : (0, solve_js_1.rotateAlgorithm)(solutionMoves, invRot);
+            const fullSolution = rot.length === 0
+                ? solutionMoves
+                : (0, rotation_fix_js_1.placeRotationFix)([], rot, solutionMoves);
+            const fullScramble = rot.length === 0
+                ? scrambleMoves
+                : (0, moves_js_1.invertCube4Algorithm)(fullSolution);
             if (!bestScrambleMoves || fullScramble.length < bestScrambleMoves.length) {
                 bestScrambleMoves = fullScramble;
                 bestSolutionMoves = fullSolution;
@@ -287,13 +466,17 @@ async function generateCube4Attempt(tables, pairTables, options = {}) {
         throw lastError instanceof Error ? lastError : new Error(String(lastError));
     }
     const scrambleMoves = bestScrambleMoves;
-    const solutionMoves = bestSolutionMoves;
     const scrambledState = (0, moves_js_1.applyCube4Algorithm)((0, state_js_1.createSolvedCube4State)(), scrambleMoves);
     if (!options.skipValidation) {
-        const solvedCheck = (0, moves_js_1.applyCube4Algorithm)(scrambledState, solutionMoves);
-        if (!(0, state_js_1.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 = (0, facelets_js_1.toCube4Facelets)(scrambledState);
     const result = {
@@ -304,10 +487,18 @@ 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: (0, facelets_js_1.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: (0, moves_js_1.invertCube4Algorithm)(scrambleMoves),
             // Winning-reduction breakdown (unsimplified lengths) + wall-clock
             // split, for tuning and A/B comparisons.