@cubingcenter/scrambler 0.6.3 → 0.7.0

package/dist-cjs/puzzles/cube4/reduction/generated/hc-manifest.json

@@ -0,0 +1,38 @@
+{
+  "version": 2,
+  "puzzle": "cube4",
+  "phase": "hc",
+  "moves": [
+    "U",
+    "U2",
+    "U'",
+    "R2",
+    "F",
+    "F2",
+    "F'",
+    "D",
+    "D2",
+    "D'",
+    "L2",
+    "B",
+    "B2",
+    "B'",
+    "Uw2",
+    "Rw2",
+    "Fw2"
+  ],
+  "states": 2704156,
+  "reachableStates": 58800,
+  "reachableDense": 58800,
+  "maxDepth": 11,
+  "distances": {
+    "file": "hc-distances.bin",
+    "range": 2704156,
+    "checksum": "8720ec4a83eca33c3d56ae0ab8709c0b3d847c14d011b6dcc4413b28bd9dfa12"
+  },
+  "moveTable": {
+    "file": "hc-move.bin",
+    "range": 999600,
+    "checksum": "6bd1d8f36b77e0863425bced1dfb69df7a13dde4fb18ceeaeba00abf14519922"
+  }
+}

package/dist-cjs/puzzles/cube4/reduction/hc-pdb.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Half-class exact PDB (Phase-3 center heuristic, Fase 1 pivot).
+ *
+ * PIVOT NOTE: the original Fase-1 spec (3 exact face-pair color PDBs,
+ * C(24,4)xC(20,4) = 51M states each) is unworkable — verified that outer
+ * face turns never move centers across faces (only wide doubles do), so
+ * the exact-color orbit under the 17 search moves holds ~70 states and
+ * the bound would read "unknown" almost everywhere. This table instead
+ * tracks the EXACT arrangement of half-class bits ((color/3)^1: 12 ones,
+ * 12 zeros), which moves under every search move:
+ *
+ *   states = C(24,12) = 2,704,156, nibble-packed (~1.35 MB)
+ *
+ * Center3 (29,400 states) is a quotient of this coordinate (rank-7 pair
+ * + rl-index + parity), so this PDB dominates it by construction:
+ * bound = max(ct3, edge, hc). BFS from solved with the 17 search moves.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HC_REACHABLE = exports.HC_PDB_STATES = exports.HC_PDB_MOVES = void 0;
+exports.hcRank = hcRank;
+exports.hcUnrank = hcUnrank;
+exports.encodeHcPdb = encodeHcPdb;
+exports.getHcPdbMoveMaps = getHcPdbMoveMaps;
+exports.hcPdbDistance = hcPdbDistance;
+exports.generateHcPdb = generateHcPdb;
+exports.buildHcDense = buildHcDense;
+exports.generateHcDenseMoves = generateHcDenseMoves;
+const center3_js_1 = require("./center3.js");
+const moves_js_1 = require("../moves.js");
+exports.HC_PDB_MOVES = center3_js_1.CENTER3_MOVES.slice(0, 17);
+/** C(24,12) = 2,704,156. */
+exports.HC_PDB_STATES = 2704156;
+const CNK = (() => {
+    const table = [];
+    for (let n = 0; n <= 24; n++) {
+        table[n] = [];
+        for (let k = 0; k <= 12; k++) {
+            if (k === 0 || k === n)
+                table[n][k] = 1;
+            else if (k > n)
+                table[n][k] = 0;
+            else
+                table[n][k] = table[n - 1][k - 1] + table[n - 1][k];
+        }
+    }
+    return table;
+})();
+function halfClass(color) {
+    return (Math.floor(color / 3) ^ 1) & 1;
+}
+/** C(24,12) rank of a 24-bit mask with popcount 12 (bit i = position i holds 1). */
+function hcRank(mask) {
+    let rank = 0;
+    let k = 1;
+    for (let i = 0; i < 24; i++) {
+        if (mask & (1 << i)) {
+            rank += CNK[i][k];
+            k++;
+        }
+    }
+    return rank;
+}
+/** Inverse of hcRank: mask with popcount 12. */
+function hcUnrank(rank) {
+    let mask = 0;
+    let r = rank;
+    for (let k = 12; k >= 1; k--) {
+        for (let v = 23; v >= 0; v--) {
+            const c = CNK[v][k];
+            if (c <= r) {
+                mask |= 1 << v;
+                r -= c;
+                break;
+            }
+        }
+    }
+    return mask;
+}
+/** Encode center colors to the half-class coordinate. */
+function encodeHcPdb(centers) {
+    let mask = 0;
+    for (let i = 0; i < 24; i++) {
+        if (halfClass(centers[i]) === 1)
+            mask |= 1 << i;
+    }
+    return hcRank(mask);
+}
+/** Position permutation maps for the 17 moves (next[i] = prev[map[i]]). */
+function buildMovePositionMaps() {
+    const maps = new Int32Array(exports.HC_PDB_MOVES.length * 24);
+    for (let m = 0; m < exports.HC_PDB_MOVES.length; m++) {
+        const { face, turns } = (0, moves_js_1.parseMove)(exports.HC_PDB_MOVES[m]);
+        const effect = moves_js_1.FACE_MOVE_EFFECTS[face];
+        let pos = Array.from({ length: 24 }, (_, i) => i);
+        for (let t = 0; t < turns; t++) {
+            const next = new Array(24);
+            for (let i = 0; i < 24; i++)
+                next[i] = pos[effect.ctperm[i]];
+            pos = next;
+        }
+        for (let i = 0; i < 24; i++)
+            maps[m * 24 + i] = pos[i];
+    }
+    return maps;
+}
+let cachedMoveMaps = null;
+function getHcPdbMoveMaps() {
+    if (!cachedMoveMaps)
+        cachedMoveMaps = buildMovePositionMaps();
+    return cachedMoveMaps;
+}
+/** Nibble-packed lookup (high nibble = odd index). */
+function hcPdbDistance(packed, coordinate) {
+    const byte = packed[coordinate >> 1];
+    return (coordinate & 1) === 0 ? byte & 0x0f : byte >> 4;
+}
+/**
+ * BFS from the solved half-class mask. Returns nibble-packed distances
+ * (0x0f = unreachable). ~2.7M states x 17 moves.
+ */
+function generateHcPdb(onProgress) {
+    const maps = getHcPdbMoveMaps();
+    const packed = new Uint8Array((exports.HC_PDB_STATES + 1) >> 1).fill(0xff);
+    const get = (c) => {
+        const b = packed[c >> 1];
+        return (c & 1) === 0 ? b & 0x0f : b >> 4;
+    };
+    const set = (c, d) => {
+        const i = c >> 1;
+        if ((c & 1) === 0)
+            packed[i] = (packed[i] & 0xf0) | (d & 0x0f);
+        else
+            packed[i] = (packed[i] & 0x0f) | ((d & 0x0f) << 4);
+    };
+    // Solved mask: U/R/F faces hold half-class 1.
+    let solvedMask = 0;
+    for (const i of [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
+        solvedMask |= 1 << i;
+    const solved = hcRank(solvedMask);
+    if (solved !== 0)
+        throw new Error(`solved rank != 0 (${solved})`);
+    const queue = new Int32Array(exports.HC_PDB_STATES);
+    let head = 0;
+    let tail = 0;
+    set(0, 0);
+    queue[tail++] = 0;
+    while (head < tail) {
+        const coord = queue[head++];
+        const d = get(coord);
+        const nd = d + 1;
+        if (nd > 14)
+            continue; // nibble range; 0x0f stays "unknown" (admissible)
+        const mask = hcUnrank(coord);
+        for (let m = 0; m < exports.HC_PDB_MOVES.length; m++) {
+            const base = m * 24;
+            let nmask = 0;
+            for (let i = 0; i < 24; i++) {
+                if (mask & (1 << maps[base + i]))
+                    nmask |= 1 << i;
+            }
+            const next = hcRank(nmask);
+            if (get(next) === 0x0f) {
+                set(next, nd);
+                queue[tail++] = next;
+            }
+        }
+        if (onProgress && (head & 0x7ffff) === 0)
+            onProgress(head, exports.HC_PDB_STATES);
+    }
+    if (onProgress)
+        onProgress(tail, exports.HC_PDB_STATES);
+    return packed;
+}
+/** Number of reachable states (BFS orbit size). Fixed by the move set. */
+exports.HC_REACHABLE = 58800;
+/** Build the dense index + unpacked distances from nibble-packed BFS output. */
+function buildHcDense(packed) {
+    const index = new Int32Array(exports.HC_PDB_STATES).fill(-1);
+    let count = 0;
+    for (let c = 0; c < exports.HC_PDB_STATES; c++) {
+        if (hcPdbDistance(packed, c) !== 0x0f)
+            index[c] = count++;
+    }
+    const distances = new Uint8Array(count).fill(0x0f);
+    for (let c = 0; c < exports.HC_PDB_STATES; c++) {
+        const di = index[c];
+        if (di >= 0)
+            distances[di] = hcPdbDistance(packed, c);
+    }
+    return { index, moves: new Int32Array(0), distances, reachableCount: count };
+}
+/** Dense transition table: for each reachable state and move, dense index (or -1). */
+function generateHcDenseMoves(dense) {
+    const maps = getHcPdbMoveMaps();
+    const moves = new Int32Array(dense.reachableCount * exports.HC_PDB_MOVES.length).fill(-1);
+    for (let c = 0; c < exports.HC_PDB_STATES; c++) {
+        const di = dense.index[c];
+        if (di < 0)
+            continue;
+        const mask = hcUnrank(c);
+        for (let m = 0; m < exports.HC_PDB_MOVES.length; m++) {
+            const base = m * 24;
+            let nmask = 0;
+            for (let i = 0; i < 24; i++) {
+                if (mask & (1 << maps[base + i]))
+                    nmask |= 1 << i;
+            }
+            moves[di * exports.HC_PDB_MOVES.length + m] = dense.index[hcRank(nmask)];
+        }
+    }
+    return moves;
+}

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

@@ -13,6 +13,7 @@ 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 hc_pdb_js_1 = require("./hc-pdb.js");
 const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
 function resolveGeneratedAssetDirectory() {
     const envDirectory = process.env.CUBINGCENTER_SCRAMBLER_TABLES_DIR;
@@ -65,17 +66,27 @@ function loadCenter1(assetDirectory) {
 }
 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;
+    function unpackPruning(buffer) {
+        const pruning = new Uint8Array(450450);
+        for (let i = 0; i < 450450; i++) {
+            const byte = buffer[i >> 1];
+            pruning[i] = (i & 1) === 0 ? byte & 0x0f : byte >> 4;
+        }
+        return pruning;
     }
-    return {
+    const pruningBuffer = readChecked(node_path_1.default.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum);
+    const tables = {
         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
+        pruning: unpackPruning(pruningBuffer)
     };
+    // Tolerates older assets without the wide table (wide searches throw
+    // a clear error only when actually requested).
+    if (manifest.pruningWideTable) {
+        const wideBuffer = readChecked(node_path_1.default.join(assetDirectory, manifest.pruningWideTable.file), manifest.pruningWideTable.checksum);
+        tables.pruningWide = unpackPruning(wideBuffer);
+    }
+    return tables;
 }
 function loadCenter3(assetDirectory) {
     const manifest = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(assetDirectory, "center3-manifest.json"), "utf8"));
@@ -86,19 +97,48 @@ function loadCenter3(assetDirectory) {
 }
 function loadEdge3(assetDirectory) {
     const manifest = JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(assetDirectory, "edge3-manifest.json"), "utf8"));
+    // Keep the nibble-packed distances as-is (15.5MB instead of 31MB): every
+    // reader (phase3 getPrun, solve.ts, edge3DistanceLookup) handles both
+    // formats, and the smaller working set halves edge-table DRAM traffic.
     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) };
 }
+function loadHc(assetDirectory) {
+    const manifestPath = node_path_1.default.join(assetDirectory, "hc-manifest.json");
+    if (!(0, node_fs_1.existsSync)(manifestPath))
+        return undefined;
+    const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, "utf8"));
+    const packed = new Uint8Array(readChecked(node_path_1.default.join(assetDirectory, manifest.distances.file), manifest.distances.checksum));
+    const dense = (0, hc_pdb_js_1.buildHcDense)(packed);
+    if (manifest.moveTable) {
+        const moveBuffer = readChecked(node_path_1.default.join(assetDirectory, manifest.moveTable.file), manifest.moveTable.checksum);
+        dense.moves = new Int32Array(moveBuffer.buffer.slice(moveBuffer.byteOffset, moveBuffer.byteOffset + moveBuffer.byteLength));
+    }
+    return dense;
+}
+function loadC3Pair(assetDirectory) {
+    const filePath = node_path_1.default.join(assetDirectory, "c3_pair_dist.bin");
+    if (!(0, node_fs_1.existsSync)(filePath))
+        return undefined;
+    return new Uint8Array((0, node_fs_1.readFileSync)(filePath));
+}
 /** 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 {
+    const tables = {
         center1: loadCenter1(assetDirectory),
         center2: loadCenter2(assetDirectory),
         center3: loadCenter3(assetDirectory),
         edge3: loadEdge3(assetDirectory)
     };
+    const hc = loadHc(assetDirectory);
+    if (hc)
+        tables.hc = hc;
+    const c3Pair = loadC3Pair(assetDirectory);
+    if (c3Pair)
+        tables.c3PairDist = c3Pair;
+    return tables;
 }

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

@@ -116,12 +116,12 @@ function applyPairingMoveToArray(arr24, move) {
  * 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)
+    let mask = 0;
+    for (let i = 0; i < 12; i++) {
+        const bit = 1 << (wp[exports.PAIRING_SECOND_HALVES[i]] >> 1);
+        if ((mask & bit) !== 0)
             return false;
-        seen[pair] = 1;
+        mask |= bit;
     }
     return true;
 }