@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist-cjs/puzzles/shared/compressed-fetch.js

@@ -5,8 +5,19 @@
 //
 // Node never uses this module: node-loader.ts reads the .bin files directly
 // from the filesystem.
+//
+// Integrity: callers can pass the manifest's expectations — sha256 + byte
+// length (4x4 manifests) or the FNV-1a32 checksums the older manifests ship
+// — and every check runs on the FINAL (decompressed) bytes, i.e. exactly the
+// .bin payload: identical checks to the node loaders. A payload served by
+// the Cache API that fails verification is purged (`cache.delete`) and
+// re-downloaded exactly once, so a corrupt cache entry heals instead of
+// failing every load forever.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchTableBuffer = fetchTableBuffer;
+exports.fnv1a32 = fnv1a32;
+exports.sha256Hex = sha256Hex;
+exports.sha256HexJs = sha256HexJs;
 // DecompressionStream only guarantees "gzip"/"deflate"; "br" support varies,
 // so probe once and never attempt formats the runtime cannot decompress.
 const SUPPORTED_FORMATS = (() => {
@@ -26,46 +37,233 @@ const SUPPORTED_FORMATS = (() => {
 })();
 async function fetchTableBuffer(baseUrl, dir, file, options = {}) {
     const urlFor = (name) => `${baseUrl}/${dir}/${name}`;
-    const cachedFetch = options.cacheName === undefined ? undefined : makeCachedFetch(options.cacheName);
-    if (options.compressed !== false && SUPPORTED_FORMATS.length > 0) {
-        for (const [suffix, format] of SUPPORTED_FORMATS) {
-            try {
-                const response = await (cachedFetch ? cachedFetch(urlFor(`${file}.${suffix}`)) : fetch(urlFor(`${file}.${suffix}`)));
-                if (response.ok && response.body) {
-                    const stream = response.body.pipeThrough(new DecompressionStream(format));
-                    return await new Response(stream).arrayBuffer();
+    const canonicalUrl = urlFor(file);
+    const cache = options.cacheName === undefined ? undefined : makeCacheChannel(options.cacheName);
+    // Cache API URLs that served the current download attempt; when the
+    // payload fails verification they are purged before the single retry.
+    let servedFromCache = [];
+    const get = async (url) => {
+        if (!cache)
+            return fetch(url);
+        const { response, fromCache } = await cache.fetch(url);
+        if (fromCache)
+            servedFromCache.push(url);
+        return response;
+    };
+    const download = async () => {
+        servedFromCache = [];
+        if (options.compressed !== false && SUPPORTED_FORMATS.length > 0) {
+            for (const [suffix, format] of SUPPORTED_FORMATS) {
+                try {
+                    const response = await get(urlFor(`${file}.${suffix}`));
+                    if (response.ok && response.body) {
+                        const stream = response.body.pipeThrough(new DecompressionStream(format));
+                        return await new Response(stream).arrayBuffer();
+                    }
+                }
+                catch {
+                    // try the next candidate
                 }
             }
-            catch {
-                // try the next candidate
-            }
         }
+        const response = await get(canonicalUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to load table ${canonicalUrl}: ${response.status} ${response.statusText}` +
+                (options.expectedBytes !== undefined ? ` (expected ${options.expectedBytes} bytes)` : ""));
+        }
+        return response.arrayBuffer();
+    };
+    let buffer = await download();
+    try {
+        await verifyTableBuffer(buffer, canonicalUrl, options);
     }
-    const response = await (cachedFetch ? cachedFetch(urlFor(file)) : fetch(urlFor(file)));
-    if (!response.ok) {
-        throw new Error(`Failed to load ${file}: ${response.status} ${response.statusText}`);
+    catch (error) {
+        // A corrupt Cache API entry fails every load until it is purged: delete
+        // the cached copies that served this attempt and re-download exactly
+        // ONCE. A second verification failure (or a payload that never came
+        // from the cache) propagates unchanged.
+        if (!cache || servedFromCache.length === 0)
+            throw error;
+        await cache.purge(servedFromCache);
+        buffer = await download();
+        await verifyTableBuffer(buffer, canonicalUrl, options);
     }
-    return response.arrayBuffer();
+    return buffer;
 }
-function makeCachedFetch(cacheName) {
-    return async (url) => {
-        if (typeof caches === "undefined") {
-            return fetch(url);
+/**
+ * Verify the downloaded payload against the manifest: byte length first
+ * (clearer truncation messages), then sha256 / FNV-1a. Runs on the
+ * decompressed bytes, so .br/.gz variants and the raw file are checked
+ * identically — and identically to the node loaders.
+ */
+async function verifyTableBuffer(buffer, url, options) {
+    if (options.expectedBytes !== undefined && buffer.byteLength !== options.expectedBytes) {
+        throw new Error(`Table size mismatch: ${url} (expected ${options.expectedBytes} bytes, got ${buffer.byteLength})`);
+    }
+    if (options.expectedSha256 !== undefined) {
+        const actual = await sha256Hex(buffer);
+        if (actual !== options.expectedSha256) {
+            throw new Error(`Table checksum mismatch: ${url} (expected sha256 ${options.expectedSha256}, got ${actual}, ${buffer.byteLength} bytes)`);
         }
-        try {
-            const cache = await caches.open(cacheName);
-            const cached = await cache.match(url);
-            if (cached) {
-                return cached;
+    }
+    if (options.expectedFnv1a !== undefined) {
+        const spec = options.expectedFnv1a;
+        const actual = fnv1a32(buffer, spec.elementSize, spec.signed ?? false);
+        if (actual !== spec.value) {
+            throw new Error(`Table checksum mismatch: ${url} (expected fnv1a ${spec.value}, got ${actual}, ${buffer.byteLength} bytes)`);
+        }
+    }
+}
+/**
+ * FNV-1a (32-bit) over the elements decoded from a wire buffer: the browser
+ * twin of the node loaders' `checksum(values)` (imul multiply, `>>> 0`
+ * result). `elementSize` mirrors each loader's decoding of the manifest
+ * checksum — see `ExpectedFnv1a`.
+ */
+function fnv1a32(buffer, elementSize, signed = false) {
+    if (buffer.byteLength % elementSize !== 0) {
+        throw new Error(`FNV-1a input length ${buffer.byteLength} is not a multiple of ${elementSize}-byte elements`);
+    }
+    let hash = 0x811c9dc5;
+    const view = new DataView(buffer);
+    const count = buffer.byteLength / elementSize;
+    for (let index = 0; index < count; index += 1) {
+        let value;
+        if (elementSize === 1)
+            value = signed ? view.getInt8(index) : view.getUint8(index);
+        else if (elementSize === 2)
+            value = view.getUint16(index * 2, true);
+        else
+            value = view.getInt32(index * 4, true);
+        hash ^= value;
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/** sha256 hex of a buffer; WebCrypto when available, portable JS fallback otherwise. */
+async function sha256Hex(buffer) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle) {
+        const digest = await subtle.digest("SHA-256", buffer);
+        const bytes = new Uint8Array(digest);
+        let hex = "";
+        for (let i = 0; i < bytes.length; i++)
+            hex += bytes[i].toString(16).padStart(2, "0");
+        return hex;
+    }
+    // Insecure contexts expose no SubtleCrypto; keep integrity checks working
+    // with a self-contained implementation instead of skipping verification.
+    return sha256HexJs(buffer);
+}
+// FIPS 180-4 SHA-256, used only when `crypto.subtle` is unavailable.
+const SHA256_K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+function sha256HexJs(buffer) {
+    const bytes = new Uint8Array(buffer);
+    const paddedLength = (bytes.length + 72) & ~63;
+    const data = new Uint8Array(paddedLength);
+    data.set(bytes);
+    data[bytes.length] = 0x80;
+    const view = new DataView(data.buffer);
+    view.setUint32(paddedLength - 8, Math.floor(bytes.length / 0x20000000));
+    view.setUint32(paddedLength - 4, (bytes.length << 3) >>> 0);
+    let h0 = 0x6a09e667;
+    let h1 = 0xbb67ae85;
+    let h2 = 0x3c6ef372;
+    let h3 = 0xa54ff53a;
+    let h4 = 0x510e527f;
+    let h5 = 0x9b05688c;
+    let h6 = 0x1f83d9ab;
+    let h7 = 0x5be0cd19;
+    const w = new Int32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let i = 0; i < 16; i += 1)
+            w[i] = view.getInt32(offset + i * 4);
+        for (let i = 16; i < 64; i += 1) {
+            const w15 = w[i - 15];
+            const w2 = w[i - 2];
+            const s0 = ((w15 >>> 7) | (w15 << 25)) ^ ((w15 >>> 18) | (w15 << 14)) ^ (w15 >>> 3);
+            const s1 = ((w2 >>> 17) | (w2 << 15)) ^ ((w2 >>> 19) | (w2 << 13)) ^ (w2 >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        let f = h5;
+        let g = h6;
+        let h = h7;
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (h + s1 + ch + SHA256_K[i] + w[i]) | 0;
+            const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + maj) | 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+        h5 = (h5 + f) | 0;
+        h6 = (h6 + g) | 0;
+        h7 = (h7 + h) | 0;
+    }
+    return [h0, h1, h2, h3, h4, h5, h6, h7]
+        .map((x) => (x >>> 0).toString(16).padStart(8, "0"))
+        .join("");
+}
+function makeCacheChannel(cacheName) {
+    if (typeof caches === "undefined") {
+        return undefined;
+    }
+    return {
+        async fetch(url) {
+            try {
+                const cache = await caches.open(cacheName);
+                const cached = await cache.match(url);
+                if (cached) {
+                    return { response: cached, fromCache: true };
+                }
+                const response = await fetch(url);
+                if (response.ok) {
+                    await cache.put(url, response.clone());
+                }
+                return { response, fromCache: false };
             }
-            const response = await fetch(url);
-            if (response.ok) {
-                await cache.put(url, response.clone());
+            catch {
+                return { response: await fetch(url), fromCache: false };
+            }
+        },
+        async purge(urls) {
+            try {
+                const cache = await caches.open(cacheName);
+                for (const url of urls) {
+                    await cache.delete(url);
+                }
+            }
+            catch {
+                // Best effort: a failed purge must not mask the verification error
+                // that triggered it — the load still fails loudly either way.
             }
-            return response;
-        }
-        catch {
-            return fetch(url);
         }
     };
 }

package/dist-cjs/puzzles/shared/load-once.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadOnce = loadOnce;
+function loadOnce(slot, load) {
+    if (!slot.promise) {
+        const wrapped = load().catch((error) => {
+            if (slot.promise === wrapped)
+                slot.promise = undefined;
+            throw error;
+        });
+        slot.promise = wrapped;
+    }
+    return slot.promise;
+}

package/dist-cjs/puzzles/skewb/solver/browser-loader.js

@@ -6,25 +6,44 @@ exports.loadBrowserTables = loadBrowserTables;
 const table_metadata_js_1 = require("./table-metadata.js");
 const compressed_fetch_js_1 = require("../../shared/compressed-fetch.js");
 const TABLES_DIR = "puzzles/skewb/solver/generated";
+const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
 let cachedBrowserTables;
+let cachedBrowserTablesPromise;
 function getCachedBrowserTables() {
     return cachedBrowserTables;
 }
 function clearCachedBrowserTables() {
     cachedBrowserTables = undefined;
+    cachedBrowserTablesPromise = undefined;
 }
 async function loadBrowserTables(baseUrl) {
     if (cachedBrowserTables) {
         return cachedBrowserTables;
     }
+    if (cachedBrowserTablesPromise) {
+        // One shared in-flight promise: concurrent calls trigger exactly one
+        // fetch pass (dedup).
+        return cachedBrowserTablesPromise;
+    }
+    const promise = fetchTables(baseUrl);
+    cachedBrowserTablesPromise = promise;
+    promise.then(() => { }, () => {
+        // A failed load must not poison the dedup slot: purge the rejected
+        // promise so a later call retries from scratch.
+        if (cachedBrowserTablesPromise === promise)
+            cachedBrowserTablesPromise = undefined;
+    });
+    return promise;
+}
+async function fetchTables(baseUrl) {
     const resolved = resolveBaseUrl(baseUrl);
     const manifest = await fetchManifest(resolved);
     const [permTable, orientTable, centersTable, helpers, policy] = await Promise.all([
-        fetchUint16Table(resolved, manifest.files.permutationTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.permutationTable.entries),
-        fetchUint16Table(resolved, manifest.files.orientationTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.orientationTable.entries),
-        fetchUint16Table(resolved, manifest.files.centersTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.centersTable.entries),
-        fetchUint8Table(resolved, manifest.files.helpers, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.helpers.entries),
-        fetchUint8Table(resolved, manifest.files.policyTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.policyTable.entries)
+        fetchUint16Table(resolved, manifest.files.permutationTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.permutationTable),
+        fetchUint16Table(resolved, manifest.files.orientationTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.orientationTable),
+        fetchUint16Table(resolved, manifest.files.centersTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.centersTable),
+        fetchUint8Table(resolved, manifest.files.helpers, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.helpers),
+        fetchUint8Table(resolved, manifest.files.policyTable, table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.policyTable)
     ]);
     const helpersOffset = table_metadata_js_1.SKEWB_SOLVER_TABLE_METADATA.helpers;
     const evenCenterRank = new Uint16Array(helpersOffset.evenCenterRankBytes / 2);
@@ -70,22 +89,31 @@ async function fetchManifest(baseUrl) {
     }
     return await response.json();
 }
-async function fetchUint16Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries * 2) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
-    const values = new Uint16Array(expectedEntries);
+/**
+ * Fetch + verify with the SAME checks as node-loader.ts: byte length from
+ * the manifest entries, FNV-1a checksum against the table-metadata
+ * constants (the values node asserts against).
+ */
+async function fetchUint16Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries * 2,
+        expectedFnv1a: { value: meta.checksum, elementSize: 2 }
+    });
+    const values = new Uint16Array(entry.entries);
     const view = new DataView(buffer);
     for (let i = 0; i < values.length; i++) {
         values[i] = view.getUint16(i * 2, true);
     }
     return values;
 }
-async function fetchUint8Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
+async function fetchUint8Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries,
+        expectedFnv1a: { value: meta.checksum, elementSize: 1 }
+    });
     return new Uint8Array(buffer);
 }

package/dist-cjs/puzzles/skewb/solver/generated-assets.js

@@ -35,7 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadGeneratedSkewbSolverTables = loadGeneratedSkewbSolverTables;
 const browser_loader_js_1 = require("./browser-loader.js");
-let cachedTables;
+const load_once_js_1 = require("../../shared/load-once.js");
+// One shared in-flight promise for the node fs load (same pattern as
+// cube3/solver/generated-assets.ts): the previous `cached ??= await …` raced —
+// concurrent callers interleaving on the await both ran `loadNodeTables()`
+// (two filesystem reads, last assignment wins). On rejection the slot is
+// purged so the next call can retry.
+const nodeTablesSlot = { promise: undefined };
 function isBrowser() {
     return typeof self !== "undefined";
 }
@@ -48,8 +54,7 @@ async function loadGeneratedSkewbSolverTables() {
             "In browser environments, call `initializeScrambler(baseUrl)` " +
             "before generating scrambles.");
     }
-    cachedTables ??= await loadNodeTables();
-    return cachedTables;
+    return (0, load_once_js_1.loadOnce)(nodeTablesSlot, loadNodeTables);
 }
 async function loadNodeTables() {
     const loader = await Promise.resolve().then(() => __importStar(require(

package/dist-cjs/puzzles/sq1/solver/browser-loader.js

@@ -6,29 +6,48 @@ exports.loadBrowserTables = loadBrowserTables;
 const table_metadata_js_1 = require("./table-metadata.js");
 const compressed_fetch_js_1 = require("../../shared/compressed-fetch.js");
 const TABLES_DIR = "puzzles/sq1/solver/generated";
+const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
 let cachedBrowserTables;
+let cachedBrowserTablesPromise;
 function getCachedBrowserTables() {
     return cachedBrowserTables;
 }
 function clearCachedBrowserTables() {
     cachedBrowserTables = undefined;
+    cachedBrowserTablesPromise = undefined;
 }
 async function loadBrowserTables(baseUrl) {
     if (cachedBrowserTables) {
         return cachedBrowserTables;
     }
+    if (cachedBrowserTablesPromise) {
+        // One shared in-flight promise: concurrent calls trigger exactly one
+        // fetch pass (dedup).
+        return cachedBrowserTablesPromise;
+    }
+    const promise = fetchTables(baseUrl);
+    cachedBrowserTablesPromise = promise;
+    promise.then(() => { }, () => {
+        // A failed load must not poison the dedup slot: purge the rejected
+        // promise so a later call retries from scratch.
+        if (cachedBrowserTablesPromise === promise)
+            cachedBrowserTablesPromise = undefined;
+    });
+    return promise;
+}
+async function fetchTables(baseUrl) {
     const resolved = resolveBaseUrl(baseUrl);
     const manifest = await fetchManifest(resolved);
     const [shapeIdx, shapePrun, shapeTopMove, shapeBottomMove, shapeTwistMove, squareTwistMove, squareTopMove, squareBottomMove, squarePrun] = await Promise.all([
-        fetchInt32Table(resolved, manifest.files.shapeIdx, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeIdx.entries),
-        fetchInt8Table(resolved, manifest.files.shapePrun, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapePrun.entries),
-        fetchInt32Table(resolved, manifest.files.shapeTopMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeTopMove.entries),
-        fetchInt32Table(resolved, manifest.files.shapeBottomMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeBottomMove.entries),
-        fetchInt32Table(resolved, manifest.files.shapeTwistMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeTwistMove.entries),
-        fetchUint16Table(resolved, manifest.files.squareTwistMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squareTwistMove.entries),
-        fetchUint16Table(resolved, manifest.files.squareTopMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squareTopMove.entries),
-        fetchUint16Table(resolved, manifest.files.squareBottomMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squareBottomMove.entries),
-        fetchInt8Table(resolved, manifest.files.squarePrun, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squarePrun.entries),
+        fetchInt32Table(resolved, manifest.files.shapeIdx, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeIdx),
+        fetchInt8Table(resolved, manifest.files.shapePrun, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapePrun),
+        fetchInt32Table(resolved, manifest.files.shapeTopMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeTopMove),
+        fetchInt32Table(resolved, manifest.files.shapeBottomMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeBottomMove),
+        fetchInt32Table(resolved, manifest.files.shapeTwistMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.shapeTwistMove),
+        fetchUint16Table(resolved, manifest.files.squareTwistMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squareTwistMove),
+        fetchUint16Table(resolved, manifest.files.squareTopMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squareTopMove),
+        fetchUint16Table(resolved, manifest.files.squareBottomMove, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squareBottomMove),
+        fetchInt8Table(resolved, manifest.files.squarePrun, table_metadata_js_1.SQ1_SOLVER_TABLE_METADATA.squarePrun),
     ]);
     cachedBrowserTables = {
         shapeIdx,
@@ -64,34 +83,47 @@ async function fetchManifest(baseUrl) {
     }
     return (await response.json());
 }
-async function fetchInt32Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries * 4) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
-    const values = new Int32Array(expectedEntries);
+/**
+ * Fetch + verify with the SAME checks as node-loader.ts: byte length from
+ * the manifest entries, FNV-1a checksum against the table-metadata
+ * constants (node skips the checksum when that constant is 0 = "unchecked";
+ * the browser mirrors the guard).
+ */
+async function fetchInt32Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries * 4,
+        ...(meta.checksum !== 0 ? { expectedFnv1a: { value: meta.checksum, elementSize: 4 } } : {})
+    });
+    const values = new Int32Array(entry.entries);
     const view = new DataView(buffer);
     for (let i = 0; i < values.length; i++) {
         values[i] = view.getInt32(i * 4, true);
     }
     return values;
 }
-async function fetchUint16Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries * 2) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
-    const values = new Uint16Array(expectedEntries);
+async function fetchUint16Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries * 2,
+        ...(meta.checksum !== 0 ? { expectedFnv1a: { value: meta.checksum, elementSize: 2 } } : {})
+    });
+    const values = new Uint16Array(entry.entries);
     const view = new DataView(buffer);
     for (let i = 0; i < values.length; i++) {
         values[i] = view.getUint16(i * 2, true);
     }
     return values;
 }
-async function fetchInt8Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
+async function fetchInt8Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries,
+        // Square-1's int8 tables hash SIGNED values in node (Int8Array).
+        ...(meta.checksum !== 0 ? { expectedFnv1a: { value: meta.checksum, elementSize: 1, signed: true } } : {})
+    });
     return new Int8Array(buffer);
 }

package/docs/development.md

@@ -9,25 +9,37 @@ pnpm test
 pnpm build
 pnpm package:check
 pnpm verify
+pnpm verify:scrambles
+node --import tsx scripts/uniformity-444.ts --n=500
 ```
 
 - `pnpm lint`: TypeScript type check without emitting files.
-- `pnpm test`: Node test runner with `tsx`.
+- `pnpm test`: Node test runner with `tsx`. Targeted suites exist per puzzle (`pnpm test:cube2`, `test:cube3`, `test:cube4`, …) and the runner also accepts file arguments (`pnpm test test/cube4.test.ts`).
 - `pnpm build`: ESM build, CJS build, CJS package marker, generated asset copy.
 - `pnpm package:check`: local package and consumption checks.
-- `pnpm verify`: full local verification for normal development.
+- `pnpm verify`: full local verification for normal development — lint, tests, build, **all** solver-table checksum checks (cube2/cube3/pyraminx/skewb/sq1 and the 4x4 `cube4:{center1,center2,center3,edge3,hc}:tables:check`), then the package checks.
+- `pnpm verify:scrambles [--count N] [events...]`: consistency harness. Generates scrambles with `skipValidation: true` and replays them **independently** — the target is re-sampled from the seed by the puzzle's own sampler (never derived from the emitted scramble, so the check cannot be tautological) and the solution must reach a state where the real `isSolved` predicate holds. Any mismatch exits 1. Events: `222 333 pymx skwb fto 444` (444 defaults to 25 generations).
+- `node --import tsx scripts/uniformity-444.ts [--n=500] [--concurrency=4] [--threshold=…]`: χ² uniformity bench for the 4x4 pipeline over the state it **reaches** (`apply(solved, moves)`), on a fixed deterministic seed corpus: center colors per slot, wing/corner pieces per slot, twist, corner×wing parity quadrants, and joint (parity × center class / twist) bins. Prints a χ²/p-value table and exits 1 if any family falls below the threshold. P-values are reference values of a fixed corpus, not classical significance — see the interpretation notes in the script header. The lightweight companion runs inside `pnpm test` (`test/cube4-uniformity.test.ts`: direct sampler N=20,000 + full pipeline N=40 with structural checks).
 
-## Solver Tables
+## Seeded generation
+
+`{ seed }` makes generation reproducible: the seed fully determines the sampled target state (a seeded PRNG in `src/random/`), and the scramblers emit a scramble for exactly that state — for `444` the replay is validated against the sample on every generation. With the same seed **and** the same options the output is deterministic: search budgets are node counters, not wall deadlines (the only wall-clock code in the 4x4 path is a pair of hang guards that never bound an observed solve). Batch APIs and the CLI derive per-item seeds of the form `seed:index` (`generateScrambles("333", 5, { seed: "s" })` and `--seed s --count 5` both use `s:0` … `s:4`), so items are independent and earlier items do not change when the count grows.
 
-3x3 solver tables are committed as generated binary assets under the cube3 solver generated directory.
+## Solver Tables
 
-Regenerate them only when coordinates, moves, pruning logic, or table encoding changes:
+Solver tables are committed as generated binary assets per puzzle — regenerate them only when coordinates, moves, pruning logic, or table encoding changes:
 
 ```sh
-pnpm cube3:tables
-pnpm cube3:tables:check
+pnpm cube3:tables && pnpm cube3:tables:check        # 3x3 (also: cube2, pyraminx, skewb, sq1)
+pnpm cube4:center1:tables && pnpm cube4:center1:tables:check   # 4x4 reduction, phase by phase
+pnpm cube4:center2:tables && pnpm cube4:center2:tables:check
+pnpm cube4:center3:tables && pnpm cube4:center3:tables:check
+pnpm cube4:edge3:tables && pnpm cube4:edge3:tables:check       # pairing BFS (C++ generator)
+pnpm cube4:hc:tables && pnpm cube4:hc:tables:check             # hc PDB
 ```
 
+Each `:tables:check` verifies the committed `manifest.json` checksums and fails when a `.bin` has drifted; `pnpm verify` runs them all. After regenerating, `pnpm tables:web:sync` refreshes the demo site copies (with `.gz`/`.br` variants).
+
 The build copies those assets into both `dist` and `dist-cjs`. Package checks fail if required generated assets are missing from the packed output.
 
 ## Public API Expectations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubingcenter/scrambler",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Extensible scramble generation toolkit for CubingCenter projects.",
   "type": "module",
   "license": "MIT",
@@ -72,7 +72,7 @@
     "test:watch": "node --test --watch --import tsx",
     "lint": "tsc -p tsconfig.json --noEmit",
     "package:check": "pnpm build && node scripts/check-package.cjs",
-    "verify": "pnpm lint && pnpm test && pnpm build && pnpm cube3:tables:check && pnpm cube2:tables:check && pnpm pyraminx:tables:check && pnpm skewb:tables:check && pnpm sq1:tables:check && pnpm package:check",
+    "verify": "pnpm lint && pnpm test && pnpm build && pnpm cube3:tables:check && pnpm cube2:tables:check && pnpm pyraminx:tables:check && pnpm skewb:tables:check && pnpm sq1:tables:check && pnpm cube4:center1:tables:check && pnpm cube4:center2:tables:check && pnpm cube4:center3:tables:check && pnpm cube4:edge3:tables:check && pnpm cube4:hc:tables:check && pnpm package:check",
     "dev": "tsx src/cli/index.ts",
     "cube3:tables": "node --import tsx scripts/generate-cube3-solver-tables.ts",
     "cube3:tables:check": "node --import tsx scripts/check-cube3-solver-tables.ts",
@@ -103,6 +103,7 @@
     "bench:skewb": "node --import tsx bench-skewb.ts",
     "bench:pyraminx": "node --import tsx bench-pyraminx.ts",
     "bench:phases": "node --import tsx bench-phases.ts",
-    "bench:uniformity": "node --import tsx bench-uniformity.ts"
+    "bench:uniformity": "node --import tsx bench-uniformity.ts",
+    "bench:cube4-pool": "node --import tsx scripts/bench-444-pool.ts"
   }
 }