@cubingcenter/scrambler 0.6.3 → 0.8.0

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

@@ -0,0 +1,44 @@
+{
+  "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"
+  },
+  "c3PairDist": {
+    "file": "c3_pair_dist.bin",
+    "range": 4233600,
+    "bytes": 2116800,
+    "checksum": "2d070dcd9cfa8ede09cf0def93b3b2ba05a7e7e5acf631d6bf25a65bf0057035"
+  }
+}

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

@@ -0,0 +1,232 @@
+"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.hcDenseIndex = hcDenseIndex;
+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 compact coordinate list + unpacked distances from the packed PDB. */
+function buildHcDense(packed) {
+    let count = 0;
+    for (let c = 0; c < exports.HC_PDB_STATES; c++) {
+        if (hcPdbDistance(packed, c) !== 0x0f)
+            count++;
+    }
+    const coordinates = new Uint32Array(count);
+    const distances = new Uint8Array(count).fill(0x0f);
+    let denseIndex = 0;
+    for (let c = 0; c < exports.HC_PDB_STATES; c++) {
+        const distance = hcPdbDistance(packed, c);
+        if (distance === 0x0f)
+            continue;
+        coordinates[denseIndex] = c;
+        distances[denseIndex] = distance;
+        denseIndex++;
+    }
+    return { coordinates, moves: new Int32Array(0), distances, reachableCount: count };
+}
+/** Full HC coordinate -> dense index, or -1 when it is unreachable. */
+function hcDenseIndex(dense, coordinate) {
+    let low = 0;
+    let high = dense.coordinates.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >>> 1;
+        const value = dense.coordinates[middle];
+        if (value === coordinate)
+            return middle;
+        if (value < coordinate)
+            low = middle + 1;
+        else
+            high = middle - 1;
+    }
+    return -1;
+}
+/** 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 di = 0; di < dense.coordinates.length; di++) {
+        const c = dense.coordinates[di];
+        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] = hcDenseIndex(dense, hcRank(nmask));
+        }
+    }
+    return moves;
+}

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

@@ -1,19 +1,59 @@
 "use strict";
 /**
  * Node loader for the cube4 reduction tables (the committed .bin files).
- * The manifests are per-phase (`center1-manifest.json`, ...).
+ * The manifests are per-phase (`center1-manifest.json`, ...) plus the shared
+ * `hc-manifest.json`, which also seals the optional `c3_pair_dist.bin`.
+ *
+ * Every .bin read is verified: sha256 checksum AND expected byte length
+ * (derived from the manifest `range` + the known packing of each table).
+ * All integrity errors name the file and the expected/actual sizes so a
+ * corrupted download fails loudly instead of silently producing divergent
+ * scrambles. browser-loader.ts performs the identical checks.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateCube4ReductionTableBytes = estimateCube4ReductionTableBytes;
 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 center3_js_1 = require("./center3.js");
 const edge3_js_1 = require("./edge3.js");
+const hc_pdb_js_1 = require("./hc-pdb.js");
+const TABLE_MEMORY_BUDGET_BYTES = 150 * 1024 * 1024;
+/** Estimated committed table bytes per solver instance (excludes JS objects). */
+function estimateCube4ReductionTableBytes(tables) {
+    return (tables.center1.distance.byteLength +
+        tables.center1.moveMaps.byteLength +
+        tables.center2.ctMove.byteLength +
+        tables.center2.rlMove.byteLength +
+        tables.center2.pruning.byteLength +
+        (tables.center2.pruningWide?.byteLength ?? 0) +
+        tables.center3.moveTable.byteLength +
+        tables.center3.pruning.byteLength +
+        tables.edge3.distances.byteLength +
+        (tables.hc?.moves.byteLength ?? 0) +
+        (tables.hc?.distances.byteLength ?? 0) +
+        (tables.hc?.coordinates.byteLength ?? 0) +
+        (tables.c3PairDist?.byteLength ?? 0));
+}
+function assertCube4ReductionTableBudget(tables) {
+    const bytes = estimateCube4ReductionTableBytes(tables);
+    if (bytes > TABLE_MEMORY_BUDGET_BYTES) {
+        throw new Error(`Cube4 reduction tables use ${(bytes / (1024 * 1024)).toFixed(1)} MiB, above the ` +
+            `${(TABLE_MEMORY_BUDGET_BYTES / (1024 * 1024)).toFixed(0)} MiB table budget.`);
+    }
+}
 const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
+/**
+ * Byte length of `c3_pair_dist.bin`: CENTER3_STATES x 144 nibble entries
+ * (index = ct3 * 144 + f * 12 + h, see phase3-search.ts), nibble-packed.
+ * The same constant is enforced in browser-loader.ts.
+ */
+const C3_PAIR_DIST_BYTES = (center3_js_1.CENTER3_STATES * 144) / 2;
 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"))) {
@@ -46,48 +86,172 @@ function getAssetDirectoryCandidates() {
 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}`);
+function readManifest(file) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Table manifest missing: ${file} — run pnpm cube4:center1:tables etc. to regenerate the tables.`);
+        }
+        throw error;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        // Always name the file: a bare JSON.parse error is unactionable.
+        throw new Error(`Invalid table manifest JSON: ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function requireEntry(manifest, manifestPath, label) {
+    const entry = manifest[label];
+    if (!entry || typeof entry.file !== "string" || typeof entry.checksum !== "string") {
+        throw new Error(`Invalid table manifest ${manifestPath}: entry "${label}" must declare { file, checksum } — ` +
+            "run pnpm cube4:hc:tables etc. to regenerate the manifest.");
+    }
+    return entry;
+}
+/**
+ * Expected byte length of a table file from its manifest entry.
+ * `packing` matches how each table is serialized (see the load* functions).
+ */
+function expectedBytes(entry, packing) {
+    if (typeof entry.bytes === "number")
+        return entry.bytes;
+    if (typeof entry.range !== "number")
+        return undefined;
+    if (packing === "byte")
+        return entry.range;
+    if (packing === "nibble")
+        return Math.ceil(entry.range / 2);
+    return entry.range * 4;
+}
+function readChecked(file, expectedChecksum, expectedLength) {
+    let buffer;
+    try {
+        buffer = (0, node_fs_1.readFileSync)(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Table file missing: ${file}` +
+                (expectedLength !== undefined ? ` (expected ${expectedLength} bytes)` : "") +
+                " — run pnpm cube4:center1:tables etc. to regenerate the tables.");
+        }
+        throw error;
+    }
+    if (expectedLength !== undefined && buffer.length !== expectedLength) {
+        throw new Error(`Table size mismatch: ${file} (expected ${expectedLength} bytes, got ${buffer.length})`);
+    }
+    const actual = sha256(buffer);
+    if (actual !== expectedChecksum) {
+        throw new Error(`Table checksum mismatch: ${file} (expected sha256 ${expectedChecksum}, got ${actual}, ${buffer.length} bytes)`);
     }
     return buffer;
 }
+function readCheckedEntry(file, entry, packing) {
+    return readChecked(file, entry.checksum, expectedBytes(entry, packing));
+}
 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"));
+    const manifestPath = node_path_1.default.join(assetDirectory, "center1-manifest.json");
+    const manifest = readManifest(manifestPath);
+    const distanceTable = requireEntry(manifest, manifestPath, "distanceTable");
+    const moveMaps = requireEntry(manifest, manifestPath, "moveMaps");
     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))
+        distance: new Uint8Array(readCheckedEntry(node_path_1.default.join(assetDirectory, distanceTable.file), distanceTable, "nibble")),
+        moveMaps: readInt32(readCheckedEntry(node_path_1.default.join(assetDirectory, moveMaps.file), moveMaps, "int32"))
     };
 }
 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;
+    const manifestPath = node_path_1.default.join(assetDirectory, "center2-manifest.json");
+    const manifest = readManifest(manifestPath);
+    const ctMove = requireEntry(manifest, manifestPath, "ctMove");
+    const rlMove = requireEntry(manifest, manifestPath, "rlMove");
+    const pruningTable = requireEntry(manifest, manifestPath, "pruningTable");
+    // Tolerates older assets without the wide table (wide searches throw
+    // a clear error only when actually requested).
+    const pruningWideEntry = manifest.pruningWideTable
+        ? requireEntry(manifest, manifestPath, "pruningWideTable")
+        : undefined;
+    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 {
-        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
+    const pruningBuffer = readCheckedEntry(node_path_1.default.join(assetDirectory, pruningTable.file), pruningTable, "nibble");
+    const tables = {
+        ctMove: readInt32(readCheckedEntry(node_path_1.default.join(assetDirectory, ctMove.file), ctMove, "int32")),
+        rlMove: readInt32(readCheckedEntry(node_path_1.default.join(assetDirectory, rlMove.file), rlMove, "int32")),
+        pruning: unpackPruning(pruningBuffer)
     };
+    if (pruningWideEntry) {
+        const wideBuffer = readCheckedEntry(node_path_1.default.join(assetDirectory, pruningWideEntry.file), pruningWideEntry, "nibble");
+        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"));
+    const manifestPath = node_path_1.default.join(assetDirectory, "center3-manifest.json");
+    const manifest = readManifest(manifestPath);
+    const moveTable = requireEntry(manifest, manifestPath, "moveTable");
+    const pruningTable = requireEntry(manifest, manifestPath, "pruningTable");
     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))
+        moveTable: readInt32(readCheckedEntry(node_path_1.default.join(assetDirectory, moveTable.file), moveTable, "int32")),
+        pruning: new Uint8Array(readCheckedEntry(node_path_1.default.join(assetDirectory, pruningTable.file), pruningTable, "byte"))
     };
 }
 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) };
+    const manifestPath = node_path_1.default.join(assetDirectory, "edge3-manifest.json");
+    const manifest = readManifest(manifestPath);
+    const distances = requireEntry(manifest, manifestPath, "distances");
+    // `range` here already counts packed nibble BYTES (classCount / 2), unlike
+    // the other manifests — derive the length from classCount instead.
+    const classCount = manifest.classCount;
+    const length = typeof classCount === "number" ? Math.ceil(classCount / 2) : expectedBytes(distances, "byte");
+    // 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 buffer = readChecked(node_path_1.default.join(assetDirectory, distances.file), distances.checksum, length);
+    const table = new Uint8Array(buffer);
+    return { distances: table, distanceOfEdge: (0, edge3_js_1.edge3DistanceLookup)(table) };
+}
+function loadHc(assetDirectory, manifest) {
+    const manifestPath = node_path_1.default.join(assetDirectory, "hc-manifest.json");
+    const distances = requireEntry(manifest, manifestPath, "distances");
+    const packed = new Uint8Array(readCheckedEntry(node_path_1.default.join(assetDirectory, distances.file), distances, "nibble"));
+    const dense = (0, hc_pdb_js_1.buildHcDense)(packed);
+    if (manifest.moveTable !== undefined) {
+        const moveTable = requireEntry(manifest, manifestPath, "moveTable");
+        const moveBuffer = readCheckedEntry(node_path_1.default.join(assetDirectory, moveTable.file), moveTable, "int32");
+        dense.moves = new Int32Array(moveBuffer.buffer.slice(moveBuffer.byteOffset, moveBuffer.byteOffset + moveBuffer.byteLength));
+    }
+    return dense;
+}
+function loadC3Pair(assetDirectory, hcManifest) {
+    const filePath = node_path_1.default.join(assetDirectory, "c3_pair_dist.bin");
+    const manifestPath = node_path_1.default.join(assetDirectory, "hc-manifest.json");
+    if (!hcManifest || hcManifest.c3PairDist === undefined) {
+        // Optional table: absent = not deployed (fine). Present but unsealed =
+        // the historical silent-corruption hole — refuse to load it unchecked.
+        if ((0, node_fs_1.existsSync)(filePath)) {
+            throw new Error(`${filePath} exists but ${manifestPath} has no "c3PairDist" checksum entry — refusing to load it ` +
+                "unchecked. Regenerate the manifest: pnpm cube4:hc:tables.");
+        }
+        return undefined;
+    }
+    const checked = requireEntry(hcManifest, manifestPath, "c3PairDist");
+    if (typeof checked.bytes === "number" && checked.bytes !== C3_PAIR_DIST_BYTES) {
+        throw new Error(`Invalid table manifest ${manifestPath}: c3PairDist.bytes is ${checked.bytes}, expected ` +
+            `${C3_PAIR_DIST_BYTES} — run pnpm cube4:hc:tables to regenerate it.`);
+    }
+    return new Uint8Array(readChecked(node_path_1.default.join(assetDirectory, checked.file), checked.checksum, C3_PAIR_DIST_BYTES));
 }
 /** Load all cube4 reduction tables (throws if the generated assets are missing). */
 function loadCube4ReductionTables() {
@@ -95,10 +259,21 @@ function loadCube4ReductionTables() {
     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)
     };
+    // Shared manifest for the two optional PDB tables; absent = not deployed.
+    const hcManifestPath = node_path_1.default.join(assetDirectory, "hc-manifest.json");
+    const hcManifest = (0, node_fs_1.existsSync)(hcManifestPath) ? readManifest(hcManifestPath) : undefined;
+    if (hcManifest) {
+        tables.hc = loadHc(assetDirectory, hcManifest);
+    }
+    const c3Pair = loadC3Pair(assetDirectory, hcManifest);
+    if (c3Pair)
+        tables.c3PairDist = c3Pair;
+    assertCube4ReductionTableBudget(tables);
+    return tables;
 }

package/dist-cjs/puzzles/cube4/reduction/pair-transversal.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Phase-2 wing-transversal pruning (two-pair PDB).
+ *
+ * A phase-2 goal is only usable when the wings are "transversal": every
+ * pair has exactly one wing in the second-half positions
+ * (`PAIRING_SECOND_HALVES`). Only ~0.1-0.25% of center goals pass, so the
+ * phase-2 search used to enumerate millions of center goals to find the
+ * transversal ones. This table bounds how many phase-2 moves two given pairs
+ * need to become transversal, so the search can prune branches that cannot
+ * end transversal within the remaining depth.
+ *
+ * State: the unordered positions of the two wings of pair X and of pair Y
+ * (276 × 276 index; overlapping positions are unreachable). The predicate
+ * only depends on positions, so ONE table serves every pair-of-pairs.
+ * Exact BFS distances under the given phase-2 move prefix (the search set),
+ * hence admissible; generated at runtime (76,176 bytes, a few ms).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAIR_INDEX = exports.PAIR_STATES = void 0;
+exports.getWingPositionMoves = getWingPositionMoves;
+exports.getTransversalPairPdb = getTransversalPairPdb;
+const center2_js_1 = require("./center2.js");
+const pairing_coordinate_js_1 = require("./pairing-coordinate.js");
+exports.PAIR_STATES = 276;
+/** Unordered position pair (a != b) → 0..275, as a flat 24×24 table. */
+exports.PAIR_INDEX = (() => {
+    const index = new Uint16Array(24 * 24).fill(0xffff);
+    let k = 0;
+    for (let a = 0; a < 24; a++) {
+        for (let b = a + 1; b < 24; b++) {
+            index[a * 24 + b] = k;
+            index[b * 24 + a] = k;
+            k++;
+        }
+    }
+    return index;
+})();
+const PAIR_A = new Uint8Array(exports.PAIR_STATES);
+const PAIR_B = new Uint8Array(exports.PAIR_STATES);
+for (let a = 0; a < 24; a++) {
+    for (let b = a + 1; b < 24; b++) {
+        const k = exports.PAIR_INDEX[a * 24 + b];
+        PAIR_A[k] = a;
+        PAIR_B[k] = b;
+    }
+}
+const IS_SECOND = new Uint8Array(24);
+for (const p of pairing_coordinate_js_1.PAIRING_SECOND_HALVES)
+    IS_SECOND[p] = 1;
+/**
+ * Wing position maps: `posMove[m * 24 + p]` = where the wing at position p
+ * goes under CENTER2_MOVES[m] (inverse of the `wp` gather maps).
+ */
+function getWingPositionMoves() {
+    if (cachedPosMove)
+        return cachedPosMove;
+    const gather = (0, center2_js_1.getWingMoveMaps)();
+    const posMove = new Uint8Array(center2_js_1.CENTER2_MOVES.length * 24);
+    for (let m = 0; m < center2_js_1.CENTER2_MOVES.length; m++) {
+        for (let i = 0; i < 24; i++)
+            posMove[m * 24 + gather[m * 24 + i]] = i;
+    }
+    cachedPosMove = posMove;
+    return posMove;
+}
+let cachedPosMove;
+const cache = new Map();
+/** Two-pair transversal distances under the first `moveCount` CENTER2_MOVES. */
+function getTransversalPairPdb(moveCount) {
+    const hit = cache.get(moveCount);
+    if (hit)
+        return hit;
+    const posMove = getWingPositionMoves();
+    const n = exports.PAIR_STATES * exports.PAIR_STATES;
+    const dist = new Uint8Array(n).fill(0xff);
+    const queue = new Int32Array(n);
+    let tail = 0;
+    for (let x = 0; x < exports.PAIR_STATES; x++) {
+        if (IS_SECOND[PAIR_A[x]] === IS_SECOND[PAIR_B[x]])
+            continue;
+        for (let y = 0; y < exports.PAIR_STATES; y++) {
+            if (IS_SECOND[PAIR_A[y]] === IS_SECOND[PAIR_B[y]])
+                continue;
+            const ya = PAIR_A[y];
+            const yb = PAIR_B[y];
+            if (ya === PAIR_A[x] || ya === PAIR_B[x] || yb === PAIR_A[x] || yb === PAIR_B[x])
+                continue;
+            const s = x * exports.PAIR_STATES + y;
+            dist[s] = 0;
+            queue[tail++] = s;
+        }
+    }
+    for (let head = 0; head < tail; head++) {
+        const s = queue[head];
+        const x = (s / exports.PAIR_STATES) | 0;
+        const y = s - x * exports.PAIR_STATES;
+        const d = dist[s] + 1;
+        for (let m = 0; m < moveCount; m++) {
+            const row = m * 24;
+            const nx = exports.PAIR_INDEX[posMove[row + PAIR_A[x]] * 24 + posMove[row + PAIR_B[x]]];
+            const ny = exports.PAIR_INDEX[posMove[row + PAIR_A[y]] * 24 + posMove[row + PAIR_B[y]]];
+            const t = nx * exports.PAIR_STATES + ny;
+            if (dist[t] === 0xff) {
+                dist[t] = d;
+                queue[tail++] = t;
+            }
+        }
+    }
+    cache.set(moveCount, dist);
+    return dist;
+}