@cubingcenter/scrambler 0.6.3 → 0.7.0

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

@@ -0,0 +1,50 @@
+/**
+ * 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 {
+    /** Full coordinate -> dense index, -1 if unreachable. */
+    index: Int32Array;
+    /** Dense moves: reachableCount x 17, dense indices. */
+    moves: Int32Array;
+    /** Dense distances (unpacked, 0x0f = unknown). */
+    distances: Uint8Array;
+    reachableCount: number;
+}
+/** Build the dense index + unpacked distances from nibble-packed BFS output. */
+export declare function buildHcDense(packed: Uint8Array): HcDenseTables;
+/** 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,yDAAyD;IACzD,KAAK,EAAE,UAAU,CAAC;IAClB,uDAAuD;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,UAAU,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAY9D;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,UAAU,CAiBrE"}

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

@@ -0,0 +1,202 @@
+/**
+ * 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 dense index + unpacked distances from nibble-packed BFS output. */
+export function buildHcDense(packed) {
+    const index = new Int32Array(HC_PDB_STATES).fill(-1);
+    let count = 0;
+    for (let c = 0; c < HC_PDB_STATES; c++) {
+        if (hcPdbDistance(packed, c) !== 0x0f)
+            index[c] = count++;
+    }
+    const distances = new Uint8Array(count).fill(0x0f);
+    for (let c = 0; c < 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). */
+export function generateHcDenseMoves(dense) {
+    const maps = getHcPdbMoveMaps();
+    const moves = new Int32Array(dense.reachableCount * HC_PDB_MOVES.length).fill(-1);
+    for (let c = 0; c < HC_PDB_STATES; c++) {
+        const di = dense.index[c];
+        if (di < 0)
+            continue;
+        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] = dense.index[hcRank(nmask)];
+        }
+    }
+    return moves;
+}

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

@@ -6,11 +6,16 @@ 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";
 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;;;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;AAG9C,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/D,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;AA2ID,oFAAoF;AACpF,wBAAgB,wBAAwB,IAAI,oBAAoB,CAgB/D"}

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

@@ -7,6 +7,7 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { edge3DistanceLookup } from "./edge3.js";
+import { buildHcDense } from "./hc-pdb.js";
 const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
 function resolveGeneratedAssetDirectory() {
     const envDirectory = process.env.CUBINGCENTER_SCRAMBLER_TABLES_DIR;
@@ -59,17 +60,27 @@ function loadCenter1(assetDirectory) {
 }
 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;
+    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(path.join(assetDirectory, manifest.pruningTable.file), manifest.pruningTable.checksum);
+    const tables = {
         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
+        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(path.join(assetDirectory, manifest.pruningWideTable.file), manifest.pruningWideTable.checksum);
+        tables.pruningWide = unpackPruning(wideBuffer);
+    }
+    return tables;
 }
 function loadCenter3(assetDirectory) {
     const manifest = JSON.parse(readFileSync(path.join(assetDirectory, "center3-manifest.json"), "utf8"));
@@ -80,19 +91,48 @@ function loadCenter3(assetDirectory) {
 }
 function loadEdge3(assetDirectory) {
     const manifest = JSON.parse(readFileSync(path.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(path.join(assetDirectory, manifest.distances.file), manifest.distances.checksum));
     return { distances, distanceOfEdge: edge3DistanceLookup(distances) };
 }
+function loadHc(assetDirectory) {
+    const manifestPath = path.join(assetDirectory, "hc-manifest.json");
+    if (!existsSync(manifestPath))
+        return undefined;
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const packed = new Uint8Array(readChecked(path.join(assetDirectory, manifest.distances.file), manifest.distances.checksum));
+    const dense = buildHcDense(packed);
+    if (manifest.moveTable) {
+        const moveBuffer = readChecked(path.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 = path.join(assetDirectory, "c3_pair_dist.bin");
+    if (!existsSync(filePath))
+        return undefined;
+    return new Uint8Array(readFileSync(filePath));
+}
 /** Load all cube4 reduction tables (throws if the generated assets are missing). */
 export function loadCube4ReductionTables() {
     const assetDirectory = resolveGeneratedAssetDirectory();
     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)
     };
+    const hc = loadHc(assetDirectory);
+    if (hc)
+        tables.hc = hc;
+    const c3Pair = loadC3Pair(assetDirectory);
+    if (c3Pair)
+        tables.c3PairDist = c3Pair;
+    return tables;
 }

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

@@ -103,12 +103,12 @@ export function applyPairingMoveToArray(arr24, move) {
  * and preserved by the phase-3 move set (verified).
  */
 export function hasPairingTransversal(wp) {
-    const seen = new Uint8Array(12);
-    for (const s of 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[PAIRING_SECOND_HALVES[i]] >> 1);
+        if ((mask & bit) !== 0)
             return false;
-        seen[pair] = 1;
+        mask |= bit;
     }
     return true;
 }

package/dist/puzzles/cube4/reduction/phase3-search.d.ts

@@ -8,6 +8,7 @@ import type { Cube4Move } from "../types.js";
 import { type Center3Tables } from "./center3.js";
 import { type Edge3Tables } from "./edge3.js";
 import type { Phase3Start } from "./phase3.js";
+import { type HcDenseTables } from "./hc-pdb.js";
 /** The 17 exploration moves (the reference's m < 17 bound). */
 export declare const SEARCH_MOVES: readonly Cube4Move[];
 export declare const ckmv3: boolean[][];
@@ -18,23 +19,128 @@ export interface Phase3Result {
     edge: Uint8Array;
 }
 /**
- * Fast table-driven Phase 3 IDA* solver class.
+ * Goal enumeration control for the phase-3 search. The classic search
+ * returns the FIRST goal-reaching sequence, which for some states is
+ * systematically unusable downstream (e.g. uniform-but-nonstandard
+ * centers). With a validator, the search keeps enumerating goal sequences
+ * — within the same node budget — until one passes or `limit` goals have
+ * been examined.
  */
+export interface Phase3SolutionValidator {
+    /** Max goal states to examine per call (bounds the extra cost). */
+    limit: number;
+    /** Goals examined so far (reset per call). */
+    examined: number;
+    /**
+     * Inspect a goal-reaching move sequence. Return true to accept it (stops
+     * the whole search); false keeps searching until `limit` goals examined.
+     */
+    validate: (moves: Cube4Move[]) => boolean;
+}
 export declare class FastPhase3Solver {
     private readonly tempep;
     private readonly moveLog;
     private readonly sym;
+    /** Transposition Table size: 2^21 = 2,097,152 entries (24 MB in RAM).
+     *  NOTE: doubling to 4M was tried and reverted (-0.07% nodes on the
+     *  corpus — the 2M working set already captures the hit locality). */
+    private static readonly TT_SIZE;
+    private static readonly TT_MASK;
+    private static readonly tt;
+    private static epoch;
+    /**
+     * Per-slot exact-length-call tag (8 MB transient). TT pruning stays
+     * epoch-scoped (unchanged traversal), but threshold proofs only trust
+     * same-call hits: a hit from another call may have validated under a
+     * different candidate, so it still prunes yet marks the proof dirty.
+     */
+    private static readonly ttGen;
+    private static callSeq;
+    private callId;
+    /** Reset the per-attempt cumulative node counter. */
+    resetEpochNodes(): void;
+    static nextEpoch(): void;
+    /** Fresh per-call id for TT-generation tagging (epoch wrap resets it). */
+    private static nextCallId;
     constructor();
+    private nodeCount;
+    /** Cumulative nodes across calls (reset per attempt via resetEpochNodes). */
+    epochNodes: number;
+    /**
+     * Proof bookkeeping for IDA* threshold propagation (reset per exact-length
+     * call). When a length-L search exhausts its tree WITHOUT hitting any of
+     * these flags, no (center, edge) solution exists at any length below
+     * `minExcess`, so the caller may skip straight to it:
+     * - `capped`: the node budget aborted the search (bounds unknown).
+     * - `limitHit`: goal enumeration hit its cap (tree not exhausted).
+     * - `sawGoal`: a goal was reached (even if the validator rejected it —
+     *   a nearby length may still validate, so only step L+1).
+     * - `ttTouched`: a transposition-table hit from ANOTHER exact-length call
+     *   skipped a subtree (same-call hits replay this call's own exhausted
+     *   subtree and stay clean; other calls may validate under a different
+     *   candidate, so their stored proof does not transfer).
+     * Bound-based axis skips need no flag: the skipped siblings are
+     * same-face turns, so noteExcess records their triangle-inequality bound.
+     */
+    private capped;
+    private limitHit;
+    private sawGoal;
+    private ttTouched;
+    private minExcess;
     private getPrun;
     /**
-     * Recursive IDA* worker on table transitions.
+     * Recursive IDA* worker on table transitions with Transposition Table pruning.
+     */
+    search(eplast: Uint8Array, ct: number, prun: number, maxl: number, lm: number, depth: number, center3Tables: Center3Tables, edge3Distances: Uint8Array, maxNodes?: number, collect?: Phase3SolutionValidator, hc?: HcDenseTables, hcCoord?: number, c3PairDist?: Uint8Array): boolean;
+    /**
+     * Record an IDA* bound prune: the child at `depth + 1` needs at least
+     * `childBound` more moves, so no solution exists through this branch
+     * below root threshold `depth + 1 + childBound`. When a bound-based axis
+     * skip also fires, the skipped siblings are same-face turns (verified:
+     * every non-empty skipAxis3 run under m < 14 is a same-base triple),
+     * hence at most 1 legal move apart — their bound is at least
+     * `childBound - 1` by the triangle inequality on the exact PDBs, so the
+     * recorded excess `depth + childBound` stays a true lower bound.
+     */
+    private noteExcess;
+    /**
+     * Search for a phase-3 solution with exact target length (first found).
+     */
+    solveLength(edge: Uint8Array, ct3: number, edist: number, length3: number, center3Tables: Center3Tables, edge3Distances: Uint8Array, maxNodes?: number, hc?: HcDenseTables, hcCoord?: number, c3PairDist?: Uint8Array): Cube4Move[] | null;
+    /**
+     * Search for a phase-3 solution with exact target length, accepting the
+     * first goal sequence that passes `validate` (up to `limit` examined,
+     * sharing `maxNodes`). With a validator that enforces the downstream
+     * requirements (reduction + standard orientation + 3x3 conversion), hard
+     * states whose first-found solutions are unusable get more draws from
+     * the same budget instead of an immediate miss.
      */
-    search(eplast: Uint8Array, ct: number, prun: number, maxl: number, lm: number, depth: number, center3Tables: Center3Tables, edge3Distances: Uint8Array): Promise<boolean>;
+    solveLengthValid(edge: Uint8Array, ct3: number, edist: number, length3: number, center3Tables: Center3Tables, edge3Distances: Uint8Array, maxNodes: number | undefined, limit: number | undefined, validate: (moves: Cube4Move[]) => boolean, hc?: HcDenseTables, hcCoord?: number, c3PairDist?: Uint8Array): Cube4Move[] | null;
     /**
-     * Search for a phase-3 solution with exact target length.
+     * Exact-length validated search that also reports what the call proved.
+     * `provenThrough` is the greatest length with provably no (center, edge)
+     * solution: set only when the tree was exhaustively explored with no goal
+     * reached, no node-cap abort, no TT hit, and complete excess info — the
+     * caller may then skip every shorter length for this candidate. Otherwise
+     * it is `length3 - 1` at most (only the attempted length is settled).
      */
-    solveLength(edge: Uint8Array, ct3: number, edist: number, length3: number, center3Tables: Center3Tables, edge3Distances: Uint8Array): Promise<Cube4Move[] | null>;
+    solveLengthProven(edge: Uint8Array, ct3: number, edist: number, length3: number, center3Tables: Center3Tables, edge3Distances: Uint8Array, maxNodes: number | undefined, limit: number | undefined, validate: (moves: Cube4Move[]) => boolean, hc?: HcDenseTables, hcCoord?: number, c3PairDist?: Uint8Array): {
+        moves: Cube4Move[] | null;
+        provenThrough: number;
+        nodesUsed: number;
+    };
 }
+/** Temporary instrumentation for proof-statistics (CUBE4_PROOF_STATS=1). */
+export declare const proofStats: {
+    total: number;
+    capped: number;
+    limitHit: number;
+    sawGoal: number;
+    ttTouched: number;
+    clean: number;
+    jumpSum: number;
+};
+export declare function resetProofStats(): void;
 /**
  * Solve Phase 3 with iterative deepening on a single Phase3Start.
  */

package/dist/puzzles/cube4/reduction/phase3-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"phase3-search.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/phase3-search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAIL,KAAK,WAAW,EAEjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,+DAA+D;AAC/D,eAAO,MAAM,YAAY,EAAE,SAAS,SAAS,EAA+B,CAAC;AAa7E,eAAO,MAAM,KAAK,EAAE,OAAO,EAAE,EAAgE,CAAC;AAO9F,eAAO,MAAM,SAAS,EAAE,MAAM,EAA2B,CAAC;AAU1D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;;IAQhC,OAAO,CAAC,OAAO;IAKf;;OAEG;IACU,MAAM,CACjB,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,OAAO,CAAC;IA8DnB;;OAEG;IACU,WAAW,CACtB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC;CAkB/B;AAID;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,aAAa,EAC5B,WAAW,EAAE,WAAW,EACxB,SAAS,SAAK,GACb,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAmC9B"}
+{"version":3,"file":"phase3-search.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/phase3-search.ts"],"names":[],"mappings":"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"}