@cubingcenter/scrambler 0.6.3 → 0.8.0

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.6.3",
+  "version": "0.8.0",
   "description": "Extensible scramble generation toolkit for CubingCenter projects.",
   "type": "module",
   "license": "MIT",
@@ -57,15 +57,22 @@
     "tsx": "^4.20.0",
     "typescript": "^5.9.0"
   },
-  "dependencies": {
-    "cubing": "^0.63.4"
-  },
   "scripts": {
     "build": "node scripts/clean.cjs && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/write-cjs-package.cjs && node scripts/copy-assets.cjs",
-    "test": "node --test --import tsx test/*.test.ts",
+    "test": "node --test --import tsx",
+    "test:all": "node --test --import tsx test/*.test.ts",
+    "test:skewb": "node --test --import tsx test/skewb*.test.ts",
+    "test:pyraminx": "node --test --import tsx test/pyraminx*.test.ts",
+    "test:sq1": "node --test --import tsx test/sq1*.test.ts",
+    "test:fto": "node --test --import tsx test/fto*.test.ts",
+    "test:cube2": "node --test --import tsx test/cube2*.test.ts",
+    "test:cube3": "node --test --import tsx test/cube3*.test.ts",
+    "test:cube4": "node --test --import tsx test/cube4*.test.ts test/center*.test.ts test/edge3.test.ts test/pairing-coordinate.test.ts test/phase*.test.ts",
+    "test:big": "node --test --import tsx test/big-cubes*.test.ts",
+    "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",
@@ -83,6 +90,8 @@
     "cube4:center2:tables:check": "node --import tsx scripts/check-center2-solver-tables.ts",
     "cube4:center3:tables": "node --import tsx scripts/generate-center3-solver-tables.ts",
     "cube4:center3:tables:check": "node --import tsx scripts/check-center3-solver-tables.ts",
+    "cube4:hc:tables": "node --import tsx scripts/generate-hc-pdb-table.ts",
+    "cube4:hc:tables:check": "node --import tsx scripts/check-hc-pdb-table.ts",
     "cube4:edge3:tables": "node --import tsx scripts/generate-edge3-solver-tables.ts",
     "cube4:edge3:tables:check": "node --import tsx scripts/check-edge3-solver-tables.ts",
     "tables:web:sync": "node --import tsx scripts/sync-web-tables.ts",
@@ -94,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"
   }
 }