@cubingcenter/scrambler 0.6.3 → 0.8.0

package/dist/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/puzzles/cube4/reduction/hc-pdb.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+export declare const HC_PDB_MOVES: readonly string[];
+/** C(24,12) = 2,704,156. */
+export declare const HC_PDB_STATES = 2704156;
+/** C(24,12) rank of a 24-bit mask with popcount 12 (bit i = position i holds 1). */
+export declare function hcRank(mask: number): number;
+/** Inverse of hcRank: mask with popcount 12. */
+export declare function hcUnrank(rank: number): number;
+/** Encode center colors to the half-class coordinate. */
+export declare function encodeHcPdb(centers: Uint8Array): number;
+export declare function getHcPdbMoveMaps(): Int32Array;
+/** Nibble-packed lookup (high nibble = odd index). */
+export declare function hcPdbDistance(packed: Uint8Array, coordinate: number): number;
+/**
+ * BFS from the solved half-class mask. Returns nibble-packed distances
+ * (0x0f = unreachable). ~2.7M states x 17 moves.
+ */
+export declare function generateHcPdb(onProgress?: (done: number, total: number) => void): Uint8Array;
+/** Number of reachable states (BFS orbit size). Fixed by the move set. */
+export declare const HC_REACHABLE = 58800;
+export interface HcDenseTables {
+    /** Sorted reachable full coordinates. Used with binary search (~0.23 MB). */
+    coordinates: Uint32Array;
+    /** Dense moves: reachableCount x 17, dense indices. */
+    moves: Int32Array;
+    /** Dense distances (unpacked, 0x0f = unknown). */
+    distances: Uint8Array;
+    reachableCount: number;
+}
+/** Build the compact coordinate list + unpacked distances from the packed PDB. */
+export declare function buildHcDense(packed: Uint8Array): HcDenseTables;
+/** Full HC coordinate -> dense index, or -1 when it is unreachable. */
+export declare function hcDenseIndex(dense: Pick<HcDenseTables, "coordinates">, coordinate: number): number;
+/** Dense transition table: for each reachable state and move, dense index (or -1). */
+export declare function generateHcDenseMoves(dense: HcDenseTables): Int32Array;
+//# sourceMappingURL=hc-pdb.d.ts.map

package/dist/puzzles/cube4/reduction/hc-pdb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hc-pdb.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/hc-pdb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAA+B,CAAC;AAE1E,4BAA4B;AAC5B,eAAO,MAAM,aAAa,UAAU,CAAC;AAmBrC,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU3C;AAED,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc7C;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAMvD;AAoBD,wBAAgB,gBAAgB,IAAI,UAAU,CAG7C;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GACjD,UAAU,CA+CZ;AAED,0EAA0E;AAC1E,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,WAAW,EAAE,WAAW,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,UAAU,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAgB9D;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAC1B,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,EACzC,UAAU,EAAE,MAAM,GACjB,MAAM,CAWR;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAgBrE"}

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

@@ -0,0 +1,220 @@
+/**
+ * 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.
+ */
+import { CENTER3_MOVES } from "./center3.js";
+import { FACE_MOVE_EFFECTS, parseMove } from "../moves.js";
+export const HC_PDB_MOVES = CENTER3_MOVES.slice(0, 17);
+/** C(24,12) = 2,704,156. */
+export const 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). */
+export 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. */
+export 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. */
+export 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(HC_PDB_MOVES.length * 24);
+    for (let m = 0; m < HC_PDB_MOVES.length; m++) {
+        const { face, turns } = parseMove(HC_PDB_MOVES[m]);
+        const effect = 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;
+export function getHcPdbMoveMaps() {
+    if (!cachedMoveMaps)
+        cachedMoveMaps = buildMovePositionMaps();
+    return cachedMoveMaps;
+}
+/** Nibble-packed lookup (high nibble = odd index). */
+export 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.
+ */
+export function generateHcPdb(onProgress) {
+    const maps = getHcPdbMoveMaps();
+    const packed = new Uint8Array((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(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 < 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, HC_PDB_STATES);
+    }
+    if (onProgress)
+        onProgress(tail, HC_PDB_STATES);
+    return packed;
+}
+/** Number of reachable states (BFS orbit size). Fixed by the move set. */
+export const HC_REACHABLE = 58800;
+/** Build the compact coordinate list + unpacked distances from the packed PDB. */
+export function buildHcDense(packed) {
+    let count = 0;
+    for (let c = 0; c < 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 < 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. */
+export 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). */
+export function generateHcDenseMoves(dense) {
+    const maps = getHcPdbMoveMaps();
+    const moves = new Int32Array(dense.reachableCount * 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 < 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 * HC_PDB_MOVES.length + m] = hcDenseIndex(dense, hcRank(nmask));
+        }
+    }
+    return moves;
+}

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

@@ -1,16 +1,30 @@
 /**
  * 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.
  */
 import type { Center1Tables } from "./center1.js";
 import type { Center2Tables } from "./center2.js";
 import type { Center3Tables } from "./center3.js";
 import type { Edge3Tables } from "./edge3.js";
+import { type HcDenseTables } from "./hc-pdb.js";
+/** Estimated committed table bytes per solver instance (excludes JS objects). */
+export declare function estimateCube4ReductionTableBytes(tables: Cube4ReductionTables): number;
 export interface Cube4ReductionTables {
     center1: Center1Tables;
     center2: Center2Tables;
     center3: Center3Tables;
     edge3: Edge3Tables;
+    /** Half-class exact PDB distances (optional; absent = bound disabled). */
+    hc?: HcDenseTables;
+    /** Joint Center3 x Single Pair PDB distances (optional). */
+    c3PairDist?: Uint8Array;
 }
 /** Load all cube4 reduction tables (throws if the generated assets are missing). */
 export declare function loadCube4ReductionTables(): Cube4ReductionTables;

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

@@ -1 +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"}
+{"version":3,"file":"node-loader.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/node-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;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;AAG9C,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAI/D,iFAAiF;AACjF,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAgBrF;AAYD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;IACnB,0EAA0E;IAC1E,EAAE,CAAC,EAAE,aAAa,CAAC;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAuPD,oFAAoF;AACpF,wBAAgB,wBAAwB,IAAI,oBAAoB,CAqB/D"}

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

@@ -1,13 +1,52 @@
 /**
  * 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.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { createHash } from "node:crypto";
+import { CENTER3_STATES } from "./center3.js";
 import { edge3DistanceLookup } from "./edge3.js";
+import { buildHcDense } from "./hc-pdb.js";
+const TABLE_MEMORY_BUDGET_BYTES = 150 * 1024 * 1024;
+/** Estimated committed table bytes per solver instance (excludes JS objects). */
+export 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_STATES * 144) / 2;
 function resolveGeneratedAssetDirectory() {
     const envDirectory = process.env.CUBINGCENTER_SCRAMBLER_TABLES_DIR;
     if (envDirectory && existsSync(path.join(envDirectory, "center1-manifest.json"))) {
@@ -40,48 +79,172 @@ function getAssetDirectoryCandidates() {
 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}`);
+function readManifest(file) {
+    let text;
+    try {
+        text = 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 = 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(readFileSync(path.join(assetDirectory, "center1-manifest.json"), "utf8"));
+    const manifestPath = path.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(path.join(assetDirectory, manifest.distanceTable.file), manifest.distanceTable.checksum)),
-        moveMaps: readInt32(readChecked(path.join(assetDirectory, manifest.moveMaps.file), manifest.moveMaps.checksum))
+        distance: new Uint8Array(readCheckedEntry(path.join(assetDirectory, distanceTable.file), distanceTable, "nibble")),
+        moveMaps: readInt32(readCheckedEntry(path.join(assetDirectory, moveMaps.file), moveMaps, "int32"))
     };
 }
 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;
+    const manifestPath = path.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(path.join(assetDirectory, manifest.ctMove.file), manifest.ctMove.checksum)),
-        rlMove: readInt32(readChecked(path.join(assetDirectory, manifest.rlMove.file), manifest.rlMove.checksum)),
-        pruning
+    const pruningBuffer = readCheckedEntry(path.join(assetDirectory, pruningTable.file), pruningTable, "nibble");
+    const tables = {
+        ctMove: readInt32(readCheckedEntry(path.join(assetDirectory, ctMove.file), ctMove, "int32")),
+        rlMove: readInt32(readCheckedEntry(path.join(assetDirectory, rlMove.file), rlMove, "int32")),
+        pruning: unpackPruning(pruningBuffer)
     };
+    if (pruningWideEntry) {
+        const wideBuffer = readCheckedEntry(path.join(assetDirectory, pruningWideEntry.file), pruningWideEntry, "nibble");
+        tables.pruningWide = unpackPruning(wideBuffer);
+    }
+    return tables;
 }
 function loadCenter3(assetDirectory) {
-    const manifest = JSON.parse(readFileSync(path.join(assetDirectory, "center3-manifest.json"), "utf8"));
+    const manifestPath = path.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(path.join(assetDirectory, manifest.moveTable.file), manifest.moveTable.checksum)),
-        pruning: new Uint8Array(readChecked(path.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum))
+        moveTable: readInt32(readCheckedEntry(path.join(assetDirectory, moveTable.file), moveTable, "int32")),
+        pruning: new Uint8Array(readCheckedEntry(path.join(assetDirectory, pruningTable.file), pruningTable, "byte"))
     };
 }
 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) };
+    const manifestPath = path.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(path.join(assetDirectory, distances.file), distances.checksum, length);
+    const table = new Uint8Array(buffer);
+    return { distances: table, distanceOfEdge: edge3DistanceLookup(table) };
+}
+function loadHc(assetDirectory, manifest) {
+    const manifestPath = path.join(assetDirectory, "hc-manifest.json");
+    const distances = requireEntry(manifest, manifestPath, "distances");
+    const packed = new Uint8Array(readCheckedEntry(path.join(assetDirectory, distances.file), distances, "nibble"));
+    const dense = buildHcDense(packed);
+    if (manifest.moveTable !== undefined) {
+        const moveTable = requireEntry(manifest, manifestPath, "moveTable");
+        const moveBuffer = readCheckedEntry(path.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 = path.join(assetDirectory, "c3_pair_dist.bin");
+    const manifestPath = path.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 (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(path.join(assetDirectory, checked.file), checked.checksum, C3_PAIR_DIST_BYTES));
 }
 /** Load all cube4 reduction tables (throws if the generated assets are missing). */
 export function loadCube4ReductionTables() {
@@ -89,10 +252,21 @@ export function loadCube4ReductionTables() {
     if (!existsSync(path.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 = path.join(assetDirectory, "hc-manifest.json");
+    const hcManifest = 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/puzzles/cube4/reduction/pair-transversal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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).
+ */
+export declare const PAIR_STATES = 276;
+/** Unordered position pair (a != b) → 0..275, as a flat 24×24 table. */
+export declare const PAIR_INDEX: Uint16Array;
+/**
+ * Wing position maps: `posMove[m * 24 + p]` = where the wing at position p
+ * goes under CENTER2_MOVES[m] (inverse of the `wp` gather maps).
+ */
+export declare function getWingPositionMoves(): Uint8Array;
+/** Two-pair transversal distances under the first `moveCount` CENTER2_MOVES. */
+export declare function getTransversalPairPdb(moveCount: number): Uint8Array;
+//# sourceMappingURL=pair-transversal.d.ts.map

package/dist/puzzles/cube4/reduction/pair-transversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-transversal.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/pair-transversal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,wEAAwE;AACxE,eAAO,MAAM,UAAU,EAAE,WAWrB,CAAC;AAeL;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,CASjD;AAKD,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAsCnE"}