@cubingcenter/scrambler 0.5.3 → 0.6.0

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

@@ -0,0 +1,281 @@
+/**
+ * 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.
+ */
+import { CUBE4_ALL_MOVES } from "../types.js";
+import { FACE_MOVE_EFFECTS, parseMove } from "../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.
+ */
+export const 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).
+ */
+export const 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.
+ */
+export const 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. */
+export const PAIRING_FIRST_HALVES = PAIRING_SLOTS.map(([f]) => f);
+/** Second-half position of each slot. */
+export const PAIRING_SECOND_HALVES = 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.
+ */
+export 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).
+ */
+export function applyPairingMoveToArray(arr24, move) {
+    const { face, turns } = parseMove(move);
+    const effect = 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).
+ */
+export function hasPairingTransversal(wp) {
+    const seen = new Uint8Array(12);
+    for (const s of 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.
+ */
+export 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).
+ */
+export 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[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[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.
+ */
+export function decodePairingState(edge, edgeo) {
+    const wp = new Uint8Array(24);
+    for (let i = 0; i < 12; i++) {
+        wp[PAIRING_FIRST_HALVES[i]] = 2 * edge[i];
+        wp[PAIRING_SECOND_HALVES[i]] = 2 * edgeo[i] + 1;
+    }
+    return wp;
+}
+/**
+ * True iff the pairing permutation is fully reduced (all 12 slots paired).
+ */
+export 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).
+ */
+export 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[PAIRING_FIRST_HALVES[i]];
+        eo[i] = arr24[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).
+ */
+export 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
+// ---------------------------------------------------------------------------
+export function verifyPairingCoordinate() {
+    const errors = [];
+    for (const move of PAIRING_MOVES) {
+        if (!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 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 PAIRING_MOVES) {
+        const { face, turns } = parseMove(move);
+        const parity = wingPermutationParity(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/puzzles/cube4/reduction/phase3-search.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+import type { Cube4Move } from "../types.js";
+import { type Center3Tables } from "./center3.js";
+import { type Edge3Tables } from "./edge3.js";
+import type { Phase3Start } from "./phase3.js";
+/** The 17 exploration moves (the reference's m < 17 bound). */
+export declare const SEARCH_MOVES: readonly Cube4Move[];
+export declare const ckmv3: boolean[][];
+export declare const skipAxis3: number[];
+export interface Phase3Result {
+    moves: Cube4Move[];
+    ct3: number;
+    edge: Uint8Array;
+}
+/**
+ * Fast table-driven Phase 3 IDA* solver class.
+ */
+export declare class FastPhase3Solver {
+    private readonly tempep;
+    private readonly moveLog;
+    private readonly sym;
+    constructor();
+    private getPrun;
+    /**
+     * Recursive IDA* worker on table transitions.
+     */
+    search(eplast: Uint8Array, ct: number, prun: number, maxl: number, lm: number, depth: number, center3Tables: Center3Tables, edge3Distances: Uint8Array): Promise<boolean>;
+    /**
+     * Search for a phase-3 solution with exact target length.
+     */
+    solveLength(edge: Uint8Array, ct3: number, edist: number, length3: number, center3Tables: Center3Tables, edge3Distances: Uint8Array): Promise<Cube4Move[] | null>;
+}
+/**
+ * Solve Phase 3 with iterative deepening on a single Phase3Start.
+ */
+export declare function solvePhase3(start: Phase3Start, center3Tables: Center3Tables, edge3Tables: Edge3Tables, maxLength?: number): Promise<Phase3Result | null>;
+//# sourceMappingURL=phase3-search.d.ts.map

package/dist/puzzles/cube4/reduction/phase3-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase3-search.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/phase3-search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAIL,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,+DAA+D;AAC/D,eAAO,MAAM,YAAY,EAAE,SAAS,SAAS,EAA+B,CAAC;AAa7E,eAAO,MAAM,KAAK,EAAE,OAAO,EAAE,EAAgE,CAAC;AAO9F,eAAO,MAAM,SAAS,EAAE,MAAM,EAA2B,CAAC;AAU1D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;;IAQhC,OAAO,CAAC,OAAO;IAKf;;OAEG;IACU,MAAM,CACjB,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,OAAO,CAAC;IA8DnB;;OAEG;IACU,WAAW,CACtB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC;CAkB/B;AAID;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,WAAW,EACxB,SAAS,SAAK,GACb,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAmC9B"}

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

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ */
+import { CENTER3_MOVES } from "./center3.js";
+import { getSymTables, getMvSymFrom, MOVE3_STD } from "./edge3.js";
+/** The 17 exploration moves (the reference's m < 17 bound). */
+export const SEARCH_MOVES = 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;
+}
+export const ckmv3 = Array.from({ length: 21 }, () => new Array(20).fill(false));
+for (let i = 0; i < 21; i++) {
+    for (let j = 0; j < 20; j++) {
+        ckmv3[i][j] = ckmv[MOVE3_STD[i]][MOVE3_STD[j]];
+    }
+}
+export const skipAxis3 = new Array(20).fill(20);
+for (let i = 0; i < 20; i++) {
+    for (let j = i; j < 20; j++) {
+        if (!ckmv3[i][j]) {
+            skipAxis3[i] = j - 1;
+            break;
+        }
+    }
+}
+/**
+ * Fast table-driven Phase 3 IDA* solver class.
+ */
+export class FastPhase3Solver {
+    tempep;
+    moveLog;
+    sym;
+    constructor() {
+        this.tempep = Array.from({ length: 30 }, () => new Uint8Array(12));
+        this.moveLog = new Array(30);
+        this.sym = 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 (ckmv3[lm][m]) {
+                m = skipAxis3[m];
+                continue;
+            }
+            const nc = center3Tables.moveTable[ct * CENTER3_MOVES.length + m];
+            if (nc < 0)
+                continue;
+            const prun1 = center3Tables.pruning[nc];
+            if (prun1 >= maxl) {
+                if (prun1 > maxl && m < 14)
+                    m = skipAxis3[m];
+                continue;
+            }
+            const symIdx = 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 = 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) => SEARCH_MOVES[m]);
+        }
+        return null;
+    }
+}
+const defaultSolver = new FastPhase3Solver();
+/**
+ * Solve Phase 3 with iterative deepening on a single Phase3Start.
+ */
+export async function solvePhase3(start, center3Tables, edge3Tables, maxLength = 20) {
+    const sym = getSymTables();
+    const symIdx = 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/puzzles/cube4/reduction/phase3.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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).
+ */
+import type { Cube4State, Cube4Move } from "../types.js";
+import { type Center1Tables } from "./center1.js";
+import { type Center2Tables } from "./center2.js";
+import { type Center3Tables } from "./center3.js";
+export interface Phase3Start {
+    /** The gated phase-2 end state (its wings are transversal-eligible). */
+    state: Cube4State;
+    /** Center3 coordinate (parity bit included). */
+    ct3: number;
+    /** Pairing permutation (normalized, edgeo = identity). */
+    edge: Uint8Array;
+    /** The $set_6 pairing parity XOR corner parity. */
+    edgeXorCornerParity: 0 | 1;
+    /** The accumulated phase-1 + alignment + phase-2 moves. */
+    moves: Cube4Move[];
+}
+/**
+ * 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.
+ */
+export declare function bridgePhase2To3(randomState: Cube4State, center1Tables: Center1Tables, center2Tables: Center2Tables, center3Tables: Center3Tables, urf?: 0 | 1 | 2, phase1Cap?: number, maxLength?: number): Phase3Start | null;
+//# sourceMappingURL=phase3.d.ts.map

package/dist/puzzles/cube4/reduction/phase3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase3.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/phase3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAGjE,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC;IAClB,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,mDAAmD;IACnD,mBAAmB,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3B,2DAA2D;IAC3D,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AA0DD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,UAAU,EACvB,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,aAAa,EAC5B,GAAG,GAAE,CAAC,GAAG,CAAC,GAAG,CAAK,EAClB,SAAS,SAAK,EACd,SAAS,SAAK,GACb,WAAW,GAAG,IAAI,CAoBpB"}

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

@@ -0,0 +1,83 @@
+/**
+ * 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).
+ */
+import { applyCube4Algorithm } from "../moves.js";
+import { solveCenter1All } from "./center1.js";
+import { center2Bridge, solveCenter2Gated } from "./center2.js";
+import { encodeCenter3 } from "./center3.js";
+import { encodePairingState, hasPairingTransversal, pairingGateParity } from "./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 hasPairingTransversal(wp) && pairingGateParity(wp) === 0;
+}
+function buildPhase3Start(state, moves) {
+    const pairing = encodePairingState(state.wp);
+    const cornerParity = cornerPermutationParity(state.cp);
+    const eXc = (pairing.parity ^ cornerParity);
+    const ct3 = 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 = solveCenter2Gated(aligned.encoded.ct, aligned.encoded.rl, aligned.state.wp, center2Tables, gateEligibleWp, maxLength);
+    if (result === null || result.wp === undefined)
+        return null;
+    const endState = 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.
+ */
+export function bridgePhase2To3(randomState, center1Tables, center2Tables, center3Tables, urf = 0, phase1Cap = 50, maxLength = 30) {
+    const phase1Solutions = solveCenter1All(randomState.centers, urf, center1Tables, phase1Cap);
+    const alignments = [
+        [],
+        ["Fw", "Bw'"],
+        ["Uw", "Dw'"]
+    ];
+    for (const solution of phase1Solutions) {
+        const output = applyCube4Algorithm(randomState, solution.moves);
+        for (const alignment of alignments) {
+            const alignedState = applyCube4Algorithm(output, alignment);
+            const aligned = 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/puzzles/cube4/reduction/phase4.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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).
+ */
+import type { Cube4State, Cube4Move } from "../types.js";
+import type { Cube3State, Cube3Move } from "../../cube3/types.js";
+export interface Cube4ReductionError {
+    /** All 12 slots paired? */
+    wingsPaired: boolean;
+    /** All 6 faces uniform? */
+    centersSolved: boolean;
+}
+/** Verify the reduction preconditions (the reference's `to333Facelet` check). */
+export declare function checkCube4Reduction(state: Cube4State): Cube4ReductionError | null;
+/**
+ * Build the 3x3 cubie state from a reduced 4x4 state. Returns null if the
+ * reduction preconditions are not met.
+ */
+export declare function toCube3State(state: Cube4State): Cube3State | null;
+/**
+ * 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.
+ */
+export declare function solveReduced4x4(phase3End: Cube4State, phase3Moves: readonly Cube4Move[], solveCube3: (state: Cube3State) => Promise<{
+    moves: Cube3Move[];
+}>): Promise<{
+    moves: Cube4Move[];
+}>;
+//# sourceMappingURL=phase4.d.ts.map

package/dist/puzzles/cube4/reduction/phase4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase4.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/phase4.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAkBlE,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,GAAG,IAAI,CAejF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAuBjE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,SAAS,SAAS,EAAE,EACjC,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,GACjE,OAAO,CAAC;IAAE,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC,CAWjC"}