@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist-cjs/puzzles/cube4/worker-pool.js

@@ -0,0 +1,447 @@
+"use strict";
+/**
+ * Worker pool for 4x4 random-state scrambles (Node.js `worker_threads`).
+ *
+ * Why: generation is CPU-bound in a single event loop — a `Promise.all`
+ * batch of N scrambles does not scale. This pool spreads one batch across
+ * N threads so `generateScrambles`-style batches grow roughly linearly
+ * with core count, while keeping the (seed, complete-options) → moves
+ * contract byte-identical to the inline path: tasks forward the FULL
+ * options object verbatim and `worker.ts` calls the very same
+ * `generateCube4Scramble`.
+ *
+ * Lifecycle:
+ *  - Lazy spawn: threads are created on demand (one per queued job, up to
+ *    `size`), never in the constructor. A cold first generation pays for
+ *    table loading (≈37 MB) per spawned thread, once; the thread then
+ *    reuses its tables for every later job (per-thread promise cache inside
+ *    `scrambler.ts`).
+ *  - Idle threads are `unref()`d, so a pool that is never terminated does
+ *    not keep the process alive; in-flight jobs `ref()` their thread so an
+ *    awaited batch always completes.
+ *  - One task in flight per thread; extra tasks queue FIFO.
+ *  - `terminate()` rejects everything queued/in-flight with
+ *    `Cube4WorkerPoolClosedError` and joins all threads — after it
+ *    resolves there are no open handles.
+ *
+ * Failure: a crashed thread only fails ITS in-flight task and is dropped
+ * from the pool; the next dispatch spawns a fresh thread (which reloads
+ * tables). Typed solver errors from inside a worker arrive as an `Error`
+ * with the original `name`, `message` and `code` preserved (see
+ * `worker-protocol.ts`).
+ *
+ * Dual-build note: this file intentionally contains no bare `import.meta`
+ * (it must also compile in the CommonJS build that `index.ts` is part of).
+ * The worker entry is located from `__filename` (CJS) or this module's top
+ * stack frame (ESM), and `dist-cjs` falls back to the sibling ESM tree,
+ * which always ships `worker.js`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cube4WorkerPool = exports.Cube4WorkerPoolClosedError = void 0;
+exports.deriveBatchCube4Options = deriveBatchCube4Options;
+exports.getDefaultCube4WorkerPool = getDefaultCube4WorkerPool;
+exports.closeDefaultCube4WorkerPool = closeDefaultCube4WorkerPool;
+exports.generateCube4ScrambleBatch = generateCube4ScrambleBatch;
+const errors_js_1 = require("../../core/errors.js");
+const scrambler_js_1 = require("./scrambler.js");
+const worker_protocol_js_1 = require("./worker-protocol.js");
+/** Typed rejection used for post-terminate operations and shutdown itself. */
+class Cube4WorkerPoolClosedError extends Error {
+    code = "cube4-pool-closed";
+    constructor(action = "operation") {
+        super(`[cube4] worker pool is closed (${action} rejected).`);
+        this.name = "Cube4WorkerPoolClosedError";
+    }
+}
+exports.Cube4WorkerPoolClosedError = Cube4WorkerPoolClosedError;
+/**
+ * Batch seed derivation — byte-for-byte the semantics of
+ * `deriveBatchScrambleOptions` in `src/core/api.ts` (`generateScrambles`):
+ * with a `seed` and `count > 1`, item i uses `${seed}:${i}`; otherwise the
+ * options pass through untouched. Exported so tests can assert the pool
+ * batch equals the sequential/core batch for the same inputs.
+ */
+function deriveBatchCube4Options(options, index, count) {
+    if (count === 1 || options.seed === undefined) {
+        return options;
+    }
+    return { ...options, seed: `${options.seed}:${index}` };
+}
+const TSX_ARGV = ["--import", "tsx"];
+/**
+ * Locates this module's own file (extension included), dual-build safe:
+ * CJS knows it as `__filename`; in ESM we take the top stack frame, which
+ * V8 reports as the module URL (`file://…`) of `worker-pool.ts|js` — the
+ * path is correct whether or not source maps are enabled (they only move
+ * line/column, never the module URL).
+ */
+function resolveCurrentModuleLocation() {
+    if (typeof __filename === "string" && __filename.length > 0) {
+        return __filename;
+    }
+    const holder = new Error();
+    Error.captureStackTrace?.(holder);
+    const raw = holder.stack;
+    const candidates = [];
+    if (typeof raw === "string") {
+        for (const line of raw.split("\n")) {
+            const match = /^\s*at (?:(?:.*?\s+\())?(.+?):\d+:\d+\)?$/.exec(line.trim());
+            if (match && match[1] !== undefined)
+                candidates.push(match[1]);
+        }
+    }
+    else if (Array.isArray(raw)) {
+        for (const frame of raw) {
+            const name = frame?.getFileName?.();
+            if (typeof name === "string")
+                candidates.push(name);
+        }
+    }
+    for (const candidate of candidates) {
+        if (candidate.includes("worker-pool.")) {
+            return candidate.startsWith("file://") ? fileUrlToPath(candidate) : candidate;
+        }
+    }
+    return undefined;
+}
+/** Minimal `file://` → path conversion (global `URL`, no node:url import). */
+function fileUrlToPath(value) {
+    try {
+        let pathname = decodeURIComponent(new URL(value).pathname);
+        // Windows file URLs keep a leading slash before the drive letter.
+        if (/^\/[A-Za-z]:/.test(pathname))
+            pathname = pathname.slice(1);
+        return pathname;
+    }
+    catch {
+        return value.replace(/^file:\/\//, "");
+    }
+}
+class Cube4WorkerPool {
+    workers = [];
+    queue = [];
+    explicitSize;
+    workerPathOption;
+    sizePromise;
+    /** Last resolved size, kept sync-readable for the pump's headroom check. */
+    sizeSync = 0;
+    pumping;
+    terminatePromise;
+    nextId = 0;
+    terminated = false;
+    constructor(options = {}) {
+        if (options.size !== undefined) {
+            if (!Number.isInteger(options.size) || options.size < 1) {
+                throw new RangeError(`[cube4] pool size must be an integer >= 1 (got ${options.size}).`);
+            }
+            this.sizeSync = options.size;
+        }
+        this.explicitSize = options.size;
+        this.workerPathOption = options.workerPath;
+    }
+    /** Maximum thread count (resolves the default lazily on first use). */
+    get size() {
+        return this.resolveSize();
+    }
+    /** Threads spawned so far (lazily grown; 0 before the first job). */
+    get workerCount() {
+        return this.workers.length;
+    }
+    get queuedCount() {
+        return this.queue.length;
+    }
+    get busyCount() {
+        return this.workers.reduce((n, rec) => n + (rec.task !== null ? 1 : 0), 0);
+    }
+    get closed() {
+        return this.terminated;
+    }
+    /**
+     * Generates one scramble on an available thread. Rejects (typed) if the
+     * pool is closed, the worker crashes, the options cannot be
+     * structured-cloned, or generation fails inside the worker.
+     */
+    generate(options = {}) {
+        if (this.terminated) {
+            return Promise.reject(new Cube4WorkerPoolClosedError("generate"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.queue.push({ id, options, resolve, reject });
+            this.pump();
+        });
+    }
+    /**
+     * Batch generation with EXACTLY the seed derivation of core
+     * `generateScrambles` (see `deriveBatchCube4Options`), so results are
+     * identical — move for move — to the sequential path for the same
+     * inputs. Order of the returned array matches request order regardless
+     * of completion order.
+     */
+    generateBatch(count, options = {}) {
+        if (!Number.isInteger(count) || count < 1) {
+            return Promise.reject(new errors_js_1.InvalidCountError(count));
+        }
+        return Promise.all(Array.from({ length: count }, (_, index) => this.generate(deriveBatchCube4Options(options, index, count))));
+    }
+    /**
+     * Prompt shutdown: rejects queued and in-flight tasks with
+     * `Cube4WorkerPoolClosedError`, terminates every thread and resolves
+     * when none is left. Idempotent.
+     */
+    terminate() {
+        if (this.terminatePromise !== undefined)
+            return this.terminatePromise;
+        this.terminated = true;
+        for (const task of this.queue.splice(0)) {
+            task.reject(new Cube4WorkerPoolClosedError("queued task"));
+        }
+        const records = this.workers.splice(0);
+        const joins = [];
+        for (const rec of records) {
+            if (rec.task !== null) {
+                rec.task.reject(new Cube4WorkerPoolClosedError("in-flight task"));
+                rec.task = null;
+            }
+            joins.push(rec.worker.terminate().then(() => undefined));
+        }
+        this.terminatePromise = Promise.all(joins).then(() => undefined);
+        return this.terminatePromise;
+    }
+    // ── internals ────────────────────────────────────────────────────────
+    resolveSize() {
+        if (this.explicitSize !== undefined)
+            return Promise.resolve(this.explicitSize);
+        this.sizePromise ??= (async () => {
+            try {
+                // @vite-ignore: Node-only; the browser bundle never executes this.
+                const os = await Promise.resolve().then(() => __importStar(require(/* webpackIgnore: true */ /* @vite-ignore */ "node:os")));
+                const parallelism = typeof os.availableParallelism === "function"
+                    ? os.availableParallelism()
+                    : os.cpus().length;
+                this.sizeSync = Math.max(1, parallelism - 1);
+            }
+            catch {
+                this.sizeSync = 4;
+            }
+            return this.sizeSync;
+        })();
+        return this.sizePromise;
+    }
+    /**
+     * Serialised dispatcher: grows the pool (lazy spawn), hands queued jobs
+     * to idle threads, and stops when every thread is busy at capacity.
+     * Re-entry while a spawn is awaited is a no-op — the running loop's
+     * `while` re-checks the queue, and every completion event (`response`,
+     * `crash`) calls `pump()` again.
+     */
+    pump() {
+        if (this.pumping !== undefined || this.terminated)
+            return;
+        this.pumping = this.runPump()
+            .catch(() => undefined) // runPump handles failures per task; belt and braces
+            .finally(() => {
+            this.pumping = undefined;
+            // A task pushed by a microtask that landed between runPump's last
+            // queue check and this finally would have been skipped (pump was
+            // still "running"). Re-pump only when dispatch can make actual
+            // progress — an idle thread or spawn headroom — so tasks parked at
+            // capacity (which a completion event will pump) cannot spin here.
+            if (this.queue.length > 0 && !this.terminated && this.hasDispatchHeadroom()) {
+                this.pump();
+            }
+        });
+    }
+    hasDispatchHeadroom() {
+        if (this.workers.some((rec) => rec.task === null))
+            return true;
+        return this.sizeSync > 0 && this.workers.length < this.sizeSync;
+    }
+    async runPump() {
+        while (!this.terminated && this.queue.length > 0) {
+            const idle = this.workers.find((rec) => rec.task === null);
+            if (idle !== undefined) {
+                this.dispatch(idle, this.queue.shift());
+                continue;
+            }
+            if (this.workers.length < (await this.resolveSize())) {
+                let rec;
+                try {
+                    rec = await this.spawnWorker();
+                }
+                catch (error) {
+                    // Spawning failed (missing entry, bad workerPath, …): fail THIS
+                    // task and keep trying for the rest of the queue.
+                    this.queue.shift()?.reject(error);
+                    continue;
+                }
+                continue; // the fresh thread is idle → dispatched on the next pass
+            }
+            break; // at capacity with every thread busy — wait for a response
+        }
+    }
+    async spawnWorker() {
+        // @vite-ignore: Node-only; never executed in a browser bundle.
+        const { Worker: WorkerCtor } = await Promise.resolve().then(() => __importStar(require(
+        /* webpackIgnore: true */ /* @vite-ignore */ "node:worker_threads")));
+        if (this.terminated)
+            throw new Cube4WorkerPoolClosedError("spawn");
+        const entry = this.resolveWorkerEntry();
+        const worker = new WorkerCtor(entry.path, { execArgv: [...entry.execArgv] });
+        const rec = { worker, task: null };
+        worker.on("message", (response) => {
+            this.handleResponse(rec, response);
+        });
+        worker.on("error", (error) => {
+            this.handleWorkerGone(rec, error);
+        });
+        worker.on("exit", (code) => {
+            this.handleWorkerGone(rec, new Error(`[cube4] worker exited unexpectedly (code ${code}).`));
+        });
+        this.workers.push(rec);
+        worker.unref(); // idle threads must not keep the process alive
+        return rec;
+    }
+    dispatch(rec, task) {
+        rec.task = task;
+        rec.worker.ref(); // an awaited job keeps the event loop alive
+        const message = { id: task.id, options: task.options };
+        try {
+            rec.worker.postMessage(message);
+        }
+        catch (error) {
+            // e.g. DataCloneError for non-cloneable options.metadata — the
+            // thread is fine; fail only this task.
+            rec.task = null;
+            rec.worker.unref();
+            task.reject(error);
+            this.pump();
+        }
+    }
+    handleResponse(rec, response) {
+        const task = rec.task;
+        if (task === null || task.id !== response.id)
+            return; // stale/unknown id
+        rec.task = null;
+        if (this.terminated)
+            return;
+        if (response.ok)
+            task.resolve(response.result);
+        else
+            task.reject((0, worker_protocol_js_1.deserializeCube4Error)(response.error));
+        const next = this.queue.shift();
+        if (next !== undefined)
+            this.dispatch(rec, next);
+        else
+            rec.worker.unref();
+        this.pump();
+    }
+    handleWorkerGone(rec, error) {
+        const index = this.workers.indexOf(rec);
+        if (index === -1)
+            return; // already removed ('error' precedes 'exit')
+        this.workers.splice(index, 1);
+        const task = rec.task;
+        rec.task = null;
+        if (task !== null && !this.terminated) {
+            // Only THIS thread's job fails; the rest of the queue keeps running
+            // (a replacement thread is spawned lazily by pump()).
+            task.reject(error);
+        }
+        if (!this.terminated)
+            this.pump();
+    }
+    resolveWorkerEntry() {
+        if (this.workerPathOption !== undefined) {
+            return {
+                path: this.workerPathOption,
+                execArgv: this.workerPathOption.endsWith(".ts") ? [...TSX_ARGV] : []
+            };
+        }
+        const hereRaw = resolveCurrentModuleLocation();
+        if (hereRaw === undefined) {
+            throw new Error("[cube4] cannot locate worker.ts/worker.js next to worker-pool.js; " +
+                "pass an explicit `workerPath` to Cube4WorkerPool.");
+        }
+        // Normalise Windows separators: forward slashes are valid in every
+        // Node path/URL consumer here (Worker entry, fs lookups by Node).
+        const here = hereRaw.replace(/\\/g, "/");
+        const separator = here.lastIndexOf("/");
+        const dir = separator === -1 ? "." : here.slice(0, separator);
+        if (here.endsWith(".ts")) {
+            // Running from source under tsx → the thread needs the tsx loader.
+            return { path: `${dir}/worker.ts`, execArgv: [...TSX_ARGV] };
+        }
+        const distCjs = dir.lastIndexOf("/dist-cjs");
+        if (distCjs !== -1) {
+            // The CJS build excludes the worker entry (it is Node-ESM-only); the
+            // ESM tree is always published alongside and always contains it.
+            const esmDir = `${dir.slice(0, distCjs)}/dist${dir.slice(distCjs + "/dist-cjs".length)}`;
+            return { path: `${esmDir}/worker.js`, execArgv: [] };
+        }
+        return { path: `${dir}/worker.js`, execArgv: [] };
+    }
+}
+exports.Cube4WorkerPool = Cube4WorkerPool;
+// ── module-level conveniences ──────────────────────────────────────────
+let defaultPool;
+/** Shared lazily-created pool (used by `generateCube4ScrambleBatch`). */
+function getDefaultCube4WorkerPool() {
+    defaultPool ??= new Cube4WorkerPool();
+    return defaultPool;
+}
+/** Terminates (and forgets) the shared pool — call on process shutdown. */
+async function closeDefaultCube4WorkerPool() {
+    const pool = defaultPool;
+    defaultPool = undefined;
+    if (pool !== undefined)
+        await pool.terminate();
+}
+/**
+ * Batch convenience mirroring core `generateScrambles` for `444`:
+ *  - `count <= 1` runs INLINE in the caller (no thread spawn, no cold
+ *    start — a single scramble must never get slower);
+ *  - `count > 1` fans out over the shared pool (same seed derivation).
+ */
+async function generateCube4ScrambleBatch(count, options = {}) {
+    if (!Number.isInteger(count) || count < 1) {
+        throw new errors_js_1.InvalidCountError(count);
+    }
+    if (count === 1) {
+        return [await (0, scrambler_js_1.generateCube4Scramble)(options)];
+    }
+    return getDefaultCube4WorkerPool().generateBatch(count, options);
+}

package/dist-cjs/puzzles/cube4/worker-protocol.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Message protocol shared by the 4x4 Node worker (`worker.ts`), its pool
+ * (`worker-pool.ts`), and the browser equivalents (`browser-worker.ts`,
+ * `browser-worker-pool.ts`).
+ *
+ * Design notes:
+ *  - Tasks carry the FULL `generateCube4Scramble` options object. The
+ *    scrambler is a pure function of (seed, complete options), so forwarding
+ *    every option verbatim is what makes the pool output bit-identical to
+ *    the inline path for the same inputs.
+ *  - Errors cross the thread boundary as data (`Cube4SerializedError`):
+ *    `name`, `message`, `code` and `stack` survive, so typed solver errors
+ *    (e.g. `Cube4TargetMismatchError` with `code: "cube4-target-mismatch"`)
+ *    remain discriminated on the consumer side by name/code — the same
+ *    classification keys `scrambler.ts` itself uses. Classes cannot be
+ *    structured-cloned, so `instanceof` does not cross the boundary
+ *    (documented contract).
+ *
+ * This module is deliberately free of runtime imports (type-only imports
+ * are erased at emit) so it can be bundled for the browser worker without
+ * dragging Node-only code into the graph.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeCube4Error = serializeCube4Error;
+exports.deserializeCube4Error = deserializeCube4Error;
+/**
+ * Flattens an unknown thrown value into the structured-clone-safe shape
+ * above. Non-Error values are stringified so nothing is lost silently.
+ */
+function serializeCube4Error(error) {
+    if (error instanceof Error) {
+        const code = error.code;
+        const primitiveCode = typeof code === "string" || typeof code === "number" ? code : undefined;
+        const serialized = {
+            name: error.name,
+            message: error.message
+        };
+        if (primitiveCode !== undefined)
+            serialized.code = primitiveCode;
+        if (typeof error.stack === "string")
+            serialized.stack = error.stack;
+        return serialized;
+    }
+    return { name: "Error", message: String(error) };
+}
+/**
+ * Rebuilds an Error from the wire shape, restoring `name`, `code` and
+ * `stack` (stack kept only as a debugging aid — its file locations point
+ * into the worker thread).
+ */
+function deserializeCube4Error(serialized) {
+    const error = new Error(serialized.message);
+    error.name = serialized.name;
+    if (serialized.code !== undefined) {
+        error.code = serialized.code;
+    }
+    if (serialized.stack !== undefined) {
+        error.stack = serialized.stack;
+    }
+    return error;
+}

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

@@ -5,23 +5,43 @@ exports.clearCachedBrowserTables = clearCachedBrowserTables;
 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/pyraminx/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 [centersTable, permutationTable, orientationTable, policyTable] = await Promise.all([
-        fetchUint8Table(resolved, manifest.files.centersTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.centersTable.entries),
-        fetchUint16Table(resolved, manifest.files.permutationTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.permutationTable.entries),
-        fetchUint8Table(resolved, manifest.files.orientationTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.orientationTable.entries),
-        fetchUint8Table(resolved, manifest.files.policyTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.policyTable.entries)
+        fetchUint8Table(resolved, manifest.files.centersTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.centersTable),
+        fetchUint16Table(resolved, manifest.files.permutationTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.permutationTable),
+        fetchUint8Table(resolved, manifest.files.orientationTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.orientationTable),
+        fetchUint8Table(resolved, manifest.files.policyTable, table_metadata_js_1.PYRAMINX_SOLVER_TABLE_METADATA.policyTable)
     ]);
     cachedBrowserTables = { centersTable, permutationTable, orientationTable, policyTable };
     return cachedBrowserTables;
@@ -48,19 +68,28 @@ async function fetchManifest(baseUrl) {
         throw new Error(`Unsupported pyraminx solver table manifest version: ${manifest.version}`);
     return manifest;
 }
-const TABLES_DIR = "puzzles/pyraminx/solver/generated";
-const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
-async function fetchUint8Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { cacheName: CACHE_NAME, compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries)
-        throw new Error(`Invalid byte size for ${entry.file}`);
+/**
+ * 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 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);
 }
-async function fetchUint16Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { cacheName: CACHE_NAME, 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,
+        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);

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

@@ -35,7 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadGeneratedPyraminxSolverTables = loadGeneratedPyraminxSolverTables;
 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 loadGeneratedPyraminxSolverTables() {
             "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(