@cubingcenter/scrambler 0.6.3 → 0.8.0

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

@@ -0,0 +1,107 @@
+/**
+ * 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).
+ */
+import { CENTER2_MOVES, getWingMoveMaps } from "./center2.js";
+import { PAIRING_SECOND_HALVES } from "./pairing-coordinate.js";
+export const PAIR_STATES = 276;
+/** Unordered position pair (a != b) → 0..275, as a flat 24×24 table. */
+export const 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(PAIR_STATES);
+const PAIR_B = new Uint8Array(PAIR_STATES);
+for (let a = 0; a < 24; a++) {
+    for (let b = a + 1; b < 24; b++) {
+        const k = PAIR_INDEX[a * 24 + b];
+        PAIR_A[k] = a;
+        PAIR_B[k] = b;
+    }
+}
+const IS_SECOND = new Uint8Array(24);
+for (const p of 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).
+ */
+export function getWingPositionMoves() {
+    if (cachedPosMove)
+        return cachedPosMove;
+    const gather = getWingMoveMaps();
+    const posMove = new Uint8Array(CENTER2_MOVES.length * 24);
+    for (let m = 0; m < 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. */
+export function getTransversalPairPdb(moveCount) {
+    const hit = cache.get(moveCount);
+    if (hit)
+        return hit;
+    const posMove = getWingPositionMoves();
+    const n = PAIR_STATES * PAIR_STATES;
+    const dist = new Uint8Array(n).fill(0xff);
+    const queue = new Int32Array(n);
+    let tail = 0;
+    for (let x = 0; x < PAIR_STATES; x++) {
+        if (IS_SECOND[PAIR_A[x]] === IS_SECOND[PAIR_B[x]])
+            continue;
+        for (let y = 0; y < 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 * PAIR_STATES + y;
+            dist[s] = 0;
+            queue[tail++] = s;
+        }
+    }
+    for (let head = 0; head < tail; head++) {
+        const s = queue[head];
+        const x = (s / PAIR_STATES) | 0;
+        const y = s - x * PAIR_STATES;
+        const d = dist[s] + 1;
+        for (let m = 0; m < moveCount; m++) {
+            const row = m * 24;
+            const nx = PAIR_INDEX[posMove[row + PAIR_A[x]] * 24 + posMove[row + PAIR_B[x]]];
+            const ny = PAIR_INDEX[posMove[row + PAIR_A[y]] * 24 + posMove[row + PAIR_B[y]]];
+            const t = nx * PAIR_STATES + ny;
+            if (dist[t] === 0xff) {
+                dist[t] = d;
+                queue[tail++] = t;
+            }
+        }
+    }
+    cache.set(moveCount, dist);
+    return dist;
+}

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,25 +19,133 @@ 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^20 = 1,048,576 entries (12 MiB per solve).
+     * The previous 2M table used 24 MiB per process, plus a separate 8 MiB
+     * generation array. The compact 1M table leaves room for concurrent
+     * solvers under the 150 MiB reduction-table budget. */
+    private static readonly TT_SIZE;
+    private static readonly TT_MASK;
+    private readonly tt;
+    private static readonly CALL_ID_LIMIT;
+    private callSeq;
+    private callId;
+    private contextCenter3;
+    private contextEdge3;
+    /** Reset this solver's cumulative node counter (legacy method name). */
+    resetEpochNodes(): void;
+    clearTranspositionTable(): void;
+    private setTableContext;
+    /** Fresh per-call id for TT-generation tagging. */
+    private nextCallId;
     constructor();
-    private getPrun;
+    private ensureDepth;
+    private nodeCount;
+    /** Cumulative nodes across calls (reset per solve generation). */
+    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, and the hit was not certified goal-free across
+     *   candidate validators.
+     * 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;
+    /**
+     * Root-length coverage of the tightest TT hit this call (depth +
+     * storedDepth): the pruned subtree proves no goal at or below that root
+     * length under the call's predicate. `Number.MAX_SAFE_INTEGER` when no hit
+     * pruned anything. Feeds `validatedThrough`.
+     */
+    private ttCoverage;
+    /**
+     * 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 (inlined at the four gate sites): 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.
+     */
+    /**
+     * 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;
     /**
-     * Recursive IDA* worker on table transitions.
+     * 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;
+        validatedThrough: 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.
  */
-export declare function solvePhase3(start: Phase3Start, center3Tables: Center3Tables, edge3Tables: Edge3Tables, maxLength?: number): Promise<Phase3Result | null>;
+export declare function solvePhase3(start: Phase3Start, center3Tables: Center3Tables, edge3Tables: Edge3Tables, maxLength?: number, maxNodes?: number): Promise<Phase3Result | null>;
 //# sourceMappingURL=phase3-search.d.ts.map

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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"}