[scramble] Add experimentalDeriveScrambleForEvent(…).

Example usage:

```js

import { experimentalDeriveScrambleForEvent } from "cubing/scramble";
import { setSearchDebug } from "cubing/search";

setSearchDebug({ allowDerivedScrambles: true });
(
  await experimentalDeriveScrambleForEvent(
    "67002dfc95e6d4288f418fbaa9150aa65b239fd5581f2d067d0293b9321a8b67",
    ["222", "222-r4", "set1", "attempt3-extra2", "scramble1"],
    "222",
  )
).log();
```

Author: lgarron

script/test/dist/lib/cubing/node/scramble/test.js

@@ -1,11 +1,15 @@
+import assert from "node:assert";
 import { Alg } from "cubing/alg";
 import { cube2x2x2 } from "cubing/puzzles";
-import { randomScrambleForEvent } from "cubing/scramble";
+import {
+  experimentalDeriveScrambleForEvent,
+  randomScrambleForEvent,
+} from "cubing/scramble";
 import { experimentalSolveTwsearch, setSearchDebug } from "cubing/search";
 
 setSearchDebug({ disableStringWorker: true });
 
-(async () => {
+await (async () => {
   (await randomScrambleForEvent("222")).log();
   (await randomScrambleForEvent("333")).log();
 
@@ -31,7 +35,36 @@ setSearchDebug({ disableStringWorker: true });
   }
 
   console.log("Success!");
+})();
+
+await (async () => {
+  {
+    console.log("----------------");
+    console.log("Deriving scrambles.");
+    setSearchDebug({ allowDerivedScrambles: true });
+    const scramble1 = await experimentalDeriveScrambleForEvent(
+      "67002dfc95e6d4288f418fbaa9150aa65b239fd5581f2d067d0293b9321a8b67",
+      ["222", "222-r4", "set1", "attempt3-extra2", "scramble1"],
+      "222",
+    );
+    console.log(scramble1.toString());
+    const scramble2 = await experimentalDeriveScrambleForEvent(
+      "67002dfc95e6d4288f418fbaa9150aa65b239fd5581f2d067d0293b9321a8b67",
+      ["222", "222-r4", "set1", "attempt3-extra2", "scramble1"],
+      "222",
+    );
+    console.log(scramble2.toString());
+    const scramble3 = await experimentalDeriveScrambleForEvent(
+      "6700abcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
+      ["222", "222-r4", "set1", "attempt3-extra2", "scramble1"],
+      "222",
+    );
+    console.log(scramble3.toString());
 
-  // TODO(https://github.com/cubing/cubing.js/issues/358): this shouldn't be needed.
-  (await import("node:process")).exit(0);
+    assert(scramble1.isIdentical(scramble2));
+    assert(!scramble1.isIdentical(scramble3));
+  }
 })();
+
+// TODO(https://github.com/cubing/cubing.js/issues/358): this shouldn't be needed.
+(await import("node:process")).exit(0);

src/cubing/scramble/index.ts

@@ -6,4 +6,7 @@
  * @packageDocumentation
  */
 
-export { randomScrambleForEvent } from "../search/cubing-private";
+export {
+  deriveScrambleForEvent as experimentalDeriveScrambleForEvent,
+  randomScrambleForEvent,
+} from "../search/cubing-private";

src/cubing/search/cubing-private/index.ts

@@ -1,2 +1,2 @@
 export { random333Scramble as rawRandom333Scramble } from "../inside/solve/puzzles/3x3x3";
-export { randomScrambleForEvent } from "../outside";
+export { deriveScrambleForEvent, randomScrambleForEvent } from "../outside";

src/cubing/search/inside/api.ts

@@ -28,6 +28,7 @@ import { randomRediCubeScramble } from "./solve/puzzles/redi_cube";
 import { solveSkewb } from "./solve/puzzles/skewb";
 import {
   type TwsearchOptions,
+  wasmDeriveScrambleForEvent,
   wasmRandomScrambleForEvent,
   wasmTwsearch,
 } from "./solve/twsearch";
@@ -231,6 +232,23 @@ export const insideAPI = {
     return (await insideAPI.randomScrambleForEvent(eventID)).toString();
   },
 
+  deriveScrambleStringForEvent: async (
+    derivationSeedHex: string,
+    derivationSaltHierarchy: string[],
+    eventID: string,
+  ): Promise<string> => {
+    const scramble = await measurePerf(
+      `deriveScrambleForEvent(…, ${JSON.stringify(eventID)})`,
+      () =>
+        wasmDeriveScrambleForEvent(
+          derivationSeedHex,
+          derivationSaltHierarchy,
+          eventID,
+        ),
+    );
+    return scramble.toString();
+  },
+
   solve333ToString: async (patternData: KPatternData): Promise<string> => {
     const pattern = new KPattern(await puzzles["3x3x3"].kpuzzle(), patternData);
     return (await solve333(pattern)).toString();

src/cubing/search/inside/solve/twsearch.ts

@@ -33,3 +33,16 @@ export async function wasmRandomScrambleForEvent(
   const { wasmRandomScrambleForEvent } = await twsearchPromise;
   return wasmRandomScrambleForEvent(eventID);
 }
+
+export async function wasmDeriveScrambleForEvent(
+  derivationSeedHex: string,
+  derivationSaltHierarchy: string[],
+  eventID: string,
+): Promise<Alg> {
+  const { wasmDeriveScrambleForEvent } = await twsearchPromise;
+  return wasmDeriveScrambleForEvent(
+    derivationSeedHex,
+    derivationSaltHierarchy,
+    eventID,
+  );
+}

src/cubing/search/outside.ts

@@ -3,7 +3,6 @@ import type { KPuzzle } from "../kpuzzle";
 // import { preInitialize222 } from "../implementations/2x2x2";
 import type { KPattern } from "../kpuzzle/KPattern";
 import type { PrefetchLevel } from "./inside/api";
-import { randomClockScrambleString } from "./inside/solve/puzzles/clock"; // TODO: don't reach into `inside` code.
 import type { TwsearchOptions } from "./inside/solve/twsearch";
 import {
   type InsideOutsideAPI,
@@ -48,34 +47,31 @@ export function _preInitializationHintForEvent(
 }
 
 export async function randomScrambleForEvent(eventID: string): Promise<Alg> {
-  switch (eventID) {
-    case "clock":
-      return Alg.fromString(await randomClockScrambleString());
-  }
-  const prom = _randomScrambleStringForEvent(eventID);
-  const wat = await prom;
-  return Alg.fromString(wat);
-}
-
-export async function _randomScrambleStringForEvent(
-  eventID: string,
-): Promise<string> {
-  if (searchOutsideDebugGlobals.forceNewWorkerForEveryScramble) {
-  }
   const worker = searchOutsideDebugGlobals.forceNewWorkerForEveryScramble
     ? await instantiateWorker()
     : await getCachedWorkerInstance();
-  return worker.insideAPI.randomScrambleStringForEvent(eventID);
+  const scrambleString =
+    await worker.insideAPI.randomScrambleStringForEvent(eventID);
+  return Alg.fromString(scrambleString);
 }
 
-export async function randomScrambleStringForEvent(
+export async function deriveScrambleForEvent(
+  derivationSeedHex: string,
+  derivationSaltHierarchy: string[],
   eventID: string,
-): Promise<string> {
-  switch (eventID) {
-    case "clock":
-      return randomClockScrambleString();
+): Promise<Alg> {
+  if (!searchOutsideDebugGlobals.allowDerivedScrambles) {
+    throw new Error("Derived scrambles are not allowed.");
   }
-  return await _randomScrambleStringForEvent(eventID);
+  const worker = searchOutsideDebugGlobals.forceNewWorkerForEveryScramble
+    ? await instantiateWorker()
+    : await getCachedWorkerInstance();
+  const scrambleString = await worker.insideAPI.deriveScrambleStringForEvent(
+    derivationSeedHex,
+    derivationSaltHierarchy,
+    eventID,
+  );
+  return Alg.fromString(scrambleString);
 }
 
 export async function experimentalSolve3x3x3IgnoringCenters(
@@ -159,6 +155,7 @@ interface SearchOutsideDebugGlobals {
   showWorkerInstantiationWarnings: boolean;
   // This can prevent a request to `search-worker-entry.js` when it doesn't exist, if the library semantics have been mangled by `esbuild`.
   prioritizeEsbuildWorkaroundForWorkerInstantiation: boolean;
+  allowDerivedScrambles: boolean;
 }
 
 export const searchOutsideDebugGlobals: SearchOutsideDebugGlobals = {
@@ -168,6 +165,7 @@ export const searchOutsideDebugGlobals: SearchOutsideDebugGlobals = {
   forceNewWorkerForEveryScramble: false,
   showWorkerInstantiationWarnings: true,
   prioritizeEsbuildWorkaroundForWorkerInstantiation: false,
+  allowDerivedScrambles: false,
 };
 
 export function setSearchDebug(
@@ -186,21 +184,16 @@ export function setSearchDebug(
       ),
     );
   }
-  if ("disableStringWorker" in options) {
-    searchOutsideDebugGlobals.disableStringWorker =
-      options.disableStringWorker ??
-      searchOutsideDebugGlobals.disableStringWorker;
-  }
-  if ("forceNewWorkerForEveryScramble" in options) {
-    searchOutsideDebugGlobals.forceNewWorkerForEveryScramble =
-      !!options.forceNewWorkerForEveryScramble;
-  }
-  if ("showWorkerInstantiationWarnings" in options) {
-    searchOutsideDebugGlobals.showWorkerInstantiationWarnings =
-      !!options.showWorkerInstantiationWarnings;
-  }
-  if ("prioritizeEsbuildWorkaroundForWorkerInstantiation" in options) {
-    searchOutsideDebugGlobals.prioritizeEsbuildWorkaroundForWorkerInstantiation =
-      !!options.prioritizeEsbuildWorkaroundForWorkerInstantiation;
+  for (const booleanField of [
+    "disableStringWorker",
+    "forceNewWorkerForEveryScramble",
+    "showWorkerInstantiationWarnings",
+    "prioritizeEsbuildWorkaroundForWorkerInstantiation",
+    "allowDerivedScrambles",
+  ] as const) {
+    if (booleanField in options) {
+      searchOutsideDebugGlobals[booleanField] =
+        options[booleanField] ?? searchOutsideDebugGlobals[booleanField];
+    }
   }
 }