@cubingcenter/scrambler 0.5.3 → 0.6.0

package/dist-cjs/puzzles/cube4/reduction/pairing-coordinate.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Pairing coordinate (phase 3 of the 4x4 reduction solver).
+ *
+ * Semantics ported from the reference `scramble_444.js` (Edge3 class) and
+ * adapted to this repo's position numbering.
+ *
+ * The pairing state is the *relative* permutation between the two halves of
+ * the edge slots: `edge[i]` = the slot whose second half holds the pair
+ * occupying slot i's first half. It exists (and `edge == identity` iff all
+ * 12 slots are paired) only for states with the *transversal* property:
+ * the 12 second-half positions must hold exactly one wing of each pair.
+ *
+ * Slot convention: the reference's `FullEdgeMap` slot layout, converted to
+ * this repo's position numbering (via the sticker isomorphism between the
+ * two layouts). It is co-adapted with the phase-3 move set — all 20 moves
+ * preserve the transversal property (verified: 0 breaks over random walks).
+ * A naive even/odd split does NOT work (Rw2/Lw2 break the transversal).
+ *
+ * The phase-3 move set contains ONLY even wing-permutation moves (face
+ * turns + double wide turns), so wing parity is invariant in this phase and
+ * is tracked by the caller (Center3 coordinate), never here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAIRING_SECOND_HALVES = exports.PAIRING_FIRST_HALVES = exports.PAIRING_SLOTS = exports.PAIRING_BFS_MOVES = exports.PAIRING_MOVES = void 0;
+exports.pairIdArray = pairIdArray;
+exports.applyPairingMoveToArray = applyPairingMoveToArray;
+exports.hasPairingTransversal = hasPairingTransversal;
+exports.pairingGateParity = pairingGateParity;
+exports.encodePairingState = encodePairingState;
+exports.decodePairingState = decodePairingState;
+exports.isPairingReduced = isPairingReduced;
+exports.applyPairingMoveToState = applyPairingMoveToState;
+exports.normalizePairingState = normalizePairingState;
+exports.verifyPairingCoordinate = verifyPairingCoordinate;
+const types_js_1 = require("../types.js");
+const moves_js_1 = require("../moves.js");
+// ---------------------------------------------------------------------------
+// Move sets
+// ---------------------------------------------------------------------------
+/**
+ * Phase-3 move set (20 moves, the reference's `move3std` minus its trailing
+ * no-op sentinel — index 36, used only as the "previous move" dummy for
+ * cancellation pruning): face turns + double wide turns. All of them are
+ * even wing permutations.
+ */
+exports.PAIRING_MOVES = [
+    "U", "U2", "U'", "R2", "F", "F2", "F'", "D", "D2", "D'",
+    "L2", "B", "B2", "B'", "Uw2", "Rw2", "Fw2", "Dw2", "Lw2", "Bw2"
+];
+/**
+ * The 17-move BFS subset used to build the pruning table (reference
+ * `bfsMoves`): omits Dw2/Lw2/Bw2 (rotation-conjugate to Uw2/Rw2/Fw2).
+ */
+exports.PAIRING_BFS_MOVES = [
+    "U2", "U", "U'", "R2", "F2", "F", "F'", "D2", "D", "D'",
+    "L2", "B2", "B", "B'", "Uw2", "Rw2", "Fw2"
+];
+// ---------------------------------------------------------------------------
+// Slot layout
+// ---------------------------------------------------------------------------
+/**
+ * The 12 edge slots as (first-half, second-half) position pairs, in this
+ * repo's position numbering. Derived from the reference's `FullEdgeMap`
+ * through the sticker isomorphism between the two layouts:
+ *
+ *   slot i = (π(FullEdgeMap[i]), π(FullEdgeMap[i] + 12))
+ *
+ * where π maps the reference's position ids to ours by matching the two
+ * stickers of each wing position. The phase-3 move set preserves the
+ * transversal property for exactly this split.
+ */
+exports.PAIRING_SLOTS = [
+    [3, 2], [7, 6], [14, 15], [10, 11], [5, 4], [0, 1],
+    [9, 8], [12, 13], [19, 18], [20, 21], [23, 22], [16, 17]
+];
+/** First-half position of each slot. */
+exports.PAIRING_FIRST_HALVES = exports.PAIRING_SLOTS.map(([f]) => f);
+/** Second-half position of each slot. */
+exports.PAIRING_SECOND_HALVES = exports.PAIRING_SLOTS.map(([, s]) => s);
+// ---------------------------------------------------------------------------
+// Pair-id array (ground truth of the pairing state)
+// ---------------------------------------------------------------------------
+/**
+ * Map the 24 labeled wings to their pair ids: `arr24[i] = wp[i] >> 1`.
+ * Each pair id 0-11 appears exactly twice.
+ */
+function pairIdArray(wp) {
+    const arr = new Uint8Array(24);
+    for (let i = 0; i < 24; i++)
+        arr[i] = wp[i] >> 1;
+    return arr;
+}
+/**
+ * Apply a move to a 24-entry pair-id array (position permutation from the
+ * verified move tables).
+ */
+function applyPairingMoveToArray(arr24, move) {
+    const { face, turns } = (0, moves_js_1.parseMove)(move);
+    const effect = moves_js_1.FACE_MOVE_EFFECTS[face];
+    let current = arr24;
+    for (let t = 0; t < turns; t++) {
+        const next = new Uint8Array(24);
+        for (let i = 0; i < 24; i++)
+            next[i] = current[effect.wperm[i]];
+        current = next;
+    }
+    return current;
+}
+// ---------------------------------------------------------------------------
+// Transversal gate
+// ---------------------------------------------------------------------------
+/**
+ * True iff the 12 second-half positions hold exactly one wing of each pair —
+ * i.e. the pair ids there are all distinct. Required by `encodePairingState`
+ * and preserved by the phase-3 move set (verified).
+ */
+function hasPairingTransversal(wp) {
+    const seen = new Uint8Array(12);
+    for (const s of exports.PAIRING_SECOND_HALVES) {
+        const pair = wp[s] >> 1;
+        if (seen[pair] !== 0)
+            return false;
+        seen[pair] = 1;
+    }
+    return true;
+}
+/**
+ * Wing-permutation parity of the state. For transversal-eligible states this
+ * is the phase-2 → phase-3 filter parity (the reference's `checkPhase2Edge`
+ * `parity == 0` condition, verified equivalent): the bridge must only accept
+ * even-parity states so the derived 3x3 edge permutation comes out even.
+ */
+function pairingGateParity(wp) {
+    let parity = 0;
+    const seen = new Array(24).fill(false);
+    for (let start = 0; start < 24; start++) {
+        if (seen[start] || wp[start] === start)
+            continue;
+        let length = 0;
+        let current = start;
+        while (!seen[current]) {
+            seen[current] = true;
+            current = wp[current];
+            length++;
+        }
+        parity ^= (length - 1) & 1;
+    }
+    return parity;
+}
+/**
+ * Encode a 24-labeled-wing state to the pairing permutation.
+ *
+ * Requires the transversal property (`hasPairingTransversal`), else null.
+ *
+ * Construction (reference $set_6, adapted to PAIRING_SLOTS):
+ *  - `edge[i]` starts as the pair id at the second-half position of slot i
+ *  - cycle-sort it to identity while tracking the inverse `temp` and parity
+ *  - `edge[i] = temp[pair id at the first-half position of slot i]`
+ *
+ * The result is in $std-normalized form (second halves implicitly hold
+ * pairs 0..11 in order).
+ */
+function encodePairingState(wp) {
+    if (!hasPairingTransversal(wp))
+        return null;
+    const temp = new Uint8Array(12);
+    const edge = new Uint8Array(12);
+    for (let i = 0; i < 12; i++) {
+        temp[i] = i;
+        edge[i] = wp[exports.PAIRING_SECOND_HALVES[i]] >> 1;
+    }
+    let parity = 1;
+    for (let i = 0; i < 12; i++) {
+        while (edge[i] !== i) {
+            const t = edge[i];
+            edge[i] = edge[t];
+            edge[t] = t;
+            const s = temp[i];
+            temp[i] = temp[t];
+            temp[t] = s;
+            parity ^= 1;
+        }
+    }
+    for (let i = 0; i < 12; i++) {
+        edge[i] = temp[wp[exports.PAIRING_FIRST_HALVES[i]] >> 1];
+    }
+    return { edge, parity: parity };
+}
+/**
+ * Decode the canonical representative: slot i's first-half position holds the
+ * even wing of pair `edge[i]`, its second-half position the odd wing of pair
+ * `edgeo[i]`. With `edgeo = identity` this is the $set_4 canonical form.
+ */
+function decodePairingState(edge, edgeo) {
+    const wp = new Uint8Array(24);
+    for (let i = 0; i < 12; i++) {
+        wp[exports.PAIRING_FIRST_HALVES[i]] = 2 * edge[i];
+        wp[exports.PAIRING_SECOND_HALVES[i]] = 2 * edgeo[i] + 1;
+    }
+    return wp;
+}
+/**
+ * True iff the pairing permutation is fully reduced (all 12 slots paired).
+ */
+function isPairingReduced(edge) {
+    for (let i = 0; i < 12; i++) {
+        if (edge[i] !== i)
+            return false;
+    }
+    return true;
+}
+/**
+ * Apply a phase-3 move to a pairing state, keeping the (edge, edgeo)
+ * representation: decode → physical move (verified move tables) → re-derive
+ * the slot halves → $std-normalize. Valid because the phase-3 move set
+ * preserves the transversal property (verified).
+ */
+function applyPairingMoveToState(edge, edgeo, move) {
+    const wp = decodePairingState(edge, edgeo);
+    const arr24 = applyPairingMoveToArray(pairIdArray(wp), move);
+    const e = new Uint8Array(12);
+    const eo = new Uint8Array(12);
+    for (let i = 0; i < 12; i++) {
+        e[i] = arr24[exports.PAIRING_FIRST_HALVES[i]];
+        eo[i] = arr24[exports.PAIRING_SECOND_HALVES[i]];
+    }
+    return normalizePairingState(e, eo);
+}
+/**
+ * $std-normalize a pairing state: reindex so the second halves hold pairs
+ * 0..11 in order (the `edgeo` array becomes the identity).
+ */
+function normalizePairingState(edge, edgeo) {
+    const temp = new Uint8Array(12);
+    for (let i = 0; i < 12; i++)
+        temp[edgeo[i]] = i;
+    const out = new Uint8Array(12);
+    const identity = new Uint8Array(12);
+    for (let i = 0; i < 12; i++) {
+        out[i] = temp[edge[i]];
+        identity[i] = i;
+    }
+    return { edge: out, edgeo: identity };
+}
+// ---------------------------------------------------------------------------
+// Verification gates
+// ---------------------------------------------------------------------------
+function verifyPairingCoordinate() {
+    const errors = [];
+    for (const move of exports.PAIRING_MOVES) {
+        if (!types_js_1.CUBE4_ALL_MOVES.includes(move)) {
+            errors.push(`Pairing move ${move} is not a valid 4x4 move.`);
+        }
+    }
+    // The slot halves must be a bijection over the 24 positions.
+    const seen = new Set();
+    for (const [f, s] of exports.PAIRING_SLOTS) {
+        if (f < 0 || f > 23 || s < 0 || s > 23)
+            errors.push(`Slot out of range: (${f}, ${s}).`);
+        seen.add(f);
+        seen.add(s);
+    }
+    if (seen.size !== 24) {
+        errors.push(`Pairing slots do not cover the 24 positions (${seen.size} distinct).`);
+    }
+    // All phase-3 moves must be even wing permutations (parity is invariant in
+    // this phase and tracked by the caller).
+    for (const move of exports.PAIRING_MOVES) {
+        const { face, turns } = (0, moves_js_1.parseMove)(move);
+        const parity = wingPermutationParity(moves_js_1.FACE_MOVE_EFFECTS[face].wperm) * (turns & 1);
+        if ((parity & 1) !== 0) {
+            errors.push(`Pairing move ${move} has odd wing permutation parity.`);
+        }
+    }
+    return errors;
+}
+function wingPermutationParity(perm) {
+    let parity = 0;
+    const seen = new Array(perm.length).fill(false);
+    for (let start = 0; start < perm.length; start++) {
+        if (seen[start] || perm[start] === start)
+            continue;
+        let length = 0;
+        let current = start;
+        while (!seen[current]) {
+            seen[current] = true;
+            current = perm[current];
+            length++;
+        }
+        parity ^= (length - 1) & 1;
+    }
+    return parity;
+}

package/dist-cjs/puzzles/cube4/reduction/phase3-search.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Fast table-driven Phase-3 search (Center3 + Edge3).
+ *
+ * Solves the joint state from Phase 2 to fully-solved monochrome centers (ct3 == 0)
+ * and all 12 wing pairs paired (sym-index == 0), using the 17-move exploration set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FastPhase3Solver = exports.skipAxis3 = exports.ckmv3 = exports.SEARCH_MOVES = void 0;
+exports.solvePhase3 = solvePhase3;
+const center3_js_1 = require("./center3.js");
+const edge3_js_1 = require("./edge3.js");
+/** The 17 exploration moves (the reference's m < 17 bound). */
+exports.SEARCH_MOVES = center3_js_1.CENTER3_MOVES.slice(0, 17);
+// Commutation / move-cancellation pruning tables
+const ckmv = Array.from({ length: 37 }, () => new Array(36).fill(false));
+for (let i = 0; i < 36; i++) {
+    for (let j = 0; j < 36; j++) {
+        ckmv[i][j] =
+            Math.floor(i / 3) === Math.floor(j / 3) ||
+                (Math.floor(i / 3) % 3 === Math.floor(j / 3) % 3 && i > j);
+    }
+    ckmv[36][i] = false;
+}
+exports.ckmv3 = Array.from({ length: 21 }, () => new Array(20).fill(false));
+for (let i = 0; i < 21; i++) {
+    for (let j = 0; j < 20; j++) {
+        exports.ckmv3[i][j] = ckmv[edge3_js_1.MOVE3_STD[i]][edge3_js_1.MOVE3_STD[j]];
+    }
+}
+exports.skipAxis3 = new Array(20).fill(20);
+for (let i = 0; i < 20; i++) {
+    for (let j = i; j < 20; j++) {
+        if (!exports.ckmv3[i][j]) {
+            exports.skipAxis3[i] = j - 1;
+            break;
+        }
+    }
+}
+/**
+ * Fast table-driven Phase 3 IDA* solver class.
+ */
+class FastPhase3Solver {
+    tempep;
+    moveLog;
+    sym;
+    constructor() {
+        this.tempep = Array.from({ length: 30 }, () => new Uint8Array(12));
+        this.moveLog = new Array(30);
+        this.sym = (0, edge3_js_1.getSymTables)();
+    }
+    getPrun(distances, idx) {
+        const byte = distances[idx >> 1];
+        return (idx & 1) === 0 ? byte & 0x0f : byte >> 4;
+    }
+    /**
+     * Recursive IDA* worker on table transitions.
+     */
+    async search(eplast, ct, prun, maxl, lm, depth, center3Tables, edge3Distances) {
+        if (maxl === 0)
+            return true;
+        if (depth % 500 === 0)
+            await new Promise(r => setTimeout(r, 0));
+        const ep = this.tempep[depth];
+        if (lm !== 20) {
+            const movoBase = (lm << 3) * 12;
+            const movBase = (lm << 3) * 12;
+            for (let i = 0; i < 12; i++) {
+                ep[i] = this.sym.mvroto[movoBase + eplast[this.sym.mvrot[movBase + i]]];
+            }
+        }
+        else {
+            ep.set(eplast);
+        }
+        for (let m = 0; m < 17; m++) {
+            if (exports.ckmv3[lm][m]) {
+                m = exports.skipAxis3[m];
+                continue;
+            }
+            const nc = center3Tables.moveTable[ct * center3_js_1.CENTER3_MOVES.length + m];
+            if (nc < 0)
+                continue;
+            const prun1 = center3Tables.pruning[nc];
+            if (prun1 >= maxl) {
+                if (prun1 > maxl && m < 14)
+                    m = exports.skipAxis3[m];
+                continue;
+            }
+            const symIdx = (0, edge3_js_1.getMvSymFrom)(ep, ep, m, this.sym.sym2Raw, this.sym.sym2Mask, this.sym.raw2Sym, this.sym.mvrot, this.sym.mvroto);
+            const prunx = this.getPrun(edge3Distances, symIdx >> 3);
+            if (prunx >= maxl) {
+                if (prunx > maxl && m < 14)
+                    m = exports.skipAxis3[m];
+                continue;
+            }
+            if (await this.search(ep, nc, prunx, maxl - 1, m, depth + 1, center3Tables, edge3Distances)) {
+                this.moveLog[depth] = m;
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Search for a phase-3 solution with exact target length.
+     */
+    async solveLength(edge, ct3, edist, length3, center3Tables, edge3Distances) {
+        this.tempep[0].set(edge);
+        if (await this.search(this.tempep[0], ct3, edist, length3, 20, 0, center3Tables, edge3Distances)) {
+            return this.moveLog.slice(0, length3).map((m) => exports.SEARCH_MOVES[m]);
+        }
+        return null;
+    }
+}
+exports.FastPhase3Solver = FastPhase3Solver;
+const defaultSolver = new FastPhase3Solver();
+/**
+ * Solve Phase 3 with iterative deepening on a single Phase3Start.
+ */
+async function solvePhase3(start, center3Tables, edge3Tables, maxLength = 20) {
+    const sym = (0, edge3_js_1.getSymTables)();
+    const symIdx = (0, edge3_js_1.getMvSymFrom)(start.edge, start.edge, 20, sym.sym2Raw, sym.sym2Mask, sym.raw2Sym, sym.mvrot, sym.mvroto);
+    const edist = (edge3Tables.distances[(symIdx >> 3) >> 1] >> (((symIdx >> 3) & 1) * 4)) & 0x0f;
+    const cdist = center3Tables.pruning[start.ct3];
+    if (cdist === 0xff || edist === 0x0f)
+        return null;
+    const minLength = Math.max(cdist, edist);
+    for (let l = minLength; l <= maxLength; l++) {
+        const moves = await defaultSolver.solveLength(start.edge, start.ct3, edist, l, center3Tables, edge3Tables.distances);
+        if (moves) {
+            return {
+                moves,
+                ct3: 0,
+                edge: Uint8Array.from({ length: 12 }, (_, i) => i)
+            };
+        }
+    }
+    return null;
+}

package/dist-cjs/puzzles/cube4/reduction/phase3.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Phase-2 → phase-3 bridge + the joint phase-3 search (Center3 + Edge3).
+ *
+ * The phase-3 pairing coordinate requires the wing transversal: the phase-2
+ * solutions' end states are otherwise almost never eligible (~0.15% of
+ * states, and the T-space is closed under the phase-3 moves), so the bridge
+ * runs the phase-2 search with the wings tracked and the transversal checked
+ * at the goal (see `solveCenter2Gated`). For the rare states where one
+ * phase-1 solution offers no eligible end, the bridge retries with the
+ * alternative phase-1 solutions (their outputs differ in the wings).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgePhase2To3 = bridgePhase2To3;
+const moves_js_1 = require("../moves.js");
+const center1_js_1 = require("./center1.js");
+const center2_js_1 = require("./center2.js");
+const center3_js_1 = require("./center3.js");
+const pairing_coordinate_js_1 = require("./pairing-coordinate.js");
+function cornerPermutationParity(cp) {
+    let parity = 0;
+    const seen = new Array(8).fill(false);
+    for (let start = 0; start < 8; start++) {
+        if (seen[start] || cp[start] === start)
+            continue;
+        let length = 0;
+        let current = start;
+        while (!seen[current]) {
+            seen[current] = true;
+            current = cp[current];
+            length++;
+        }
+        parity ^= (length - 1) & 1;
+    }
+    return parity;
+}
+function gateEligibleWp(wp) {
+    return (0, pairing_coordinate_js_1.hasPairingTransversal)(wp) && (0, pairing_coordinate_js_1.pairingGateParity)(wp) === 0;
+}
+function buildPhase3Start(state, moves) {
+    const pairing = (0, pairing_coordinate_js_1.encodePairingState)(state.wp);
+    const cornerParity = cornerPermutationParity(state.cp);
+    const eXc = (pairing.parity ^ cornerParity);
+    const ct3 = (0, center3_js_1.encodeCenter3)(state, eXc);
+    return {
+        state,
+        ct3: ct3.coordinate,
+        edge: pairing.edge,
+        edgeXorCornerParity: eXc,
+        moves
+    };
+}
+/** Try one aligned phase-2 start with the gated search. */
+function tryPhase2Start(aligned, accumulated, center2Tables, center3Tables, maxLength) {
+    const result = (0, center2_js_1.solveCenter2Gated)(aligned.encoded.ct, aligned.encoded.rl, aligned.state.wp, center2Tables, gateEligibleWp, maxLength);
+    if (result === null || result.wp === undefined)
+        return null;
+    const endState = (0, moves_js_1.applyCube4Algorithm)(aligned.state, result.moves);
+    return buildPhase3Start(endState, [...accumulated, ...result.moves]);
+}
+/**
+ * Build the phase-3 start from the ORIGINAL scramble state. Solves phase 1
+ * (with alternatives), aligns, and runs the gated phase-2 search.
+ * Returns null if the enumeration budget is exhausted.
+ */
+function bridgePhase2To3(randomState, center1Tables, center2Tables, center3Tables, urf = 0, phase1Cap = 50, maxLength = 30) {
+    const phase1Solutions = (0, center1_js_1.solveCenter1All)(randomState.centers, urf, center1Tables, phase1Cap);
+    const alignments = [
+        [],
+        ["Fw", "Bw'"],
+        ["Uw", "Dw'"]
+    ];
+    for (const solution of phase1Solutions) {
+        const output = (0, moves_js_1.applyCube4Algorithm)(randomState, solution.moves);
+        for (const alignment of alignments) {
+            const alignedState = (0, moves_js_1.applyCube4Algorithm)(output, alignment);
+            const aligned = (0, center2_js_1.center2Bridge)(alignedState);
+            if (aligned === null)
+                continue;
+            const start = tryPhase2Start(aligned, [...solution.moves, ...alignment], center2Tables, center3Tables, maxLength);
+            if (start !== null)
+                return start;
+        }
+    }
+    return null;
+}

package/dist-cjs/puzzles/cube4/reduction/phase4.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Phase 4: reduce the solved-centers + paired-wings 4x4 state to a 3x3
+ * cubie state and solve it with the existing cube3 two-phase solver.
+ *
+ * The corner permutation/orientation carry over directly (same numbering as
+ * the cube3). The 12 paired edges: each slot holds one 3x3 edge; the edge
+ * permutation = the pair id and the orientation = the chirality flip (which
+ * wing of the pair sits at the slot's first-half position).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCube4Reduction = checkCube4Reduction;
+exports.toCube3State = toCube3State;
+exports.solveReduced4x4 = solveReduced4x4;
+const moves_js_1 = require("../moves.js");
+const pairing_coordinate_js_1 = require("./pairing-coordinate.js");
+// The "right-chiral" wing/position classes (same set as facelets.ts).
+const RIGHT_GROUP = new Set([1, 2, 4, 6, 8, 11, 13, 15, 16, 19, 20, 23]);
+// For each 3x3 edge position p (positions 2p, 2p+1), the pairing slot whose
+// first-half position belongs to that pair.
+const SLOT_OF_EDGE = (() => {
+    const table = new Array(12);
+    for (let slot = 0; slot < 12; slot++) {
+        const pair = pairing_coordinate_js_1.PAIRING_SLOTS[slot][0] >> 1;
+        table[pair] = slot;
+    }
+    return table;
+})();
+/** Verify the reduction preconditions (the reference's `to333Facelet` check). */
+function checkCube4Reduction(state) {
+    for (let face = 0; face < 6; face++) {
+        const color = state.centers[face * 4];
+        for (let i = 1; i < 4; i++) {
+            if (state.centers[face * 4 + i] !== color) {
+                return { wingsPaired: false, centersSolved: false };
+            }
+        }
+    }
+    for (const [f, s] of pairing_coordinate_js_1.PAIRING_SLOTS) {
+        if ((state.wp[f] >> 1) !== (state.wp[s] >> 1)) {
+            return { wingsPaired: false, centersSolved: true };
+        }
+    }
+    return null;
+}
+/**
+ * Build the 3x3 cubie state from a reduced 4x4 state. Returns null if the
+ * reduction preconditions are not met.
+ */
+function toCube3State(state) {
+    if (checkCube4Reduction(state) !== null)
+        return null;
+    const edges = { permutation: new Array(12), orientation: new Array(12) };
+    for (let edge = 0; edge < 12; edge++) {
+        // the 3x3 edge positions are the position pairs (2p, 2p+1); the slot of
+        // the edge p is the slot whose first-half position belongs to that pair.
+        const slot = SLOT_OF_EDGE[edge];
+        const first = pairing_coordinate_js_1.PAIRING_SLOTS[slot][0];
+        const wing = state.wp[first];
+        edges.permutation[edge] = wing >> 1;
+        // the chirality flip: the derived edge is flipped when the wing and the
+        // slot-half have opposite chirality (the facelets.ts RIGHT_GROUP rule)
+        edges.orientation[edge] = RIGHT_GROUP.has(wing) !== RIGHT_GROUP.has(first) ? 1 : 0;
+    }
+    return {
+        corners: {
+            permutation: Array.from(state.cp),
+            orientation: Array.from(state.co)
+        },
+        edges
+    };
+}
+/**
+ * Full solve: run the reduction phases (1-3) + the 3x3 finish. The caller
+ * provides the phase-3 solution; this applies it and finishes with the cube3
+ * solver, returning the complete move sequence.
+ */
+async function solveReduced4x4(phase3End, phase3Moves, solveCube3) {
+    const state = (0, moves_js_1.applyCube4Algorithm)(phase3End, phase3Moves);
+    const reductionError = checkCube4Reduction(state);
+    if (reductionError !== null) {
+        throw new Error(`4x4 reduction failed: wingsPaired=${reductionError.wingsPaired} centersSolved=${reductionError.centersSolved}`);
+    }
+    const cube3State = toCube3State(state);
+    const solution = await solveCube3(cube3State);
+    return { moves: [...phase3Moves, ...solution.moves] };
+}