motely-wasm 20.0.1 → 20.1.0

package/.smoke-test.mjs

@@ -0,0 +1,58 @@
+// Temporary v20 smoke test — boots the EMBEDDED build and runs a real bounded
+// search end to end. Delete after use. Run: node .smoke-test.mjs
+import bootsharp from "./dist/index.mjs";
+import { Program } from "./dist/generated/modules/motely/wasm.g.mjs";
+
+const t0 = Date.now();
+const log = (m) => console.log(`[+${((Date.now() - t0) / 1000).toFixed(2)}s] ${m}`);
+
+let progressTicks = 0;
+let scored = 0;
+let firstMatch = null;
+
+Program.onProgress.subscribe(() => progressTicks++);
+Program.onSeedMatch.subscribe((seed) => {
+  if (!firstMatch) firstMatch = seed;
+});
+Program.onScoredResult.subscribe((r) => {
+  scored++;
+  if (scored <= 3) log(`  scored seed=${r.seed} score=${r.score} tallies=[${r.tallies}]`);
+});
+
+log("booting embedded WASM (no args)...");
+await bootsharp.boot();
+log(`booted. status=${bootsharp.getStatus()} (expect 2=Booted)`);
+
+// 1. JAML parse — throws on invalid.
+const JAML = `must:
+  - joker: Blueprint
+    antes: [1, 2, 3, 4, 5, 6, 7, 8]
+deck: Red
+stake: White
+`;
+const config = Program.parseJaml(JAML);
+log(`parseJaml OK: must=${config.must?.length ?? "?"} deck=${config.deck} stake=${config.stake}`);
+
+// 2. JAML <-> JSON roundtrip.
+const json = Program.jamlToJson(JAML);
+const backToJaml = Program.jsonToJaml(json);
+log(`jamlToJson OK (${json.length} chars), jsonToJaml OK (${backToJaml.length} chars)`);
+
+// 3. A real bounded random search (small N — NOT a full sweep).
+log("running runRandomSearch(config, 25000)...");
+const search = Program.runRandomSearch(config, 25000);
+log(
+  `search done: searched=${search.totalSeedsSearched} matches=${search.matchingSeeds} ` +
+    `completed=${search.isCompleted}`
+);
+log(`events fired: progress=${progressTicks} scored=${scored} firstMatch=${firstMatch ?? "(none)"}`);
+
+// Verdict.
+const ok =
+  bootsharp.getStatus() === 2 &&
+  config.deck === "Red" &&
+  json.length > 0 &&
+  search.isCompleted &&
+  search.totalSeedsSearched > 0n;
+log(ok ? "✅ SMOKE TEST PASSED" : "❌ SMOKE TEST FAILED");
+process.exit(ok ? 0 : 1);

package/README.md

@@ -1,126 +1,200 @@
 # motely-wasm
 
-WebAssembly build of [MotelyJAML](https://github.com/OptimusPi/MotelyJAML) — the SIMD Balatro seed search engine with JAML filter support. Powers [seedfinder.app](https://seedfinder.app).
+> Balatro seed search + per-seed analysis in the browser — a vectorized SIMD engine compiled to WebAssembly.
+
+[![npm version](https://img.shields.io/npm/v/motely-wasm.svg)](https://www.npmjs.com/package/motely-wasm)
+[![license](https://img.shields.io/npm/l/motely-wasm.svg)](./package.json)
+[![types](https://img.shields.io/badge/types-included-blue.svg)](#subpath-exports--where-the-types-live)
+[![WASM](https://img.shields.io/badge/runtime-embedded%20WASM-purple.svg)](#boot)
+
+The C# Motely seed engine, AOT/SIMD-compiled to WebAssembly via [Bootsharp](https://github.com/elringus/bootsharp). Author filters in **JAML** (Jimbo's Ante Markup Language), run real searches over Balatro's seed space, and analyze any single seed — all client-side, no server.
+
+- **Embedded** — the `.wasm` is inlined into the module. `boot()` takes no args, nothing to copy or serve.
+- **Typed** — full TypeScript declarations, emitted per C# namespace, served on subpath imports.
+- **Streaming** — subscribe to progress/match/scored events, or filter live with a JS predicate (`jimmolate`).
 
 ## Install
 
 ```sh
 npm install motely-wasm
+# or
+pnpm add motely-wasm
 ```
 
-## Boot
+Requires a host with WASM + ES modules: modern browsers, Node 18+, Deno, Bun. For browser UIs, run searches in a **Web Worker** — every `run*` call blocks its thread until the search completes (WASM has no pthreads).
 
-The WASM binary is **sideloaded** — a separate `dist/bin/motely-wasm.wasm`, **not** base64-embedded — so `boot()` **must** be told where to find it. A no-arg `boot()` will not load the runtime and every search silently does nothing.
+## Boot
 
-In Node, read the bytes and pass them directly (`fetch` can't read `file://` URLs):
+The WASM binary is **embedded** — no files to copy, no path to serve, no `bin/` to wire up. `boot()` takes no arguments.
 
-```js
-import { readFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+```ts
 import bootsharp from "motely-wasm";
 
-const dist = resolve(dirname(fileURLToPath(import.meta.url)), "node_modules/motely-wasm/dist");
-const wasm = await readFile(resolve(dist, "bin", bootsharp.manifest.wasm));
-await bootsharp.boot({ wasm });
+await bootsharp.boot(); // embedded: no args
 ```
 
-In the browser, pass the root URL your host serves `dist/` at:
+> **`bootsharp` is the _default_ export.** `boot`, `exit`, `getStatus`, `BootStatus`, and `manifest` hang off it. Do **not** write `import * as bootsharp` — `boot` is not a named export and `bootsharp.boot` would be `undefined`.
 
-```js
-await bootsharp.boot("/motely-wasm/dist");
-```
+> **`[Import]` bindings are snapshotted at `boot()`.** Assign `Program.jimmolatePredicate` (and any other `[Import]`) **before** calling `boot()`. You may reassign the predicate after boot to swap dispatch logic.
 
-Guard re-boots with `bootsharp.getStatus() === bootsharp.BootStatus.Standby`.
+## Quick start — run a search
 
-## Imports
+```ts
+import bootsharp from "motely-wasm";
+import { Program } from "motely-wasm/motely/wasm";
+import type { MotelyScoredSeedResult, MotelyProgress } from "motely-wasm/motely";
 
-```js
-// Main API — the C# Program class, renamed to Motely
-import { Program as Motely } from "motely-wasm/dist/generated/modules/motely/wasm.g.mjs";
+await bootsharp.boot();
 
-// Enums — MotelyDeck, MotelyStake, etc.
-import * as enums from "motely-wasm/dist/generated/modules/motely/enums.g.mjs";
+// 1. Parse JAML — throws on invalid input.
+const config = Program.parseJaml(`
+must:
+  - joker: Blueprint
+    antes: [1, 2, 3, 4, 5, 6, 7, 8]
+deck: Red
+stake: White
+`);
 
-// Types — MotelyProgress, IMotelySearch, MotelyScoredSeedResult, etc.
-import * as types from "motely-wasm/dist/generated/modules/motely.g.mjs";
+// 2. Stream results as the engine scores seeds.
+Program.onProgress.subscribe((p: MotelyProgress) =>
+  console.log(`${p.percentComplete.toFixed(1)}%  (${p.matchingSeeds} hits)`)
+);
+Program.onScoredResult.subscribe((r: MotelyScoredSeedResult) =>
+  console.log(`MATCH ${r.seed}  score=${r.score}`)
+);
+
+// 3. Run. Blocks until done (call from a Web Worker for a live UI).
+const search = Program.runRandomSearch(config, 100_000);
+console.log(`done: ${search.matchingSeeds}/${search.totalSeedsSearched} seeds`);
 ```
 
-## Quick start
+### Search entry points
 
-```js
-// Optional [Import] hook — surface WASM-side errors. Bind BEFORE boot:
-// Bootsharp snapshots [Import] bindings at boot().
-Motely.reportWasmError = (msg) => console.error("[WASM]", msg);
+| Method | Searches |
+|--------|----------|
+| `runSequentialSearch(config, startBatch?, endBatch?, batchChars?, intervalMs?)` | The seed space in order, batch by batch |
+| `runRandomSearch(config, count)` | `count` random seeds |
+| `runSeedListSearch(config)` | The seeds listed in `config.seeds` |
+| `runAestheticSearch(config, aesthetic)` | Seeds matching a `JamlAesthetic` lens |
+| `runNativeListSearch(filterName, seeds)` | A list through a built-in native filter |
+| `runPassthroughListSearch(seeds)` | A list with no filtering (decode/inspect) |
 
-// Subscribe to events
-Motely.onSeedMatch.subscribe(seed => console.log("match:", seed));
-Motely.onProgress.subscribe(p => console.log(`${p.percentComplete.toFixed(1)}%`));
+Each returns an `IMotelySearch` whose counters (`matchingSeeds`, `totalSeedsSearched`, `isCompleted`, …) are ready to read on return.
 
-// Parse a JAML filter. JAML is YAML, and YAML is a JSON superset — a JSON
-// object string parses too, which is what makes it round-trip cleanly over MCP.
-const config = Motely.parseJaml(`
-name: WeeMonday
-deck: Erratic
-stake: Black
-must:
-  - joker: WeeJoker
-    antes: [1]
-`);
+## Jimmolate — filter live with a JS predicate
 
-// Run a search (blocks until complete — run in a Worker for non-blocking UI).
-const search = Motely.runSequentialSearch(config);
-console.log(search.matchingSeeds, "matches out of", search.totalSeedsSearched);
+`jimmolate` is the original Immolate `filter(seed) => keep?` model, in the browser. The C# engine does the SIMD work; your JS predicate decides which **scored** results survive. A seed reaches your handler only if the predicate keeps it.
+
+```ts
+import bootsharp from "motely-wasm";
+import { Program } from "motely-wasm/motely/wasm";
+import type { MotelyScoredSeedResult } from "motely-wasm/motely";
+
+// Assign the predicate BEFORE boot (it's an [Import], snapshotted at boot).
+Program.jimmolatePredicate = (r: MotelyScoredSeedResult) => r.score >= 20;
+
+await bootsharp.boot();
+
+Program.jimmolateEnabled = true; // gate on — without this, every scored seed is reported
+Program.onScoredResult.subscribe((r) => keep(r)); // fires only for kept seeds
+
+Program.runRandomSearch(Program.parseJaml(jaml), 1_000_000);
 ```
 
-## API
-
-```js
-Motely.parseJaml(jaml)                       // string → JamlConfig (throws on invalid JAML)
-Motely.explainJaml(config)                   // human-readable plan summary
-Motely.createPlan(config)                    // JamlSearchPlan (tally columns, CSV header)
-Motely.jamlToJson(jaml)                       // JAML string → JSON string
-Motely.jsonToJaml(json)                       // JSON string → JAML string
-Motely.jamlyzer(seed, lens)                   // analyze ONE seed through a JamlConfig lens → JamlyzerSnapshot
-Motely.nativeFilterNames()                    // built-in native filter names
-
-Motely.runSequentialSearch(config, ...)       // sequential seed search
-Motely.runRandomSearch(config, count)         // random seed sample
-Motely.runSeedListSearch(config)              // search only config.seeds
-Motely.runAestheticSearch(config, aesthetic)  // aesthetic / scored search
-Motely.runNativeListSearch(name, seeds)       // named native filter over a seed list
-Motely.runPassthroughListSearch(seeds)        // no filter, just iterate seeds
+Leave `jimmolateEnabled` false to receive **every** scored seed (no filtering).
+
+JAML ⇄ JSON conversion is available too: `Program.jamlToJson(jaml)` and `Program.jsonToJaml(json)`.
+
+## Subpath exports — where the types live
+
+Bootsharp emits one declaration file **per C# namespace** ([Bootsharp · Type Declarations](https://github.com/elringus/bootsharp) → "One `.g.d.mts` file is emitted per C# namespace, colocated with the matching `.g.mjs` binding"). Members in a namespace land on a matching **subpath**; the bare top-level import is intentionally empty. **Import types from the subpath, not the package root.**
+
+| Import | Contents |
+|--------|----------|
+| `motely-wasm` | Default export: `boot()`, `exit()`, `getStatus()`, `BootStatus`, `manifest` |
+| `motely-wasm/motely/wasm` | `Program` — the engine API (search, JAML parse, file I/O) |
+| `motely-wasm/motely` | Core types: `MotelyScoredSeedResult`, `MotelyProgress`, `IMotelySearch`, `MotelyItem`, `MotelyMatchSource` |
+| `motely-wasm/motely/enums` | Engine enums: `MotelyDeck`, `MotelyStake`, `MotelyVoucher`, `MotelyTag`, `MotelyBossBlind`, `MotelyBoosterPack`, joker enums, … |
+| `motely-wasm/motely/filters/jaml` | `JamlConfig`, `JamlAesthetic` |
+| `motely-wasm/motely/filters` | `JamlSearchPlan` |
+| `motely-wasm/bootsharp/file-system` | `IFileSystem`, `IFileMounter`, `Change`, `MountOptions`, `PickOptions` |
+
+```ts
+import { Program } from "motely-wasm/motely/wasm";
+import type { IMotelySearch, MotelyProgress, MotelyScoredSeedResult } from "motely-wasm/motely";
+import { MotelyDeck, MotelyStake } from "motely-wasm/motely/enums";
+import { JamlAesthetic } from "motely-wasm/motely/filters/jaml";
 ```
 
 ## Events
 
-```js
-Motely.onSeedMatch.subscribe(seed => {})       // string — each matching seed
-Motely.onScoredResult.subscribe(result => {})  // MotelyScoredSeedResult { seed, score, tallies }
-Motely.onProgress.subscribe(p => {})           // MotelyProgress
-Motely.onFileChanges.subscribe(changes => {})  // file system changes (browser OPFS)
-```
+Subscribe before running a search.
+
+| Event | Payload | Fires |
+|-------|---------|-------|
+| `Program.onProgress` | `MotelyProgress` | On the progress interval during a run |
+| `Program.onSeedMatch` | `string` (seed) | When a seed matches the filter |
+| `Program.onScoredResult` | `MotelyScoredSeedResult` | Per scored seed (post-`jimmolate` filter) |
+| `Program.onFileChanges` | `Change[]` | When a mounted directory changes |
 
-## File system (browser)
+## File system (browser File System Access API)
 
-`Motely.pickRoot`, `mountRoot`, `unmountRoot`, `readTextFile`, `writeTextFile` use the browser File System Access API via `Bootsharp.FileSystem`. Initialize the JS extension before booting:
+The engine reads and writes JAML files from a user-picked directory via the browser File System Access API. This capability ships as a **separate peer package** — [`@rewaffle/bootsharp-file-system`](https://www.npmjs.com/package/@rewaffle/bootsharp-file-system), a sponsor-exclusive Bootsharp extension — because the WASM engine doesn't bundle the mounter itself. Install it and **wire the mounter before `boot()`**: `IFileMounter` is a Bootsharp `[Import]`, so calling `Program.pickRoot()` without `fs.init()` throws.
+
+```sh
+npm install @rewaffle/bootsharp-file-system   # peer package
+```
 
-```js
+```ts
+import bootsharp from "motely-wasm";
+import { Program } from "motely-wasm/motely/wasm";
+import { IFileMounter, PermissionMode } from "motely-wasm/bootsharp/file-system";
 import * as fs from "@rewaffle/bootsharp-file-system";
-import { Bootsharp } from "motely-wasm/dist/generated/modules/bootsharp/file-system.g.mjs";
 
-fs.init(Bootsharp.FileSystem.FileMounter);
-await bootsharp.boot("/motely-wasm/dist");
+// 1. Bind the mounter BEFORE boot (every [Import] is snapshotted at boot()).
+fs.init(IFileMounter);
+await bootsharp.boot();
+
+// 2. Now the file APIs on Program work.
+const root = await Program.pickRoot({ mode: PermissionMode.ReadWrite }); // null if cancelled
+if (root) {
+  await Program.mountRoot(root, { mode: PermissionMode.ReadWrite });
+  const jaml = await Program.readTextFile(root, "filters/blueprint.jaml");
+  await Program.writeTextFile(root, "filters/out.jaml", updated);
+  await Program.unmountRoot(root);
+}
+```
+
+The search / JAML / analysis APIs don't route through this — they run whether or not the mounter is wired. The directory APIs (`pickRoot`, `mountRoot`, `readTextFile`, `writeTextFile`) are what need it; unwired, they throw.
+
+### Mobile browsers / single file
+
+The directory mount relies on `showDirectoryPicker`, which iOS Safari and most mobile browsers **do not support** — and `Program` exposes only directory-*root* mounting (`pickRoot` / `mountRoot`), no single-file pick. So don't mount on mobile. You don't need to: `parseJaml`, `runRandomSearch`, etc. all take a JAML **string**. Read one file with a plain `<input type="file">` and feed its text straight in — works on every browser, no FS package required:
+
+```ts
+const file = input.files[0];                 // <input type="file" accept=".jaml,.yaml">
+const config = Program.parseJaml(await file.text());
+const search = Program.runRandomSearch(config, 100_000);
 ```
 
-## Jimmolate
+## Bundler notes
+
+The `browser` field in `package.json` stubs Node built-ins (`node:fs`, `node:url`, `node:path`, `node:module`, `node:crypto`, `node:process`) to `false`, so Vite/Webpack skip them cleanly. In library wrappers, **externalize** `motely-wasm` (and `motely-wasm/*`) so the consuming app controls WASM resolution.
 
-Scalar predicate filtering after the base SIMD pass. Bind the predicate **before** boot (Bootsharp snapshots `[Import]` bindings at boot), then enable it:
+## Build from source
 
-```js
-Motely.jimmolatePredicate = (result) => {
-    // result is MotelyScoredSeedResult — { seed, score, tallies }
-    return result.score > 0; // return true to keep the seed
-};
-Motely.jimmolateEnabled = true;
+```sh
+npm run build   # dotnet publish ../Motely.Wasm/Motely.Wasm.csproj -c Release
 ```
+
+Release builds use NativeAOT-LLVM (speed-optimized, trimmed). Output lands in `dist/`, which Bootsharp **regenerates wholesale on every publish** — never hand-edit anything under `dist/`.
+
+## Maintainers
+
+`package.json` is **hand-maintained and static** — edit it directly. Do **not** point `BootsharpPackageDirectory` at this directory: Bootsharp overwrites `package.json` on every build with a bare template (no version, types, or author), which breaks `npm publish`. The build parks that throwaway template in `obj/` (gitignored) instead. See the comment in `Motely.Wasm.csproj`.
+
+Bump versions with `npm version patch` (never hand-edit the `version` field), then `npm publish`.
+
+## License
+
+MIT © Nathanial P. Howard

package/__boot.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html><html><head><meta charset="utf-8"></head><body><pre id="o">booting…</pre>
+<script type="module">
+const o=document.getElementById("o");
+const S="name: t\ndeck: Red\nmust:\n  - joker: Blueprint\n";
+try{
+  const bs=(await import("./dist/index.mjs")).default;
+  const {Program}=await import("./dist/generated/modules/motely/wasm.g.mjs");
+  await bs.boot();
+  const json=Program.jamlToJson(S);
+  const cfg=Program.parseJaml(S);
+  window.__R={ok:true,json:json.slice(0,120),cfg:cfg!=null};
+  o.textContent="OK "+JSON.stringify(window.__R);
+}catch(e){window.__R={ok:false,err:String(e&&e.stack||e)};o.textContent="FAIL "+window.__R.err;}
+</script></body></html>

package/cli.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// motely-wasm CLI — boot the embedded engine and DO something from the terminal.
+// Doubles as the v20 end-to-end test nobody wrote. Exercises the full Program surface.
+//
+//   node cli.mjs search     <filter.jaml> --random <N>        bounded random search
+//   node cli.mjs search     <filter.jaml> --seeds A,B,C       seed-list search
+//   node cli.mjs jimmolate  <filter.jaml> --random <N> --min <s>   JS predicate keeps score>=s
+//   node cli.mjs sequential <filter.jaml> [--start N] [--end M]    ORDERED sweep (bounded!)
+//   node cli.mjs aesthetic  <filter.jaml> <aestheticIndex>    aesthetic-lens search of --seeds/--random
+//   node cli.mjs native     [<name> --seeds A,B,C]            list or run built-in native filters
+//   node cli.mjs explain    <filter.jaml>                     print the search plan in English
+//   node cli.mjs convert    <file.jaml>                       JAML -> JSON -> JAML roundtrip
+//
+import bootsharp from "./dist/index.mjs";
+import { Program } from "./dist/generated/modules/motely/wasm.g.mjs";
+import { readFileSync } from "node:fs";
+
+const t0 = Date.now();
+const secs = () => ((Date.now() - t0) / 1000).toFixed(2);
+const die = (m) => { console.error(`✗ ${m}`); process.exit(1); };
+const readJaml = (p) => { try { return readFileSync(p, "utf8"); } catch { die(`cannot read JAML: ${p}`); } };
+
+const [cmd, ...rest] = process.argv.slice(2);
+const flag = (name, def) => { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : def; };
+const arg0 = () => (rest[0] && !rest[0].startsWith("--") ? rest[0] : null);
+
+if (!cmd || cmd === "--help" || cmd === "-h") {
+  console.log(readFileSync(new URL(import.meta.url)).toString().split("\n").slice(1, 16).join("\n").replace(/^\/\/ ?/gm, ""));
+  process.exit(0);
+}
+
+// ── jimmolate predicate MUST be wired before boot (Bootsharp [Import], snapshotted at boot). ──
+let scoredTotal = 0, keptTotal = 0;
+const MIN = Number(flag("--min", "0"));
+if (cmd === "jimmolate") {
+  Program.jimmolatePredicate = (r) => {
+    scoredTotal++;
+    const keep = r.score >= MIN;
+    if (keep) keptTotal++;
+    return keep;
+  };
+}
+
+console.log(`[+${secs()}s] booting embedded WASM (no args)…`);
+await bootsharp.boot();
+console.log(`[+${secs()}s] booted (status ${bootsharp.getStatus()}).`);
+
+// ── commands that don't need a search ──
+if (cmd === "native" && !arg0()) {
+  console.log("Built-in native filters:");
+  for (const n of Program.nativeFilterNames()) console.log(`  • ${n}`);
+  process.exit(0);
+}
+if (cmd === "explain") {
+  const cfg = Program.parseJaml(readJaml(arg0() ?? die("usage: explain <filter.jaml>")));
+  console.log(`\n${Program.explainJaml(cfg) || "(no must/should/mustNot clauses to explain)"}`);
+  process.exit(0);
+}
+if (cmd === "convert") {
+  const src = readJaml(arg0() ?? die("usage: convert <file.jaml>"));
+  const json = Program.jamlToJson(src);
+  const back = Program.jsonToJaml(json);
+  console.log(`JAML -> JSON (${json.length} chars):\n${json}\n\nJSON -> JAML (${back.length} chars):\n${back}`);
+  process.exit(0);
+}
+// ── search-family commands ──
+const wireStreams = () => {
+  let shown = 0;
+  Program.onScoredResult.subscribe((r) => {
+    if (shown++ < 15) console.log(`   ★ ${r.seed}  score=${r.score}  tallies=[${r.tallies}]`);
+  });
+  Program.onProgress.subscribe((p) => {
+    process.stdout.write(`\r[+${secs()}s] ${p.percentComplete.toFixed(0)}%  hits=${p.matchingSeeds}   `);
+  });
+};
+const report = (search) => {
+  console.log(`\n[+${secs()}s] done: searched=${search.totalSeedsSearched} matches=${search.matchingSeeds} completed=${search.isCompleted}`);
+  process.exit(search.isCompleted ? 0 : 1);
+};
+
+if (cmd === "native") {
+  const seeds = (flag("--seeds") ?? die("usage: native <name> --seeds A,B,C")).split(",");
+  wireStreams();
+  report(Program.runNativeListSearch(arg0(), seeds));
+}
+
+const cfgFile = arg0() ?? die(`usage: ${cmd} <filter.jaml> …`);
+const config = Program.parseJaml(readJaml(cfgFile));
+console.log(`[+${secs()}s] parsed: must=${config.must?.length ?? 0} should=${config.should?.length ?? 0} deck=${config.deck} stake=${config.stake}`);
+wireStreams();
+
+if (cmd === "jimmolate") {
+  Program.jimmolateEnabled = true;
+  console.log(`[+${secs()}s] jimmolate ON — predicate keeps score >= ${MIN}`);
+}
+
+let search;
+if (cmd === "sequential") {
+  // SAFETY RAIL: never default to an unbounded sweep (the forbidden ~2.3T run).
+  const start = BigInt(flag("--start", "0"));
+  const end = BigInt(flag("--end", String(start + 1n))); // default: exactly one batch
+  if (end <= start) die("--end must be greater than --start");
+  if (end - start > 64n) die(`refusing ${end - start} batches — that's a huge sweep. Cap it (<=64 batches) for the CLI.`);
+  console.log(`[+${secs()}s] sequential sweep: batches [${start}, ${end}) …`);
+  search = Program.runSequentialSearch(config, start, end);
+} else if (cmd === "aesthetic") {
+  const aesthetic = Number(rest[1] ?? die("usage: aesthetic <filter.jaml> <aestheticIndex> --seeds …/--random …"));
+  const seeds = flag("--seeds"); const random = flag("--random");
+  if (seeds) config.seeds = seeds.split(",");
+  // aesthetic search reads its seed source from the config/settings the same way;
+  // run it and let the engine drive.
+  search = Program.runAestheticSearch(config, aesthetic);
+} else if (cmd === "search" || cmd === "jimmolate") {
+  const random = flag("--random"); const seeds = flag("--seeds");
+  search = random
+    ? Program.runRandomSearch(config, Number(random))
+    : seeds
+      ? (() => { config.seeds = seeds.split(","); return Program.runSeedListSearch(config); })()
+      : die("specify --random <N> or --seeds A,B,C");
+} else {
+  die(`unknown command "${cmd}" — try --help`);
+}
+
+if (cmd === "jimmolate")
+  console.log(`\n[+${secs()}s] jimmolate: predicate saw ${scoredTotal} scored seeds, KEPT ${keptTotal} (score >= ${MIN}).`);
+report(search);