@cubingcenter/scrambler 0.5.3 → 0.6.0

package/dist-cjs/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-cjs/puzzles/cube4/reduction/geometry.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PHASE_3_MOVES = exports.PHASE_2_MOVES = exports.PHASE_1_MOVES = void 0;
+exports.buildReductionGeometry = buildReductionGeometry;
+exports.permutationParity = permutationParity;
+exports.verifyReductionGeometry = verifyReductionGeometry;
+const types_js_1 = require("../types.js");
+const moves_js_1 = require("../moves.js");
+// ---------------------------------------------------------------------------
+// Phase move sets
+// ---------------------------------------------------------------------------
+exports.PHASE_1_MOVES = types_js_1.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).
+exports.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).
+exports.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;
+}
+function buildReductionGeometry() {
+    return {
+        rotations: ROTATIONS,
+        centerRotations: ROTATIONS.map((m) => buildPermutation(m, centerCoord, centerIndexAtCoord)),
+        wingRotations: ROTATIONS.map((m) => buildWingRotation(m)),
+        moveCornerParity: types_js_1.CUBE4_ALL_MOVES.map((move) => permutationParityOf(moves_js_1.FACE_MOVE_EFFECTS[(0, moves_js_1.parseMove)(move).face].cperm)),
+        moveWingParity: types_js_1.CUBE4_ALL_MOVES.map((move) => permutationParityOf(moves_js_1.FACE_MOVE_EFFECTS[(0, moves_js_1.parseMove)(move).face].wperm)),
+        phase1Moves: exports.PHASE_1_MOVES,
+        phase2Moves: exports.PHASE_2_MOVES,
+        phase3Moves: exports.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;
+}
+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
+// ---------------------------------------------------------------------------
+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 exports.PHASE_2_MOVES) {
+        const map = positionMapOf(moves_js_1.FACE_MOVE_EFFECTS[(0, moves_js_1.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 exports.PHASE_3_MOVES) {
+        const { face, turns } = (0, moves_js_1.parseMove)(move);
+        const effect = moves_js_1.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 exports.PHASE_2_MOVES) {
+        const { face, turns } = (0, moves_js_1.parseMove)(move);
+        const effect = moves_js_1.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-cjs/puzzles/cube4/reduction/node-loader.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Node loader for the cube4 reduction tables (the committed .bin files).
+ * The manifests are per-phase (`center1-manifest.json`, ...).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCube4ReductionTables = loadCube4ReductionTables;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const edge3_js_1 = require("./edge3.js");
+const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
+function resolveGeneratedAssetDirectory() {
+    const envDirectory = process.env.CUBINGCENTER_SCRAMBLER_TABLES_DIR;
+    if (envDirectory && (0, node_fs_1.existsSync)(node_path_1.default.join(envDirectory, "center1-manifest.json"))) {
+        return envDirectory;
+    }
+    for (const candidate of getAssetDirectoryCandidates()) {
+        if ((0, node_fs_1.existsSync)(node_path_1.default.join(candidate, "center1-manifest.json"))) {
+            return candidate;
+        }
+    }
+    return node_path_1.default.join(process.cwd(), "src", GENERATED_DIRECTORY);
+}
+function getAssetDirectoryCandidates() {
+    const cwd = process.cwd();
+    const candidates = [
+        node_path_1.default.join(cwd, "src", GENERATED_DIRECTORY),
+        node_path_1.default.join(cwd, "dist", GENERATED_DIRECTORY),
+        node_path_1.default.join(cwd, "dist-cjs", GENERATED_DIRECTORY)
+    ];
+    try {
+        const requireFromCwd = (0, node_module_1.createRequire)(node_path_1.default.join(cwd, "package.json"));
+        const packageEntry = requireFromCwd.resolve("@cubingcenter/scrambler");
+        candidates.push(node_path_1.default.join(node_path_1.default.dirname(packageEntry), GENERATED_DIRECTORY));
+    }
+    catch {
+        // Source-tree usage is covered by the cwd candidates.
+    }
+    return candidates;
+}
+function sha256(buffer) {
+    return (0, node_crypto_1.createHash)("sha256").update(buffer).digest("hex");
+}
+function readChecked(file, expectedChecksum) {
+    const buffer = (0, node_fs_1.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((0, node_fs_1.readFileSync)(node_path_1.default.join(assetDirectory, "center1-manifest.json"), "utf8"));
+    return {
+        distance: new Uint8Array(readChecked(node_path_1.default.join(assetDirectory, manifest.distanceTable.file), manifest.distanceTable.checksum)),
+        moveMaps: readInt32(readChecked(node_path_1.default.join(assetDirectory, manifest.moveMaps.file), manifest.moveMaps.checksum))
+    };
+}
+function loadCenter2(assetDirectory) {
+    const manifest = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(assetDirectory, "center2-manifest.json"), "utf8"));
+    const pruningBuffer = readChecked(node_path_1.default.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(node_path_1.default.join(assetDirectory, manifest.ctMove.file), manifest.ctMove.checksum)),
+        rlMove: readInt32(readChecked(node_path_1.default.join(assetDirectory, manifest.rlMove.file), manifest.rlMove.checksum)),
+        pruning
+    };
+}
+function loadCenter3(assetDirectory) {
+    const manifest = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(assetDirectory, "center3-manifest.json"), "utf8"));
+    return {
+        moveTable: readInt32(readChecked(node_path_1.default.join(assetDirectory, manifest.moveTable.file), manifest.moveTable.checksum)),
+        pruning: new Uint8Array(readChecked(node_path_1.default.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum))
+    };
+}
+function loadEdge3(assetDirectory) {
+    const manifest = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(assetDirectory, "edge3-manifest.json"), "utf8"));
+    const distances = new Uint8Array(readChecked(node_path_1.default.join(assetDirectory, manifest.distances.file), manifest.distances.checksum));
+    return { distances, distanceOfEdge: (0, edge3_js_1.edge3DistanceLookup)(distances) };
+}
+/** Load all cube4 reduction tables (throws if the generated assets are missing). */
+function loadCube4ReductionTables() {
+    const assetDirectory = resolveGeneratedAssetDirectory();
+    if (!(0, node_fs_1.existsSync)(node_path_1.default.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)
+    };
+}