@cubingcenter/scrambler 0.7.0 → 0.8.0

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

@@ -1,20 +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"))) {
@@ -47,25 +86,97 @@ 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 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++) {
@@ -74,53 +185,73 @@ function loadCenter2(assetDirectory) {
         }
         return pruning;
     }
-    const pruningBuffer = readChecked(node_path_1.default.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum);
+    const pruningBuffer = readCheckedEntry(node_path_1.default.join(assetDirectory, pruningTable.file), pruningTable, "nibble");
     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)),
+        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)
     };
-    // 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);
+    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 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 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 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) {
+function loadHc(assetDirectory, manifest) {
     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 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) {
-        const moveBuffer = readChecked(node_path_1.default.join(assetDirectory, manifest.moveTable.file), manifest.moveTable.checksum);
+    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) {
+function loadC3Pair(assetDirectory, hcManifest) {
     const filePath = node_path_1.default.join(assetDirectory, "c3_pair_dist.bin");
-    if (!(0, node_fs_1.existsSync)(filePath))
+    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;
-    return new Uint8Array((0, node_fs_1.readFileSync)(filePath));
+    }
+    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() {
@@ -134,11 +265,15 @@ function loadCube4ReductionTables() {
         center3: loadCenter3(assetDirectory),
         edge3: loadEdge3(assetDirectory)
     };
-    const hc = loadHc(assetDirectory);
-    if (hc)
-        tables.hc = hc;
-    const c3Pair = loadC3Pair(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;
+}