@cubingcenter/scrambler 0.6.3 → 0.8.0

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

@@ -1,22 +1,74 @@
 "use strict";
 /**
  * Browser 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`.
+ *
+ * Integrity — identical to node-loader.ts: every downloaded .bin is verified
+ * against the manifest sha256 + expected byte length (on the DECOMPRESSED
+ * payload, so .br/.gz variants and the raw file are checked the same way).
+ *
+ * Optional tables (`hc` + `c3PairDist`), NEVER silent:
+ *  - `hc-manifest.json` present → its entries must download and verify, else
+ *    the whole load REJECTS (node throws too). There is no silent degradation
+ *    to an unpruned search: it would change the scramble produced for the
+ *    same seed, breaking node/browser determinism.
+ *  - `hc-manifest.json` absent (404) → the optional tables were not deployed;
+ *    `c3_pair_dist.bin` is then probed to tell "not deployed" (both absent →
+ *    skip, like node) apart from "stale/half-deployed assets" (bin present,
+ *    manifest missing → REJECT with an actionable message — node refuses the
+ *    same asset set).
+ * There is deliberately no "degraded" flag: the only valid outcomes are
+ * "fully loaded tables" or "loud failure", so both platforms always compute
+ * the same scrambles.
+ *
+ * Caching: concurrent loads share ONE in-flight promise (one fetch pass per
+ * table). The promise is kept after success; when it rejects it is purged so
+ * the next call can retry instead of being stuck on a poisoned cache.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCachedCube4Tables = getCachedCube4Tables;
 exports.clearCachedCube4Tables = clearCachedCube4Tables;
 exports.loadCube4ReductionTablesBrowser = loadCube4ReductionTablesBrowser;
+const center3_js_1 = require("./center3.js");
 const edge3_js_1 = require("./edge3.js");
 const compressed_fetch_js_1 = require("../../shared/compressed-fetch.js");
+const hc_pdb_js_1 = require("./hc-pdb.js");
 const GENERATED_DIRECTORY = "puzzles/cube4/reduction/generated";
 const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
+const TABLE_MEMORY_BUDGET_BYTES = 150 * 1024 * 1024;
+/**
+ * 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.
+ * Kept in sync with node-loader.ts.
+ */
+const C3_PAIR_DIST_BYTES = (center3_js_1.CENTER3_STATES * 144) / 2;
 let cachedTables;
+let cachedTablesPromise;
+function assertCube4ReductionTableBudget(tables) {
+    const bytes = 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);
+    if (bytes > TABLE_MEMORY_BUDGET_BYTES) {
+        throw new Error(`Cube4 reduction tables use ${(bytes / (1024 * 1024)).toFixed(1)} MiB, above the 150 MiB table budget.`);
+    }
+}
 function getCachedCube4Tables() {
     return cachedTables;
 }
 function clearCachedCube4Tables() {
     cachedTables = undefined;
+    cachedTablesPromise = undefined;
 }
 function resolveBaseUrl(provided) {
     if (provided) {
@@ -31,33 +83,95 @@ function resolveBaseUrl(provided) {
     }
     return ".";
 }
-async function loadCube4ReductionTablesBrowser(baseUrl) {
-    if (cachedTables) {
-        return cachedTables;
+function loadCube4ReductionTablesBrowser(baseUrl) {
+    if (cachedTablesPromise) {
+        // One shared in-flight promise: concurrent calls trigger exactly one
+        // fetch pass (dedup), and the resolved value stays cached afterwards.
+        return cachedTablesPromise;
     }
     const resolved = resolveBaseUrl(baseUrl);
-    const [center1, center2, center3, edge3] = await Promise.all([
-        loadCenter1(resolved),
-        loadCenter2(resolved),
-        loadCenter3(resolved),
-        loadEdge3(resolved)
-    ]);
-    cachedTables = { center1, center2, center3, edge3 };
-    return cachedTables;
+    const promise = (async () => {
+        const [center1, center2, center3, edge3, optional] = await Promise.all([
+            loadCenter1(resolved),
+            loadCenter2(resolved),
+            loadCenter3(resolved),
+            loadEdge3(resolved),
+            loadOptionalTables(resolved)
+        ]);
+        const tables = { center1, center2, center3, edge3 };
+        if (optional.hc)
+            tables.hc = optional.hc;
+        if (optional.c3PairDist)
+            tables.c3PairDist = optional.c3PairDist;
+        assertCube4ReductionTableBudget(tables);
+        return tables;
+    })();
+    cachedTablesPromise = promise;
+    promise.then((value) => {
+        cachedTables = value;
+    }, () => {
+        // A failed load must not poison the cache: purge the rejected promise
+        // so a later call retries from scratch.
+        if (cachedTablesPromise === promise)
+            cachedTablesPromise = undefined;
+    });
+    return promise;
+}
+function requireEntry(entry, manifestUrl, label) {
+    if (!entry || typeof entry.file !== "string" || typeof entry.checksum !== "string") {
+        throw new Error(`Invalid table manifest ${manifestUrl}: entry "${label}" must declare { file, checksum } — ` +
+            "the deployed assets are stale; sync them with pnpm tables:web:sync.");
+    }
+    return entry;
 }
-async function fetchJson(baseUrl, file) {
+/**
+ * Expected byte length of a table file from its manifest entry.
+ * `packing` matches how each table is serialized — keep in sync with
+ * node-loader.ts.
+ */
+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;
+}
+async function fetchVerified(baseUrl, entry, packing, expectedLength) {
+    const length = expectedLength ?? expectedBytes(entry, packing);
+    return (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedSha256: entry.checksum,
+        ...(length !== undefined ? { expectedBytes: length } : {})
+    });
+}
+async function fetchManifest(baseUrl, file) {
     const url = `${baseUrl}/${GENERATED_DIRECTORY}/${file}`;
     const response = await fetch(url);
     if (!response.ok) {
-        throw new Error(`Failed to load ${file}: ${response.status} ${response.statusText}`);
+        throw new Error(`Failed to load table manifest ${url}: ${response.status} ${response.statusText}`);
+    }
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        // Always name the URL: a bare JSON.parse error is unactionable.
+        throw new Error(`Invalid table manifest JSON: ${url}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    return response.json();
 }
 async function loadCenter1(baseUrl) {
-    const manifest = await fetchJson(baseUrl, "center1-manifest.json");
+    const manifestUrl = `${baseUrl}/${GENERATED_DIRECTORY}/center1-manifest.json`;
+    const manifest = await fetchManifest(baseUrl, "center1-manifest.json");
+    const distanceTable = requireEntry(manifest.distanceTable, manifestUrl, "distanceTable");
+    const moveMaps = requireEntry(manifest.moveMaps, manifestUrl, "moveMaps");
     const [distanceBuffer, moveMapsBuffer] = await Promise.all([
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.distanceTable.file, { cacheName: CACHE_NAME, compressed: manifest.distanceTable.compressed !== false }),
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.moveMaps.file, { cacheName: CACHE_NAME, compressed: manifest.moveMaps.compressed !== false })
+        fetchVerified(baseUrl, distanceTable, "nibble"),
+        fetchVerified(baseUrl, moveMaps, "int32")
     ]);
     return {
         distance: new Uint8Array(distanceBuffer),
@@ -65,27 +179,48 @@ async function loadCenter1(baseUrl) {
     };
 }
 async function loadCenter2(baseUrl) {
-    const manifest = await fetchJson(baseUrl, "center2-manifest.json");
+    const manifestUrl = `${baseUrl}/${GENERATED_DIRECTORY}/center2-manifest.json`;
+    const manifest = await fetchManifest(baseUrl, "center2-manifest.json");
+    const ctMove = requireEntry(manifest.ctMove, manifestUrl, "ctMove");
+    const rlMove = requireEntry(manifest.rlMove, manifestUrl, "rlMove");
+    const pruningTable = requireEntry(manifest.pruningTable, manifestUrl, "pruningTable");
+    const pruningWideEntry = manifest.pruningWideTable
+        ? requireEntry(manifest.pruningWideTable, manifestUrl, "pruningWideTable")
+        : undefined;
     const [ctMoveBuffer, rlMoveBuffer, pruningBuffer] = await Promise.all([
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.ctMove.file, { cacheName: CACHE_NAME, compressed: manifest.ctMove.compressed !== false }),
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.rlMove.file, { cacheName: CACHE_NAME, compressed: manifest.rlMove.compressed !== false }),
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.pruningTable.file, { cacheName: CACHE_NAME, compressed: manifest.pruningTable.compressed !== false })
+        fetchVerified(baseUrl, ctMove, "int32"),
+        fetchVerified(baseUrl, rlMove, "int32"),
+        fetchVerified(baseUrl, pruningTable, "nibble")
     ]);
-    const ctMove = new Int32Array(ctMoveBuffer);
-    const rlMove = new Int32Array(rlMoveBuffer);
+    const ctMoveValues = new Int32Array(ctMoveBuffer);
+    const rlMoveValues = new Int32Array(rlMoveBuffer);
     const pruningPacked = new Uint8Array(pruningBuffer);
     const pruning = new Uint8Array(450450);
     for (let i = 0; i < 450450; i++) {
         const byte = pruningPacked[i >> 1];
         pruning[i] = (i & 1) === 0 ? byte & 0x0f : byte >> 4;
     }
-    return { ctMove, rlMove, pruning };
+    const tables = { ctMove: ctMoveValues, rlMove: rlMoveValues, pruning };
+    if (pruningWideEntry) {
+        const wideBuffer = await fetchVerified(baseUrl, pruningWideEntry, "nibble");
+        const widePacked = new Uint8Array(wideBuffer);
+        const pruningWide = new Uint8Array(450450);
+        for (let i = 0; i < 450450; i++) {
+            const byte = widePacked[i >> 1];
+            pruningWide[i] = (i & 1) === 0 ? byte & 0x0f : byte >> 4;
+        }
+        tables.pruningWide = pruningWide;
+    }
+    return tables;
 }
 async function loadCenter3(baseUrl) {
-    const manifest = await fetchJson(baseUrl, "center3-manifest.json");
+    const manifestUrl = `${baseUrl}/${GENERATED_DIRECTORY}/center3-manifest.json`;
+    const manifest = await fetchManifest(baseUrl, "center3-manifest.json");
+    const moveTable = requireEntry(manifest.moveTable, manifestUrl, "moveTable");
+    const pruningTable = requireEntry(manifest.pruningTable, manifestUrl, "pruningTable");
     const [moveTableBuffer, pruningBuffer] = await Promise.all([
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.moveTable.file, { cacheName: CACHE_NAME, compressed: manifest.moveTable.compressed !== false }),
-        (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.pruningTable.file, { cacheName: CACHE_NAME, compressed: manifest.pruningTable.compressed !== false })
+        fetchVerified(baseUrl, moveTable, "int32"),
+        fetchVerified(baseUrl, pruningTable, "byte")
     ]);
     return {
         moveTable: new Int32Array(moveTableBuffer),
@@ -93,8 +228,68 @@ async function loadCenter3(baseUrl) {
     };
 }
 async function loadEdge3(baseUrl) {
-    const manifest = await fetchJson(baseUrl, "edge3-manifest.json");
-    const distancesBuffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, GENERATED_DIRECTORY, manifest.distances.file, { cacheName: CACHE_NAME, compressed: manifest.distances.compressed !== false });
-    const distances = new Uint8Array(distancesBuffer);
-    return { distances, distanceOfEdge: (0, edge3_js_1.edge3DistanceLookup)(distances) };
+    const manifestUrl = `${baseUrl}/${GENERATED_DIRECTORY}/edge3-manifest.json`;
+    const manifest = await fetchManifest(baseUrl, "edge3-manifest.json");
+    const distances = requireEntry(manifest.distances, manifestUrl, "distances");
+    // `range` here already counts packed nibble BYTES (classCount / 2), unlike
+    // the other manifests — derive the length from classCount instead.
+    const length = typeof manifest.classCount === "number" ? Math.ceil(manifest.classCount / 2) : expectedBytes(distances, "byte");
+    const distancesBuffer = await fetchVerified(baseUrl, distances, "nibble", length);
+    // Keep nibble-packed (see node-loader.ts): all readers handle both formats.
+    const table = new Uint8Array(distancesBuffer);
+    return { distances: table, distanceOfEdge: (0, edge3_js_1.edge3DistanceLookup)(table) };
+}
+/**
+ * The two optional PDB tables sealed in `hc-manifest.json`. Semantics mirror
+ * node-loader.ts exactly (see the header comment): present → verified or
+ * reject; absent → probe the c3 bin so stale deployments fail loudly.
+ */
+async function loadOptionalTables(baseUrl) {
+    const manifestUrl = `${baseUrl}/${GENERATED_DIRECTORY}/hc-manifest.json`;
+    const response = await fetch(manifestUrl);
+    let manifest;
+    if (response.ok) {
+        const text = await response.text();
+        try {
+            manifest = JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`Invalid table manifest JSON: ${manifestUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    else if (response.status !== 404) {
+        throw new Error(`Failed to load table manifest ${manifestUrl}: ${response.status} ${response.statusText}`);
+    }
+    const result = {};
+    if (manifest?.c3PairDist !== undefined) {
+        const entry = requireEntry(manifest.c3PairDist, manifestUrl, "c3PairDist");
+        if (typeof entry.bytes === "number" && entry.bytes !== C3_PAIR_DIST_BYTES) {
+            throw new Error(`Invalid table manifest ${manifestUrl}: c3PairDist.bytes is ${entry.bytes}, expected ` +
+                `${C3_PAIR_DIST_BYTES} — sync the assets with pnpm tables:web:sync.`);
+        }
+        const buffer = await fetchVerified(baseUrl, entry, "nibble", C3_PAIR_DIST_BYTES);
+        result.c3PairDist = new Uint8Array(buffer);
+    }
+    else {
+        // Mirror node's fs check: bin present but unsealed = broken deployment.
+        const probeUrl = `${baseUrl}/${GENERATED_DIRECTORY}/c3_pair_dist.bin`;
+        const probe = await fetch(probeUrl);
+        if (probe.ok) {
+            throw new Error(`c3_pair_dist.bin is deployed (${probeUrl}) but hc-manifest.json has no "c3PairDist" checksum ` +
+                `entry (${manifestUrl}) — refusing to load tables without integrity checks (node fails on the ` +
+                "same assets). Sync the assets: pnpm tables:web:sync.");
+        }
+    }
+    if (manifest) {
+        const distances = requireEntry(manifest.distances, manifestUrl, "distances");
+        const packed = new Uint8Array(await fetchVerified(baseUrl, distances, "nibble"));
+        const dense = (0, hc_pdb_js_1.buildHcDense)(packed);
+        if (manifest.moveTable !== undefined) {
+            const moveTable = requireEntry(manifest.moveTable, manifestUrl, "moveTable");
+            const moveBuffer = await fetchVerified(baseUrl, moveTable, "int32");
+            dense.moves = new Int32Array(moveBuffer);
+        }
+        result.hc = dense;
+    }
+    return result;
 }

package/dist-cjs/puzzles/cube4/reduction/center2.js

@@ -13,19 +13,24 @@
  *  - goal: ct == 0 and rl in the 6 reference goal patterns (even parity);
  *  - the 28-move set keeps the ct and rl position sets separate, so the move
  *    tables factor: ctmv (6,435×28) and rlmv (70×28);
- *  - the search explores the first 23 moves (face moves + Uw2/Rw/Rw2/Rw').
+ *  - the search explores the first 23 moves (face moves + Uw2/Rw/Rw2/Rw')
+ *    by default; the wide set (`CENTER2_SEARCH_MOVES_WIDE`, all 28, with
+ *    the `pruningWide` table) additionally tries Dw2/Lw/Lw2/Lw'/Bw2.
  *
  * The phase-1 → phase-2 bridge (alignment + encode) is in `reduction.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CENTER2_STATES = exports.CENTER2_RL_STATES = exports.CENTER2_CT_STATES = exports.CENTER2_GOAL_RL = exports.CENTER2_SEARCH_MOVES = exports.CENTER2_MOVES = void 0;
+exports.CENTER2_CHIRAL_STATES = exports.CENTER2_CHIRAL_CT_STATES = exports.ALIGNMENT_ROTATIONS = exports.CENTER2_STATES = exports.CENTER2_RL_STATES = exports.CENTER2_CT_STATES = exports.CENTER2_GOAL_RL = exports.CENTER2_SEARCH_MOVES_WIDE = exports.CENTER2_SEARCH_MOVES = exports.CENTER2_MOVES = void 0;
 exports.wingPermutationParity = wingPermutationParity;
 exports.encodeCenter2 = encodeCenter2;
 exports.isCenter2Goal = isCenter2Goal;
 exports.center2Bridge = center2Bridge;
 exports.generateCenter2Tables = generateCenter2Tables;
+exports.encodeCenter2ChiralCt = encodeCenter2ChiralCt;
+exports.generateCenter2ChiralTables = generateCenter2ChiralTables;
 exports.solveCenter2 = solveCenter2;
 exports.solveCenter2All = solveCenter2All;
+exports.getWingMoveMaps = getWingMoveMaps;
 exports.solveCenter2GatedLength = solveCenter2GatedLength;
 exports.solveCenter2Gated = solveCenter2Gated;
 exports.verifyCenter2 = verifyCenter2;
@@ -41,11 +46,23 @@ exports.CENTER2_MOVES = [
 ];
 /** The search's exploration set (the first 23 of CENTER2_MOVES). */
 exports.CENTER2_SEARCH_MOVES = exports.CENTER2_MOVES.slice(0, 23);
+/**
+ * The wide exploration set: all 28 moves (adds Dw2/Lw/Lw2/Lw'/Bw2).
+ * Searches over this set must use the `pruningWide` table — the
+ * 23-move pruning distances are inadmissible here (they overestimate).
+ */
+exports.CENTER2_SEARCH_MOVES_WIDE = exports.CENTER2_MOVES;
 /** The 6 reference goal rl patterns (full 70-space values, even parity). */
 exports.CENTER2_GOAL_RL = [0, 18, 28, 46, 54, 56];
 exports.CENTER2_CT_STATES = 6435;
 exports.CENTER2_RL_STATES = 70;
 exports.CENTER2_STATES = exports.CENTER2_CT_STATES * exports.CENTER2_RL_STATES;
+const CENTER2_GOAL_FLAGS = (() => {
+    const flags = new Uint8Array(exports.CENTER2_RL_STATES);
+    for (const rl of exports.CENTER2_GOAL_RL)
+        flags[rl] = 1;
+    return flags;
+})();
 // ct positions: U(0-3), D(12-15), F(8-11), B(20-23) — the reference's face
 // order {U, D, F, B}, in this repo's face-major numbering.
 const CT_POS = [0, 1, 2, 3, 12, 13, 14, 15, 8, 9, 10, 11, 20, 21, 22, 23];
@@ -109,7 +126,7 @@ function encodeCenter2(state) {
     return { ct: ctRank, rl: rlRank };
 }
 function isCenter2Goal(ct, rl) {
-    return ct === 0 && exports.CENTER2_GOAL_RL.includes(rl);
+    return ct === 0 && CENTER2_GOAL_FLAGS[rl] === 1;
 }
 /**
  * The phase-2 coordinate is only valid for states where exactly 8 of the
@@ -125,6 +142,11 @@ const ALIGNMENT_CANDIDATES = [
     ["Uw", "Dw'"]
 ];
 function center2InvariantDiffs(centers) {
+    const rlAxis = centers[RL_POS[7]] % 3;
+    for (let i = 0; i < 7; i++) {
+        if (centers[RL_POS[i]] % 3 !== rlAxis)
+            return { ctDiff: -1, rlDiff: -1 };
+    }
     let ctDiff = 0;
     let rlDiff = 0;
     for (let i = 0; i < 15; i++) {
@@ -137,12 +159,18 @@ function center2InvariantDiffs(centers) {
     }
     return { ctDiff, rlDiff };
 }
+exports.ALIGNMENT_ROTATIONS = [
+    [],
+    ["z"],
+    ["y"]
+];
 /**
  * Phase-1 → phase-2 bridge: apply the shortest alignment candidate that
  * makes the state coordinate-invariant, then encode.
  */
 function center2Bridge(state) {
-    for (const alignment of ALIGNMENT_CANDIDATES) {
+    for (let idx = 0; idx < ALIGNMENT_CANDIDATES.length; idx++) {
+        const alignment = ALIGNMENT_CANDIDATES[idx];
         const aligned = alignment.length === 0
             ? state
             : (0, moves_js_1.applyCube4Algorithm)(state, alignment);
@@ -150,6 +178,7 @@ function center2Bridge(state) {
         if (ctDiff === 8 && rlDiff === 4) {
             return {
                 alignment: [...alignment],
+                rotation: [...exports.ALIGNMENT_ROTATIONS[idx]],
                 state: aligned,
                 encoded: encodeCenter2(aligned)
             };
@@ -259,7 +288,123 @@ function generateCenter2Tables() {
             }
         }
     }
-    return { ctMove, rlMove, pruning };
+    // Wide pruning BFS: same goals, all 28 moves (exact distances for the
+    // wide search; the 23-move table overestimates there).
+    const pruningWide = new Uint8Array(exports.CENTER2_STATES).fill(0xff);
+    const wideQueue = [];
+    for (const rl of exports.CENTER2_GOAL_RL) {
+        pruningWide[rl] = 0;
+        wideQueue.push(rl);
+    }
+    let wideHead = 0;
+    while (wideHead < wideQueue.length) {
+        const idx = wideQueue[wideHead++];
+        const ct = Math.floor(idx / exports.CENTER2_RL_STATES);
+        const rl = idx % exports.CENTER2_RL_STATES;
+        const d = pruningWide[idx];
+        for (let m = 0; m < exports.CENTER2_SEARCH_MOVES_WIDE.length; m++) {
+            const nextCt = ctMove[ct * exports.CENTER2_MOVES.length + m];
+            const nextRl = rlMove[rl * exports.CENTER2_MOVES.length + m];
+            const next = nextCt * exports.CENTER2_RL_STATES + nextRl;
+            if (pruningWide[next] === 0xff) {
+                pruningWide[next] = d + 1;
+                wideQueue.push(next);
+            }
+        }
+    }
+    return { ctMove, rlMove, pruning, pruningWide };
+}
+// ---------------------------------------------------------------------------
+// Chiral (absolute-ct) phase-2 tables
+// ---------------------------------------------------------------------------
+/**
+ * The ct rank above is RELATIVE to ct[15], so `ct == 0` accepts both
+ * assignments of the two non-R/L axes to the U/D and F/B face-pairs. Only
+ * one of them survives the downstream chirality gate (`axisDet`: the U, R, F
+ * axes must form a right-handed frame, i.e. U/D must hold axis (a + 2) % 3
+ * when R/L holds axis a). The chiral coordinate ranks the ABSOLUTE pattern
+ * "which of the 16 U/D/F/B positions hold the U/D-bound axis" (C(16,8) =
+ * 12,870) and its pruning measures the distance to the chirality-correct
+ * goals only, so the phase-2 search never walks wrong-chirality goal paths.
+ * Same goal set as `ct == 0 && axisDet == 1`; generated at runtime (~1.6 MB).
+ */
+exports.CENTER2_CHIRAL_CT_STATES = 12870;
+exports.CENTER2_CHIRAL_STATES = exports.CENTER2_CHIRAL_CT_STATES * exports.CENTER2_RL_STATES;
+function rankSubset16(bits) {
+    let idx = 0;
+    let r = 8;
+    for (let i = 15; i >= 0 && r > 0; i--) {
+        if (bits[i] === 1) {
+            idx += CNK[i][r];
+            r--;
+        }
+    }
+    return idx;
+}
+function unrankSubset16(idx) {
+    const bits = new Uint8Array(16);
+    let r = 8;
+    for (let i = 15; i >= 0 && r > 0; i--) {
+        if (idx >= CNK[i][r]) {
+            idx -= CNK[i][r];
+            bits[i] = 1;
+            r--;
+        }
+    }
+    return bits;
+}
+/** Chiral ct rank of a coordinate-invariant (bridged) phase-2 state. */
+function encodeCenter2ChiralCt(state) {
+    const rlAxis = state.centers[RL_POS[0]] % 3;
+    const udAxis = (rlAxis + 2) % 3;
+    const bits = new Uint8Array(16);
+    for (let i = 0; i < 16; i++)
+        bits[i] = state.centers[CT_POS[i]] % 3 === udAxis ? 1 : 0;
+    return rankSubset16(bits);
+}
+function generateCenter2ChiralTables(rlMove) {
+    const moveMaps = buildMovePositionMaps();
+    const nMoves = exports.CENTER2_MOVES.length;
+    const ctMove = new Uint16Array(exports.CENTER2_CHIRAL_CT_STATES * nMoves);
+    const full = new Uint8Array(24);
+    const bits = new Uint8Array(16);
+    for (let ct = 0; ct < exports.CENTER2_CHIRAL_CT_STATES; ct++) {
+        const pattern = unrankSubset16(ct);
+        full.fill(0);
+        for (let i = 0; i < 16; i++)
+            full[CT_POS[i]] = pattern[i];
+        for (let m = 0; m < nMoves; m++) {
+            for (let i = 0; i < 16; i++)
+                bits[i] = full[moveMaps[m * 24 + CT_POS[i]]];
+            ctMove[ct * nMoves + m] = rankSubset16(bits);
+        }
+    }
+    const goalBits = new Uint8Array(16);
+    for (let i = 0; i < 8; i++)
+        goalBits[i] = 1; // CT_POS[0..7] = U and D faces
+    const goalCt = rankSubset16(goalBits);
+    const pruning = new Uint8Array(exports.CENTER2_CHIRAL_STATES).fill(0xff);
+    const queue = new Int32Array(exports.CENTER2_CHIRAL_STATES);
+    let tail = 0;
+    for (const rl of exports.CENTER2_GOAL_RL) {
+        const idx = goalCt * exports.CENTER2_RL_STATES + rl;
+        pruning[idx] = 0;
+        queue[tail++] = idx;
+    }
+    for (let head = 0; head < tail; head++) {
+        const idx = queue[head];
+        const ct = (idx / exports.CENTER2_RL_STATES) | 0;
+        const rl = idx - ct * exports.CENTER2_RL_STATES;
+        const d = pruning[idx] + 1;
+        for (let m = 0; m < exports.CENTER2_SEARCH_MOVES.length; m++) {
+            const next = ctMove[ct * nMoves + m] * exports.CENTER2_RL_STATES + rlMove[rl * nMoves + m];
+            if (pruning[next] === 0xff) {
+                pruning[next] = d;
+                queue[tail++] = next;
+            }
+        }
+    }
+    return { ctMove, pruning, goalCt };
 }
 // The reference's cancellation rule (ckmv over move2std): skip the same base
 // move, or the same axis-class when the previous move's standard index is
@@ -434,24 +579,24 @@ function buildWingMoveMaps() {
 // ---------------------------------------------------------------------------
 // Verification gates
 // ---------------------------------------------------------------------------
-function verifyCenter2(tables) {
+function verifyCenter2(tables, pruning = tables.pruning, moves = exports.CENTER2_SEARCH_MOVES) {
     const errors = [];
     for (const rl of exports.CENTER2_GOAL_RL) {
-        if (tables.pruning[rl] !== 0) {
+        if (pruning[rl] !== 0) {
             errors.push(`Goal rl ${rl} must have pruning 0.`);
         }
     }
     let maxDepth = 0;
     for (let idx = 0; idx < exports.CENTER2_STATES; idx++) {
-        const d = tables.pruning[idx];
+        const d = pruning[idx];
         if (d > maxDepth)
             maxDepth = d;
         const ct = Math.floor(idx / exports.CENTER2_RL_STATES);
         const rl = idx % exports.CENTER2_RL_STATES;
-        for (let m = 0; m < exports.CENTER2_SEARCH_MOVES.length; m++) {
+        for (let m = 0; m < moves.length; m++) {
             const nc = tables.ctMove[ct * exports.CENTER2_MOVES.length + m];
             const nr = tables.rlMove[rl * exports.CENTER2_MOVES.length + m];
-            const nd = tables.pruning[nc * exports.CENTER2_RL_STATES + nr];
+            const nd = pruning[nc * exports.CENTER2_RL_STATES + nr];
             if (nd < d - 1 || nd > d + 1) {
                 errors.push(`Pruning inconsistency at ${idx} move ${exports.CENTER2_MOVES[m]}: ${d} -> ${nd}.`);
                 break;

package/dist-cjs/puzzles/cube4/reduction/edge3.js

@@ -28,6 +28,7 @@ exports.getSymTables = getSymTables;
 exports.buildSymTables = buildSymTables;
 exports.getMvSymFrom = getMvSymFrom;
 exports.generateEdge3Tables = generateEdge3Tables;
+exports.unpackEdge3Distances = unpackEdge3Distances;
 exports.edge3DistanceLookup = edge3DistanceLookup;
 exports.__edge3TestHooks = __edge3TestHooks;
 exports.verifyEdge3 = verifyEdge3;
@@ -479,8 +480,23 @@ function generateEdge3Tables(maxDepthCap = -1) {
         frontier = next;
         depth++;
     }
-    const distanceOfEdge = edge3DistanceLookup(distances);
-    return { distances, distanceOfEdge };
+    const unpacked = unpackEdge3Distances(distances);
+    const distanceOfEdge = edge3DistanceLookup(unpacked);
+    return { distances: unpacked, distanceOfEdge };
+}
+/**
+ * Unpack 4-bit nibble-packed distances into a byte-expanded Uint8Array (1 byte per state).
+ */
+function unpackEdge3Distances(packed) {
+    if (packed.length >= exports.EDGE3_TOTAL)
+        return packed;
+    const unpacked = new Uint8Array(exports.EDGE3_TOTAL);
+    for (let i = 0; i < packed.length; i++) {
+        const b = packed[i];
+        unpacked[i << 1] = b & 0x0f;
+        unpacked[(i << 1) | 1] = b >> 4;
+    }
+    return unpacked;
 }
 /**
  * The distance lookup over a loaded distances buffer: builds the sym
@@ -491,9 +507,12 @@ function edge3DistanceLookup(distances) {
     const t = symTables ?? buildSymTables();
     const { sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto } = t;
     const identity = Uint8Array.from({ length: 12 }, (_, i) => i);
+    const isUnpacked = distances.length >= exports.EDGE3_TOTAL;
     return (e) => {
         const std = (0, pairing_coordinate_js_1.normalizePairingState)(e, identity).edge;
         const idx = getMvSymFrom(std, identity, 20, sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto) >> 3;
+        if (isUnpacked)
+            return distances[idx];
         return (distances[idx >> 1] >> ((idx & 1) * 4)) & 0x0f;
     };
 }
@@ -511,8 +530,10 @@ function verifyEdge3(tables) {
         errors.push("Solved state must have distance 0.");
     }
     let seen = 0;
+    const isUnpacked = tables.distances.length >= exports.EDGE3_TOTAL;
     for (let i = 0; i < exports.EDGE3_TOTAL; i++) {
-        if (((tables.distances[i >> 1] >> ((i & 1) * 4)) & 0x0f) !== 0x0f)
+        const d = isUnpacked ? tables.distances[i] : ((tables.distances[i >> 1] >> ((i & 1) * 4)) & 0x0f);
+        if (d !== 0x0f)
             seen++;
     }
     if (seen !== exports.EDGE3_TOTAL) {