@cubingcenter/scrambler 0.5.3 → 0.6.0

package/dist/puzzles/cube4/reduction/generated/edge3-manifest.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "puzzle": "cube4",
+  "phase": "edge3",
+  "classCount": 31006080,
+  "maxDepth": 13,
+  "distances": {
+    "file": "edge3-distances.bin",
+    "range": 15503040,
+    "checksum": "b441c57a052dc5650958426c7fddbdf5cab195f615449bc2235364f2ceb6c939"
+  }
+}

package/dist/puzzles/cube4/reduction/geometry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reduction geometry for the 4x4 solver.
+ *
+ * Provides:
+ *  - the 24-rotation symmetry group as permutations on the 24 center
+ *    positions and the 24 wing positions (built from a 3D sticker model),
+ *  - the phase move sets (F1: all moves, F2: UD-preserving, F3: pairing),
+ *  - per-move corner/wing permutation parities,
+ *  - the wing orbit structure preserved by the phase-3 move set,
+ *  - verification gates (group order, move-set invariants, orbit structure).
+ *
+ * Everything here is verified programmatically by the gates so a hand error
+ * in any table fails loudly instead of silently corrupting solutions.
+ */
+import type { Cube4Move } from "../types.js";
+export declare const PHASE_1_MOVES: readonly Cube4Move[];
+export declare const PHASE_2_MOVES: readonly Cube4Move[];
+export declare const PHASE_3_MOVES: readonly Cube4Move[];
+export interface ReductionGeometry {
+    /** 24 rotation matrices (3×3) of the cube symmetry group. */
+    rotations: readonly (readonly (readonly number[])[])[];
+    centerRotations: readonly (readonly number[])[];
+    wingRotations: readonly (readonly number[])[];
+    moveCornerParity: readonly number[];
+    moveWingParity: readonly number[];
+    phase1Moves: readonly Cube4Move[];
+    phase2Moves: readonly Cube4Move[];
+    phase3Moves: readonly Cube4Move[];
+}
+export declare function buildReductionGeometry(): ReductionGeometry;
+export declare function permutationParity(values: readonly number[]): 0 | 1;
+export declare function verifyReductionGeometry(): string[];
+//# sourceMappingURL=geometry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/geometry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQ7C,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAAoB,CAAC;AAInE,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAI7C,CAAC;AAKF,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAI7C,CAAC;AAiIF,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,SAAS,EAAE,SAAS,CAAC,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IACvD,eAAe,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAChD,aAAa,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAC9C,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC;IAClC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC;IAClC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC;CACnC;AAED,wBAAgB,sBAAsB,IAAI,iBAAiB,CAW1D;AAmGD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAUlE;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CA6DlD"}

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

@@ -0,0 +1,302 @@
+/**
+ * Reduction geometry for the 4x4 solver.
+ *
+ * Provides:
+ *  - the 24-rotation symmetry group as permutations on the 24 center
+ *    positions and the 24 wing positions (built from a 3D sticker model),
+ *  - the phase move sets (F1: all moves, F2: UD-preserving, F3: pairing),
+ *  - per-move corner/wing permutation parities,
+ *  - the wing orbit structure preserved by the phase-3 move set,
+ *  - verification gates (group order, move-set invariants, orbit structure).
+ *
+ * Everything here is verified programmatically by the gates so a hand error
+ * in any table fails loudly instead of silently corrupting solutions.
+ */
+import { CUBE4_ALL_MOVES } from "../types.js";
+import { FACE_MOVE_EFFECTS, parseMove } from "../moves.js";
+// ---------------------------------------------------------------------------
+// Phase move sets
+// ---------------------------------------------------------------------------
+export const PHASE_1_MOVES = CUBE4_ALL_MOVES;
+// Moves that keep U/D-colored centers on U/D faces: all face turns plus
+// Uw/Dw (the u/d slices cycle centers among the R/F/L/B faces only).
+export const PHASE_2_MOVES = [
+    "U", "U2", "U'", "R", "R2", "R'", "F", "F2", "F'",
+    "D", "D2", "D'", "L", "L2", "L'", "B", "B2", "B'",
+    "Uw", "Uw2", "Uw'", "Dw", "Dw2", "Dw'"
+];
+// Wing-pairing moves (cstimer-style): all face turns plus quarter wide
+// turns. The wide turns move centers mid-search (guided back by the center
+// coordinate) and flip wing permutation parity (tracked as the phase-2 bit).
+export const PHASE_3_MOVES = [
+    "U", "U2", "U'", "R", "F", "F2", "F'",
+    "D", "D2", "D'", "L", "B", "B2", "B'",
+    "Uw", "Rw", "Fw", "Dw", "Lw", "Bw"
+];
+const FACE_BASES = [
+    { n: [0, 0, 1], u: [1, 0, 0], v: [0, 1, 0] }, // U
+    { n: [1, 0, 0], u: [0, -1, 0], v: [0, 0, 1] }, // R
+    { n: [0, 1, 0], u: [1, 0, 0], v: [0, 0, 1] }, // F
+    { n: [0, 0, -1], u: [1, 0, 0], v: [0, 1, 0] }, // D
+    { n: [-1, 0, 0], u: [0, 1, 0], v: [0, 0, 1] }, // L
+    { n: [0, -1, 0], u: [-1, 0, 0], v: [0, 0, 1] } // B
+];
+function stickerCoord(face, row, col) {
+    const { n, u, v } = FACE_BASES[face];
+    return [
+        n[0] * 4 + (col - 1.5) * 2 * u[0] + (1.5 - row) * 2 * v[0],
+        n[1] * 4 + (col - 1.5) * 2 * u[1] + (1.5 - row) * 2 * v[1],
+        n[2] * 4 + (col - 1.5) * 2 * u[2] + (1.5 - row) * 2 * v[2]
+    ];
+}
+function faceAtCoord(c) {
+    let best = 0;
+    let bestDot = -Infinity;
+    for (let face = 0; face < 6; face += 1) {
+        const { n } = FACE_BASES[face];
+        const dot = c[0] * n[0] + c[1] * n[1] + c[2] * n[2];
+        if (dot > bestDot) {
+            bestDot = dot;
+            best = face;
+        }
+    }
+    return best;
+}
+function rowColAtCoord(face, c) {
+    const { u, v } = FACE_BASES[face];
+    const uu = c[0] * u[0] + c[1] * u[1] + c[2] * u[2];
+    const vv = c[0] * v[0] + c[1] * v[1] + c[2] * v[2];
+    const col = Math.round(uu / 2 + 1.5);
+    const row = Math.round(1.5 - vv / 2);
+    return [row, col];
+}
+// Rotation generators (as 3x3 integer matrices):
+//  Rz90: 90° about the UD axis  (x,y,z) → (-y,x,z)
+//  Rdiag: 120° about (1,1,1)    (x,y,z) → (z,x,y)
+const RZ90 = [
+    [0, -1, 0],
+    [1, 0, 0],
+    [0, 0, 1]
+];
+const RDIAG = [
+    [0, 0, 1],
+    [1, 0, 0],
+    [0, 1, 0]
+];
+function applyMatrix(m, v) {
+    return [
+        m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2],
+        m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2],
+        m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2]
+    ];
+}
+function composeMatrix(a, b) {
+    return b.map((col) => applyMatrix(a, col));
+}
+function matrixKey(m) {
+    return m.map((col) => col.join(",")).join(";");
+}
+function buildRotationGroup() {
+    const seen = new Map();
+    const group = [];
+    const queue = [RZ90, RDIAG];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        const key = matrixKey(current);
+        if (seen.has(key))
+            continue;
+        seen.set(key, current);
+        group.push(current);
+        for (const generator of [RZ90, RDIAG]) {
+            const composed = composeMatrix(current, generator);
+            if (!seen.has(matrixKey(composed))) {
+                queue.push(composed);
+            }
+        }
+    }
+    return group;
+}
+const ROTATIONS = buildRotationGroup();
+// ---------------------------------------------------------------------------
+// Position mappings under a rotation
+// ---------------------------------------------------------------------------
+function centerCoord(index) {
+    const face = Math.floor(index / 4);
+    const slot = index % 4;
+    // slot → (row, col) for the inner 2×2 at face positions 5,6,9,10
+    const rowCol = [
+        [1, 1], [1, 2], [2, 1], [2, 2]
+    ];
+    const [row, col] = rowCol[slot];
+    return stickerCoord(face, row, col);
+}
+function centerIndexAtCoord(c) {
+    const face = faceAtCoord(c);
+    const [row, col] = rowColAtCoord(face, c);
+    const slot = row === 1 && col === 1 ? 0 : row === 1 && col === 2 ? 1 : row === 2 && col === 1 ? 2 : 3;
+    return face * 4 + slot;
+}
+export function buildReductionGeometry() {
+    return {
+        rotations: ROTATIONS,
+        centerRotations: ROTATIONS.map((m) => buildPermutation(m, centerCoord, centerIndexAtCoord)),
+        wingRotations: ROTATIONS.map((m) => buildWingRotation(m)),
+        moveCornerParity: CUBE4_ALL_MOVES.map((move) => permutationParityOf(FACE_MOVE_EFFECTS[parseMove(move).face].cperm)),
+        moveWingParity: CUBE4_ALL_MOVES.map((move) => permutationParityOf(FACE_MOVE_EFFECTS[parseMove(move).face].wperm)),
+        phase1Moves: PHASE_1_MOVES,
+        phase2Moves: PHASE_2_MOVES,
+        phase3Moves: PHASE_3_MOVES
+    };
+}
+function buildPermutation(matrix, positionCoord, positionAtCoord) {
+    const perm = new Array(24);
+    for (let index = 0; index < 24; index += 1) {
+        perm[positionAtCoord(applyMatrix(matrix, positionCoord(index)))] = index;
+    }
+    return perm;
+}
+function buildWingRotation(matrix) {
+    const stickers = wingStickers();
+    const perm = new Array(24);
+    for (let index = 0; index < 24; index += 1) {
+        const [s1, s2] = stickers[index];
+        const r1 = applyMatrix(matrix, s1);
+        const r2 = applyMatrix(matrix, s2);
+        perm[wingIndexAtSticker(r1)] = index;
+    }
+    return perm;
+}
+// Wing position → its two stickers as (face, sticker 0-15), from facelets.ts.
+const WING_STICKER_POSITIONS = [
+    [0, 11], [1, 1], [0, 7], [1, 2], [0, 14], [2, 2], [0, 13], [2, 1],
+    [0, 8], [4, 2], [0, 4], [4, 1], [0, 1], [5, 2], [0, 2], [5, 1],
+    [3, 7], [1, 13], [3, 11], [1, 14], [3, 2], [2, 14], [3, 1], [2, 13],
+    [3, 4], [4, 14], [3, 8], [4, 13], [3, 13], [5, 14], [3, 14], [5, 13],
+    [2, 7], [1, 4], [2, 11], [1, 8], [2, 4], [4, 7], [2, 8], [4, 11],
+    [5, 7], [4, 4], [5, 11], [4, 8], [5, 4], [1, 7], [5, 8], [1, 11]
+];
+const WING_INDEX_BY_STICKER = (() => {
+    const map = new Map();
+    for (let position = 0; position < 24; position += 1) {
+        for (let k = 0; k < 2; k += 1) {
+            const [face, sticker] = WING_STICKER_POSITIONS[position * 2 + k];
+            map.set(`${face},${Math.floor(sticker / 4)},${sticker % 4}`, position);
+        }
+    }
+    return map;
+})();
+function wingStickers() {
+    const stickers = WING_STICKER_POSITIONS.map(([face, sticker]) => stickerCoord(face, Math.floor(sticker / 4), sticker % 4));
+    const result = [];
+    for (let position = 0; position < 24; position += 1) {
+        result.push([stickers[position * 2], stickers[position * 2 + 1]]);
+    }
+    return result;
+}
+function wingIndexAtSticker(c) {
+    const face = faceAtCoord(c);
+    const [row, col] = rowColAtCoord(face, c);
+    const index = WING_INDEX_BY_STICKER.get(`${face},${row},${col}`);
+    if (index === undefined) {
+        throw new Error(`Not a wing sticker position: face=${face} row=${row} col=${col}`);
+    }
+    return index;
+}
+// ---------------------------------------------------------------------------
+// Move helpers
+// ---------------------------------------------------------------------------
+// Position map of a move effect: piece at position p moves to position
+// inversePerm[p] where newState[i] = oldState[perm[i]].
+function positionMapOf(perm) {
+    const map = new Array(perm.length);
+    for (let destination = 0; destination < perm.length; destination += 1) {
+        map[perm[destination]] = destination;
+    }
+    return map;
+}
+function permutationParityOf(perm) {
+    let parity = 0;
+    const seen = new Array(perm.length).fill(false);
+    for (let start = 0; start < perm.length; start += 1) {
+        if (seen[start] || perm[start] === start)
+            continue;
+        let length = 0;
+        let current = start;
+        while (!seen[current]) {
+            seen[current] = true;
+            current = perm[current];
+            length += 1;
+        }
+        parity ^= (length - 1) & 1;
+    }
+    return parity;
+}
+export function permutationParity(values) {
+    let inversions = 0;
+    for (let left = 0; left < values.length; left += 1) {
+        for (let right = left + 1; right < values.length; right += 1) {
+            if (values[left] > values[right]) {
+                inversions += 1;
+            }
+        }
+    }
+    return (inversions % 2);
+}
+// ---------------------------------------------------------------------------
+// Verification gates
+// ---------------------------------------------------------------------------
+export function verifyReductionGeometry() {
+    const errors = [];
+    if (ROTATIONS.length !== 24) {
+        errors.push(`Rotation group has ${ROTATIONS.length} elements, expected 24.`);
+    }
+    const geometry = buildReductionGeometry();
+    // Rotations must be bijections.
+    for (let r = 0; r < geometry.centerRotations.length; r += 1) {
+        const perm = geometry.centerRotations[r];
+        if (new Set(perm).size !== 24) {
+            errors.push(`Center rotation ${r} is not a bijection.`);
+            break;
+        }
+        const wperm = geometry.wingRotations[r];
+        if (new Set(wperm).size !== 24) {
+            errors.push(`Wing rotation ${r} is not a bijection.`);
+            break;
+        }
+    }
+    // Phase 2 moves must keep U/D colors on U/D center positions.
+    const udPositions = new Set([0, 1, 2, 3, 12, 13, 14, 15]);
+    for (const move of PHASE_2_MOVES) {
+        const map = positionMapOf(FACE_MOVE_EFFECTS[parseMove(move).face].ctperm);
+        for (const position of udPositions) {
+            if (!udPositions.has(map[position])) {
+                errors.push(`Phase 2 move ${move} moves a U/D center position out of U/D faces.`);
+                break;
+            }
+        }
+    }
+    // Wing permutation parity flips exactly on the wide quarter turns (the
+    // bit the phase-2 search absorbs). Parity of the n-th power is
+    // base-parity × (turns mod 2).
+    for (const move of PHASE_3_MOVES) {
+        const { face, turns } = parseMove(move);
+        const effect = FACE_MOVE_EFFECTS[face];
+        const wingParity = (permutationParityOf(effect.wperm) * (turns & 1)) & 1;
+        const expectedWing = move.includes("w") && !move.endsWith("2") ? 1 : 0;
+        if (wingParity !== expectedWing) {
+            errors.push(`Phase 3 move ${move} has unexpected wing permutation parity.`);
+        }
+    }
+    // Phase 2 moves keep U/D colors on U/D faces; wing-parity flips only on
+    // the Uw/Dw quarter turns (the tracked bit).
+    for (const move of PHASE_2_MOVES) {
+        const { face, turns } = parseMove(move);
+        const effect = FACE_MOVE_EFFECTS[face];
+        const wingParity = (permutationParityOf(effect.wperm) * (turns & 1)) & 1;
+        const expectedWing = move.includes("w") && !move.endsWith("2") ? 1 : 0;
+        if (wingParity !== expectedWing) {
+            errors.push(`Phase 2 move ${move} has unexpected wing permutation parity.`);
+        }
+    }
+    return errors;
+}

package/dist/puzzles/cube4/reduction/node-loader.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Node loader for the cube4 reduction tables (the committed .bin files).
+ * The manifests are per-phase (`center1-manifest.json`, ...).
+ */
+import type { Center1Tables } from "./center1.js";
+import type { Center2Tables } from "./center2.js";
+import type { Center3Tables } from "./center3.js";
+import type { Edge3Tables } from "./edge3.js";
+export interface Cube4ReductionTables {
+    center1: Center1Tables;
+    center2: Center2Tables;
+    center3: Center3Tables;
+    edge3: Edge3Tables;
+}
+/** Load all cube4 reduction tables (throws if the generated assets are missing). */
+export declare function loadCube4ReductionTables(): Cube4ReductionTables;
+//# sourceMappingURL=node-loader.d.ts.map

package/dist/puzzles/cube4/reduction/node-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-loader.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/node-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;CACpB;AAuGD,oFAAoF;AACpF,wBAAgB,wBAAwB,IAAI,oBAAoB,CAW/D"}

package/dist/puzzles/cube4/reduction/node-loader.js

@@ -0,0 +1,98 @@
+/**
+ * Node loader for the cube4 reduction tables (the committed .bin files).
+ * The manifests are per-phase (`center1-manifest.json`, ...).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { edge3DistanceLookup } from "./edge3.js";
+const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
+function resolveGeneratedAssetDirectory() {
+    const envDirectory = process.env.CUBINGCENTER_SCRAMBLER_TABLES_DIR;
+    if (envDirectory && existsSync(path.join(envDirectory, "center1-manifest.json"))) {
+        return envDirectory;
+    }
+    for (const candidate of getAssetDirectoryCandidates()) {
+        if (existsSync(path.join(candidate, "center1-manifest.json"))) {
+            return candidate;
+        }
+    }
+    return path.join(process.cwd(), "src", GENERATED_DIRECTORY);
+}
+function getAssetDirectoryCandidates() {
+    const cwd = process.cwd();
+    const candidates = [
+        path.join(cwd, "src", GENERATED_DIRECTORY),
+        path.join(cwd, "dist", GENERATED_DIRECTORY),
+        path.join(cwd, "dist-cjs", GENERATED_DIRECTORY)
+    ];
+    try {
+        const requireFromCwd = createRequire(path.join(cwd, "package.json"));
+        const packageEntry = requireFromCwd.resolve("@cubingcenter/scrambler");
+        candidates.push(path.join(path.dirname(packageEntry), GENERATED_DIRECTORY));
+    }
+    catch {
+        // Source-tree usage is covered by the cwd candidates.
+    }
+    return candidates;
+}
+function sha256(buffer) {
+    return createHash("sha256").update(buffer).digest("hex");
+}
+function readChecked(file, expectedChecksum) {
+    const buffer = readFileSync(file);
+    if (sha256(buffer) !== expectedChecksum) {
+        throw new Error(`Table checksum mismatch: ${file}`);
+    }
+    return buffer;
+}
+function readInt32(buffer) {
+    return new Int32Array(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
+}
+function loadCenter1(assetDirectory) {
+    const manifest = JSON.parse(readFileSync(path.join(assetDirectory, "center1-manifest.json"), "utf8"));
+    return {
+        distance: new Uint8Array(readChecked(path.join(assetDirectory, manifest.distanceTable.file), manifest.distanceTable.checksum)),
+        moveMaps: readInt32(readChecked(path.join(assetDirectory, manifest.moveMaps.file), manifest.moveMaps.checksum))
+    };
+}
+function loadCenter2(assetDirectory) {
+    const manifest = JSON.parse(readFileSync(path.join(assetDirectory, "center2-manifest.json"), "utf8"));
+    const pruningBuffer = readChecked(path.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum);
+    const pruning = new Uint8Array(450450);
+    for (let i = 0; i < 450450; i++) {
+        const byte = pruningBuffer[i >> 1];
+        pruning[i] = (i & 1) === 0 ? byte & 0x0f : byte >> 4;
+    }
+    return {
+        ctMove: readInt32(readChecked(path.join(assetDirectory, manifest.ctMove.file), manifest.ctMove.checksum)),
+        rlMove: readInt32(readChecked(path.join(assetDirectory, manifest.rlMove.file), manifest.rlMove.checksum)),
+        pruning
+    };
+}
+function loadCenter3(assetDirectory) {
+    const manifest = JSON.parse(readFileSync(path.join(assetDirectory, "center3-manifest.json"), "utf8"));
+    return {
+        moveTable: readInt32(readChecked(path.join(assetDirectory, manifest.moveTable.file), manifest.moveTable.checksum)),
+        pruning: new Uint8Array(readChecked(path.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum))
+    };
+}
+function loadEdge3(assetDirectory) {
+    const manifest = JSON.parse(readFileSync(path.join(assetDirectory, "edge3-manifest.json"), "utf8"));
+    const distances = new Uint8Array(readChecked(path.join(assetDirectory, manifest.distances.file), manifest.distances.checksum));
+    return { distances, distanceOfEdge: edge3DistanceLookup(distances) };
+}
+/** Load all cube4 reduction tables (throws if the generated assets are missing). */
+export function loadCube4ReductionTables() {
+    const assetDirectory = resolveGeneratedAssetDirectory();
+    if (!existsSync(path.join(assetDirectory, "center1-manifest.json"))) {
+        throw new Error("Cube4 reduction tables not generated — run pnpm cube4:center1:tables etc.");
+    }
+    return {
+        center1: loadCenter1(assetDirectory),
+        center2: loadCenter2(assetDirectory),
+        center3: loadCenter3(assetDirectory),
+        edge3: loadEdge3(assetDirectory)
+    };
+}

package/dist/puzzles/cube4/reduction/pairing-coordinate.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 type { Cube4Move } from "../types.js";
+/**
+ * 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 declare const PAIRING_MOVES: readonly Cube4Move[];
+/**
+ * The 17-move BFS subset used to build the pruning table (reference
+ * `bfsMoves`): omits Dw2/Lw2/Bw2 (rotation-conjugate to Uw2/Rw2/Fw2).
+ */
+export declare const PAIRING_BFS_MOVES: readonly Cube4Move[];
+/**
+ * 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 declare const PAIRING_SLOTS: readonly (readonly [number, number])[];
+/** First-half position of each slot. */
+export declare const PAIRING_FIRST_HALVES: readonly number[];
+/** Second-half position of each slot. */
+export declare const PAIRING_SECOND_HALVES: readonly number[];
+/**
+ * Map the 24 labeled wings to their pair ids: `arr24[i] = wp[i] >> 1`.
+ * Each pair id 0-11 appears exactly twice.
+ */
+export declare function pairIdArray(wp: Uint8Array): Uint8Array;
+/**
+ * Apply a move to a 24-entry pair-id array (position permutation from the
+ * verified move tables).
+ */
+export declare function applyPairingMoveToArray(arr24: Uint8Array, move: Cube4Move): Uint8Array;
+/**
+ * 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 declare function hasPairingTransversal(wp: Uint8Array): boolean;
+/**
+ * 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 declare function pairingGateParity(wp: Uint8Array): 0 | 1;
+export interface PairingEncodeResult {
+    /** 12-permutation, `identity` iff all 12 slots are paired. */
+    edge: Uint8Array;
+    /**
+     * Parity bit returned by the encode (the reference XORs this into the
+     * phase-3 center coordinate: `parity ^ cornerParity`, and its evolution
+     * under the phase-3 moves — the wide doubles flip it — is tracked by that
+     * coordinate's `pmove` bits, NOT here). Validated determinism only; the
+     * evolution semantics are verified with the Center3 integration.
+     */
+    parity: 0 | 1;
+}
+/**
+ * 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 declare function encodePairingState(wp: Uint8Array): PairingEncodeResult | null;
+/**
+ * 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 declare function decodePairingState(edge: Uint8Array, edgeo: Uint8Array): Uint8Array;
+/**
+ * True iff the pairing permutation is fully reduced (all 12 slots paired).
+ */
+export declare function isPairingReduced(edge: Uint8Array): boolean;
+/**
+ * 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 declare function applyPairingMoveToState(edge: Uint8Array, edgeo: Uint8Array, move: Cube4Move): {
+    edge: Uint8Array;
+    edgeo: Uint8Array;
+};
+/**
+ * $std-normalize a pairing state: reindex so the second halves hold pairs
+ * 0..11 in order (the `edgeo` array becomes the identity).
+ */
+export declare function normalizePairingState(edge: Uint8Array, edgeo: Uint8Array): {
+    edge: Uint8Array;
+    edgeo: Uint8Array;
+};
+export declare function verifyPairingCoordinate(): string[];
+//# sourceMappingURL=pairing-coordinate.d.ts.map

package/dist/puzzles/cube4/reduction/pairing-coordinate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing-coordinate.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/pairing-coordinate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAQ7C;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAGpC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,SAAS,EAGxC,CAAC;AAMX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAG/D,CAAC;AAEF,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAkC,CAAC;AAErF,yCAAyC;AACzC,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAMxF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,UAAU,GAAG,UAAU,CAItD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,CAUtF;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CAQ7D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,UAAU,GAAG,CAAC,GAAG,CAAC,CAevD;AAMD,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,UAAU,GAAG,mBAAmB,GAAG,IAAI,CA2B7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAOlF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAK1D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,SAAS,GACd;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAUzC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,UAAU,GAChB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAUzC;AAMD,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CA+BlD"}