@backtest-kit/cli 16.3.0 → 16.4.0

package/README.md

@@ -104,6 +104,7 @@ Every invocation is **one mode** (a primary flag) + a positional strategy/entry
 | **Candle Dump** | `--dump` | Fetch & save raw OHLCV candles to a file |
 | **PnL Debug** | `--pnldebug` | Simulate per-minute PnL for a given entry price & direction |
 | **Broker Debug** | `--brokerdebug` | Fire a single broker commit against the live adapter |
+| **Simulator** | `--simulator` | Sweep exit/entry parameters over a crowd-ideas feed, train an author whitelist |
 | **Flush** | `--flush` | Delete report/log/markdown/agent folders from a strategy dump dir |
 | **Init** | `--init` | Scaffold a new project |
 | **Docker** | `--docker` | Scaffold a self-contained Docker workspace |
@@ -266,12 +267,12 @@ The same shape works for `--live --entry` / `--paper --entry` (call `Live.backgr
 
 ## 🛠️ Tooling modes
 
-Five utilities that don't run a strategy. They share one convention, explained once here and referenced below.
+Six utilities that don't run a strategy. They share one convention, explained once here and referenced below.
 
 > **The `<mode>.module` convention.** By default the CLI auto-registers CCXT Binance. To use a different exchange (custom API keys, rate limits, a non-spot market), drop a `modules/<mode>.module.ts` that calls `addExchangeSchema` from `backtest-kit`. The CLI loads it automatically before running, trying `.ts`/`.mjs`/`.cjs`; it's searched **next to the target file first, then in the project root**. `.env` is loaded root-first then the target-file dir (override), so API keys stay out of code.
 
 <details>
-<summary>The shared <code>&lt;mode&gt;.module.ts</code> shape (pine / editor / dump / pnldebug / brokerdebug)</summary>
+<summary>The shared <code>&lt;mode&gt;.module.ts</code> shape (pine / editor / dump / pnldebug / brokerdebug / simulator)</summary>
 
 ```typescript
 // modules/pine.module.ts  (same shape for editor/dump/pnldebug.module; brokerdebug registers a Broker instead)
@@ -449,6 +450,34 @@ The CLI loads `./modules/brokerdebug.module`, fetches the last candle for `--sym
 
 </details>
 
+### 🎛️ Simulator (`--simulator`)
+
+Sweep exit/entry parameters over a feed of crowd trading ideas using the `Simulator` entity — one candle pass per idea, a full parameter grid evaluated arithmetically, an author whitelist trained with default-ban semantics. Prints a Markdown report with three ranking winners (time-based Sharpe, Sortino, PnL) and the production whitelist.
+
+```bash
+npx @backtest-kit/cli --simulator --symbol BTCUSDT ./assets/ts-ideas.normalized.jsonl
+# → summary to stdout; add --json / --markdown to save into ./dump/
+```
+
+<details>
+<summary>Simulator flags, input format & behavior</summary>
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--simulator` | boolean | Enable simulator mode |
+| `--symbol` | string | Trading pair to simulate (default `"BTCUSDT"`) |
+| `--exchange` | string | Exchange (default: first registered, falls back to CCXT Binance) |
+| `--output` | string | Output base name (default `simulator_{SYMBOL}_{TIMESTAMP}`) |
+| `--json` | boolean | Save the full `ISimulatorResult` to `./dump/<output>.json` |
+| `--markdown` | boolean | Save the summary report to `./dump/<output>.md` |
+| `--verbose` | boolean | Log every simulator lifecycle callback to the console |
+
+**Positional (required):** path to an ideas `.jsonl` file — one idea per line, exact shape `{ "id": number, "ts": number, "symbol": string, "direction": "LONG"|"SHORT"|"NEUTRAL", "author": string }`. The file is validated **before any work starts** — the first line that does not match the structure aborts the run with an error naming the line and the field. Ideas of other symbols are filtered out by the engine, so one shared feed serves any `--symbol`.
+
+Under the hood: 5-day candle horizon per idea (lazy chunked fetch through the exchange, persist cache first), flood dedupe (one idea per author per direction per 8h), author ban thresholds swept as grid axes (unproven author = banned by default), production slot semantics, time-based Sharpe/Sortino over daily equity buckets. With `--verbose` every lifecycle callback (`onIdeas`, `onProfiles`, `onAuthorsTrained`, `onGridPoint`, `onRanking`, `onDone`) is logged to the console as it fires, so long runs show progress. Exchange via `simulator.module` (see convention above).
+
+</details>
+
 ### 🗑️ Flush (`--flush`)
 
 Delete generated output folders from one or more strategy dump dirs **without** touching cached candle data.

package/build/index.cjs

@@ -233,14 +233,14 @@ const getReadySubject = functoolsKit.singleshot(() => {
     return new functoolsKit.Subject();
 });
 
-const main$i = () => {
+const main$j = () => {
     const entrySubject = getEntrySubject();
     entrySubject.subscribe(async (path) => {
         console.log("Running", path);
         await getReadySubject().next();
     });
 };
-main$i();
+main$j();
 
 const ERROR_HANDLER_INSTALLED = Symbol.for("error-handler-installed");
 function dumpStackTrace(error) {
@@ -891,6 +891,10 @@ const getArgs = functoolsKit.singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            simulator: {
+                type: "boolean",
+                default: false,
+            },
             commit: {
                 type: "string",
                 default: "",
@@ -3534,14 +3538,14 @@ const cli = {
 };
 init();
 
-const MODES = ["backtest", "walker", "paper", "live", "main", "pine", "editor", "dump", "pnldebug", "brokerdebug", "flush", "init", "docker", "help", "version"];
+const MODES = ["backtest", "walker", "paper", "live", "main", "pine", "editor", "dump", "pnldebug", "brokerdebug", "simulator", "flush", "init", "docker", "help", "version"];
 const ENTRY_PATH$1 = "./node_modules/@backtest-kit/cli/build/index.mjs";
 const HELP_TEXT$1 = `
 Example:
 
   node ${ENTRY_PATH$1} --help
 `.trimStart();
-const main$h = async () => {
+const main$i = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3549,14 +3553,14 @@ const main$h = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"16.3.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"16.4.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
     process.stdout.write(HELP_TEXT$1);
     process.exit(0);
 };
-main$h();
+main$i();
 
 const notifyShutdown = functoolsKit.singleshot(async () => {
     console.log("Graceful shutdown initiated.");
@@ -3572,7 +3576,7 @@ const flush = async (entryPoint) => {
         console.log(`Removed: ${target}`);
     }
 };
-const main$g = async () => {
+const main$h = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3589,7 +3593,7 @@ const main$g = async () => {
     }
     process.exit(0);
 };
-main$g();
+main$h();
 
 const BEFORE_EXIT_FN$6 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$6);
@@ -3612,7 +3616,7 @@ const BEFORE_EXIT_FN$6 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$6 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$6);
 });
-const main$f = async () => {
+const main$g = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3630,7 +3634,7 @@ const main$f = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$6();
 };
-main$f();
+main$g();
 
 const BEFORE_EXIT_FN$5 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$5);
@@ -3649,7 +3653,7 @@ const BEFORE_EXIT_FN$5 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$5 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$5);
 });
-const main$e = async () => {
+const main$f = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3668,7 +3672,7 @@ const main$e = async () => {
     listenGracefulShutdown$5();
     await cli.walkerMainService.connect();
 };
-main$e();
+main$f();
 
 const BEFORE_EXIT_FN$4 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$4);
@@ -3690,7 +3694,7 @@ const BEFORE_EXIT_FN$4 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$4 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$d = async () => {
+const main$e = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3704,7 +3708,7 @@ const main$d = async () => {
     await cli.paperMainService.connect();
     listenGracefulShutdown$4();
 };
-main$d();
+main$e();
 
 const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -3726,7 +3730,7 @@ const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$3 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$c = async () => {
+const main$d = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3740,7 +3744,7 @@ const main$c = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$3();
 };
-main$c();
+main$d();
 
 const stopBacktestList$1 = async () => {
     for (const item of await BacktestKit.Backtest.list()) {
@@ -3804,7 +3808,7 @@ const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$2 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$b = async () => {
+const main$c = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -3860,7 +3864,7 @@ const main$b = async () => {
     listenGracefulShutdown$2();
     await cli.resolveService.attachEntry(path.resolve(cwd, entryPoint));
 };
-main$b();
+main$c();
 
 const MODE_MODULE = {
     backtest: "backtest.module",
@@ -3963,7 +3967,7 @@ const createGracefulShutdown = (mode) => {
         process.on("SIGINT", handler);
     });
 };
-const main$a = async () => {
+const main$b = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4039,7 +4043,7 @@ const main$a = async () => {
     }
     await getEntrySubject().next(absolutePath);
 };
-main$a();
+main$b();
 
 const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -4050,7 +4054,7 @@ const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$1 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$9 = async () => {
+const main$a = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4060,7 +4064,7 @@ const main$9 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$9();
+main$a();
 
 const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -4071,7 +4075,7 @@ const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$8 = async () => {
+const main$9 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4081,7 +4085,7 @@ const main$8 = async () => {
     }
     listenGracefulShutdown();
 };
-main$8();
+main$9();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -4103,7 +4107,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main$7 = async () => {
+const main$8 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4203,9 +4207,9 @@ const main$7 = async () => {
     console.log(await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema));
     process.exit(0);
 };
-main$7();
+main$8();
 
-const main$6 = async () => {
+const main$7 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4268,9 +4272,9 @@ const main$6 = async () => {
     };
     process.on("SIGINT", beforeExit);
 };
-main$6();
+main$7();
 
-const main$5 = async () => {
+const main$6 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4351,9 +4355,9 @@ const main$5 = async () => {
     console.log(JSON.stringify(candles, null, 2));
     process.exit(0);
 };
-main$5();
+main$6();
 
-const main$4 = async () => {
+const main$5 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -4467,6 +4471,221 @@ const main$4 = async () => {
     }
     process.exit(0);
 };
+main$5();
+
+const SIMULATOR_NAME = "cli_simulator";
+const IDEA_DIRECTIONS = ["LONG", "SHORT", "NEUTRAL"];
+const validateIdea = (idea, line) => {
+    if (typeof idea !== "object" || idea === null) {
+        return `line ${line}: not an object`;
+    }
+    if (typeof idea.id !== "number") {
+        return `line ${line}: "id" must be a number, got ${typeof idea.id}`;
+    }
+    if (typeof idea.ts !== "number") {
+        return `line ${line}: "ts" must be a number (unix ms), got ${typeof idea.ts}`;
+    }
+    if (typeof idea.symbol !== "string" || !idea.symbol) {
+        return `line ${line}: "symbol" must be a non-empty string`;
+    }
+    if (!IDEA_DIRECTIONS.includes(idea.direction)) {
+        return `line ${line}: "direction" must be one of ${IDEA_DIRECTIONS.join("|")}, got ${JSON.stringify(idea.direction)}`;
+    }
+    if (typeof idea.author !== "string" || !idea.author) {
+        return `line ${line}: "author" must be a non-empty string`;
+    }
+    return null;
+};
+const toMarkdown = (result) => {
+    const lines = [];
+    lines.push(`# Simulator Report — ${result.symbol}`);
+    lines.push("");
+    lines.push(`| Metric | Value |`);
+    lines.push(`| --- | --- |`);
+    lines.push(`| Ideas (total / directional) | ${result.ideasTotal} / ${result.ideasDirectional} |`);
+    lines.push(`| Profiles (truncated) | ${result.profileCount} (${result.truncatedCount}) |`);
+    lines.push(`| Authors allowed / banned | ${result.allowedAuthors.length} / ${result.bannedAuthors.length} |`);
+    lines.push(`| Grid points | ${result.reports.length} |`);
+    lines.push(`| Hold minutes avg / p95 / p99 | ${result.avgHoldMinutes.toFixed(0)} / ${result.p95HoldMinutes} / ${result.p99HoldMinutes} |`);
+    lines.push("");
+    lines.push(`## Ranking winners`);
+    lines.push("");
+    lines.push(`| Criterion | Stop% | Trailing% | Hold | Aligned | Track | HitRate | Trades | PNL% | WinRate | Sharpe | Sortino |`);
+    lines.push(`| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |`);
+    for (const best of result.best) {
+        if (!best.report) {
+            lines.push(`| ${best.criterion} | — | — | — | — | — | — | — | — | — | — | — |`);
+            continue;
+        }
+        const { point } = best.report;
+        lines.push(`| ${best.criterion} | ${point.hardStopPercent} | ${point.trailingTakePercent} | ${point.holdMinutes / 60}h | ${point.minIdeasAligned} | ${point.minAuthorTrack} | ${point.minAuthorHitRate} | ` +
+            `${best.report.trades} | ${best.report.totalPnlPercent.toFixed(2)}% | ${(best.report.winRate * 100).toFixed(0)}% | ${best.report.sharpe.toFixed(2)} | ${best.report.sortino.toFixed(2)} |`);
+    }
+    lines.push("");
+    lines.push(`## Allowed authors (production whitelist)`);
+    lines.push("");
+    lines.push(`| Author | Ideas | Hits | HitRate |`);
+    lines.push(`| --- | --- | --- | --- |`);
+    for (const stat of result.authorStats.filter(({ banned }) => !banned)) {
+        lines.push(`| ${stat.author} | ${stat.ideas} | ${stat.hits} | ${(stat.hitRate * 100).toFixed(0)}% |`);
+    }
+    return lines.join("\n");
+};
+const main$4 = async () => {
+    if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
+        return;
+    }
+    const { values, positionals } = getArgs();
+    if (!values.simulator) {
+        return;
+    }
+    const [ideasPath = null] = positionals.filter((value) => value.endsWith(".jsonl"));
+    if (!ideasPath) {
+        console.error("Error: positional path to an ideas .jsonl file is required");
+        process.exit(1);
+    }
+    let ideas = [];
+    {
+        let content;
+        try {
+            content = await fs$1.readFile(path.resolve(ideasPath), "utf-8");
+        }
+        catch (error) {
+            console.error(`Error: cannot read ideas file: ${ideasPath}`);
+            process.exit(1);
+        }
+        const rows = content.split("\n").filter(Boolean);
+        if (!rows.length) {
+            console.error(`Error: ideas file is empty: ${ideasPath}`);
+            process.exit(1);
+        }
+        for (let i = 0; i < rows.length; i++) {
+            let idea;
+            try {
+                idea = JSON.parse(rows[i]);
+            }
+            catch {
+                console.error(`Error: invalid JSON in ideas file, line ${i + 1}`);
+                process.exit(1);
+            }
+            const problem = validateIdea(idea, i + 1);
+            if (problem) {
+                console.error(`Error: ideas file does not match the idea structure — ${problem}`);
+                console.error(`Expected shape: { "id": number, "ts": number, "symbol": string, "direction": "LONG"|"SHORT"|"NEUTRAL", "author": string }`);
+                process.exit(1);
+            }
+            ideas.push(idea);
+        }
+    }
+    {
+        const cwd = process.cwd();
+        dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+    }
+    await cli.configConnectionService.loadConfig("setup.config");
+    {
+        const loader = await cli.configConnectionService.loadConfig("loader.config");
+        try {
+            if (typeof loader === "function") {
+                await loader();
+            }
+            if (typeof loader?.loader === "function") {
+                await loader.loader();
+            }
+        }
+        catch (error) {
+            console.error("Module loader failed", error);
+            process.exit(-1);
+        }
+    }
+    await cli.moduleConnectionService.loadModule("simulator.module");
+    {
+        await cli.exchangeSchemaService.addSchema();
+        await cli.symbolSchemaService.addSchema();
+    }
+    const [defaultExchangeName = null] = await BacktestKit.listExchangeSchema();
+    const exchangeName = values.exchange || defaultExchangeName?.exchangeName;
+    const symbol = values.symbol || "BTCUSDT";
+    BacktestKit.addSimulatorSchema({
+        simulatorName: SIMULATOR_NAME,
+        exchangeName,
+        callbacks: {
+            onIdeas: (symbol, ideasTotal, ideasDirectional) => {
+                if (values.verbose) {
+                    console.log("onIdeas", { symbol, ideasTotal, ideasDirectional });
+                }
+            },
+            onProfiles: (symbol, profiles, truncatedCount) => {
+                if (values.verbose) {
+                    console.log("onProfiles", { symbol, profiles: profiles.length, truncatedCount });
+                }
+            },
+            onAuthorsTrained: (symbol, stats, bannedIdeas) => {
+                if (values.verbose) {
+                    console.log("onAuthorsTrained", {
+                        symbol,
+                        authors: stats.length,
+                        banned: stats.filter(({ banned }) => banned).length,
+                        bannedIdeas,
+                    });
+                }
+            },
+            onGridPoint: (symbol, report) => {
+                if (values.verbose) {
+                    console.log("onGridPoint", {
+                        symbol,
+                        point: report.point,
+                        trades: report.trades,
+                        pnl: +report.totalPnlPercent.toFixed(2),
+                        sharpe: +report.sharpe.toFixed(2),
+                    });
+                }
+            },
+            onRanking: (symbol, criterion, _sorted, best) => {
+                if (values.verbose) {
+                    console.log("onRanking", {
+                        symbol,
+                        criterion,
+                        point: best.report?.point ?? null,
+                        pnl: best.report ? +best.report.totalPnlPercent.toFixed(2) : null,
+                    });
+                }
+            },
+            onDone: (symbol, result) => {
+                if (values.verbose) {
+                    console.log("onDone", {
+                        symbol,
+                        reports: result.reports.length,
+                        allowedAuthors: result.allowedAuthors.length,
+                        bannedAuthors: result.bannedAuthors.length,
+                    });
+                }
+            },
+        },
+    });
+    const result = await BacktestKit.Simulator.run({
+        symbol,
+        simulatorName: SIMULATOR_NAME,
+        ideas,
+    });
+    const dumpName = values.output || `simulator_${symbol}_${Date.now()}`;
+    const dumpDir = path.join(process.cwd(), "dump");
+    if (values.json) {
+        const filePath = path.resolve(dumpDir, `${dumpName}.json`);
+        await fs$1.mkdir(dumpDir, { recursive: true });
+        await fs$1.writeFile(filePath, JSON.stringify(result, null, 2), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        process.exit(0);
+    }
+    if (values.markdown) {
+        const filePath = path.resolve(dumpDir, `${dumpName}.md`);
+        await fs$1.mkdir(dumpDir, { recursive: true });
+        await fs$1.writeFile(filePath, toMarkdown(result), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        process.exit(0);
+    }
+    console.log(toMarkdown(result));
+    process.exit(0);
+};
 main$4();
 
 const __filename$2 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
@@ -4665,6 +4884,7 @@ Modes:
   --dump                Fetch and save raw OHLCV candles
   --pnldebug            Simulate PnL per minute for a given entry price and direction
   --brokerdebug         Fire a single broker commit against the live broker adapter
+  --simulator <ideas.jsonl>  Sweep exit/entry parameters over crowd ideas, train author whitelist
   --flush  <entry...>   Delete report/log/markdown/agent folders from strategy dump dir
   --init                Scaffold a new project in the current directory
   --docker              Scaffold a Docker workspace for running strategies in a container
@@ -4785,6 +5005,33 @@ Broker debug flags (--brokerdebug):
   Loads ./live.module, fetches the last candle for --symbol/--timeframe, and calls
   the selected broker commit with synthetic payload values derived from current price.
 
+Simulator flags (--simulator):
+
+  --symbol      <string>   Trading pair to simulate (default: BTCUSDT)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name (default: simulator_{SYMBOL}_{TIMESTAMP})
+  --json                   Save full ISimulatorResult to ./dump/<output>.json
+  --markdown               Save summary report to ./dump/<output>.md
+  --verbose                Log every simulator lifecycle callback to the console
+
+  Positional: path to an ideas .jsonl file — one idea per line with the exact shape
+  { "id": number, "ts": number, "symbol": string, "direction": "LONG"|"SHORT"|"NEUTRAL",
+  "author": string }. The file is validated BEFORE any work; a line that does not
+  match the structure aborts the run with an error.
+
+  Runs the backtest-kit Simulator entity: one 5-day candle pass per idea, flood
+  dedupe (one idea per author per direction per 8h), default-ban author filter
+  (ban thresholds are grid axes), grid evaluation with time-based Sharpe/Sortino,
+  three ranking winners. The report includes the production author whitelist.
+  Ideas of other symbols are filtered out — one shared feed serves any --symbol.
+
+  No output flag → print the Markdown summary to stdout. With --verbose every
+  simulator lifecycle callback (onIdeas, onProfiles, onAuthorsTrained, onGridPoint,
+  onRanking, onDone) is logged to the console as it fires.
+
+  Module file ./modules/simulator.module is loaded automatically if it exists
+  (register your exchange there); without it CCXT Binance is used by default.
+
 Flush flags (--flush):
 
   One or more positional entry points. For each entry point the following
@@ -4818,6 +5065,7 @@ Module hooks (loaded automatically by each mode):
   modules/dump.module       --dump       Exchange schema for candle dumps
   modules/pnldebug.module   --pnldebug      Exchange schema for PnL debug runs
   modules/brokerdebug.module  --brokerdebug   Broker adapter used for broker commit testing
+  modules/simulator.module  --simulator     Exchange schema for crowd-ideas simulation
 
   --flush has no associated module. It only removes dump subdirectories.
 
@@ -4846,6 +5094,8 @@ Examples:
   node ${ENTRY_PATH} --pnldebug --priceopen 67956.73 --direction long --when 1772064000000 --minutes 60 --markdown
   node ${ENTRY_PATH} --brokerdebug --commit signal-open --symbol BTCUSDT
   node ${ENTRY_PATH} --brokerdebug --commit partial-profit --symbol ETHUSDT
+  node ${ENTRY_PATH} --simulator --symbol BTCUSDT ./assets/ts-ideas.normalized.jsonl
+  node ${ENTRY_PATH} --simulator --symbol BTCUSDT --json --output jun_2026_sweep ./assets/ts-ideas.normalized.jsonl
   node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts
   node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts ./content/feb_2026.strategy/feb_2026.test.ts
   node ${ENTRY_PATH} --init --output my-trading-bot
@@ -4859,7 +5109,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"16.3.0"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"16.4.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -4873,7 +5123,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"16.3.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"16.4.0"}\n`);
     process.exit(0);
 };
 main();

package/build/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import * as BacktestKit from 'backtest-kit';
-import { setConfig, listenExit, emitters, Notification, Cron, Recent, Storage, Markdown, Report, Dump, State, Memory, MarkdownWriter, ReportWriter, PersistSignalAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistPartialAdapter, PersistBreakevenAdapter, PersistCandleAdapter, PersistStorageAdapter, PersistNotificationAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistIntervalAdapter, PersistMemoryAdapter, PersistRecentAdapter, PersistStateAdapter, PersistSessionAdapter, PersistStrategyAdapter, Log, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, RecentLive, RecentBacktest, Broker, SessionLive, SessionBacktest, MemoryLive, MemoryBacktest, StateLive, StateBacktest, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, shutdown, listenSignal, listStrategySchema, overrideExchangeSchema, Backtest, System, Cache, Interval, alignToInterval, addWalkerSchema, overrideWalkerSchema, Walker, listenDoneWalker, Live, getCandles, checkCandles, warmCandles, listenRisk, listenStrategyCommit, listenSync, listenSignalNotify, Exchange } from 'backtest-kit';
+import { setConfig, listenExit, emitters, Notification, Cron, Recent, Storage, Markdown, Report, Dump, State, Memory, MarkdownWriter, ReportWriter, PersistSignalAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistPartialAdapter, PersistBreakevenAdapter, PersistCandleAdapter, PersistStorageAdapter, PersistNotificationAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistIntervalAdapter, PersistMemoryAdapter, PersistRecentAdapter, PersistStateAdapter, PersistSessionAdapter, PersistStrategyAdapter, Log, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, RecentLive, RecentBacktest, Broker, SessionLive, SessionBacktest, MemoryLive, MemoryBacktest, StateLive, StateBacktest, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, shutdown, listenSignal, listStrategySchema, overrideExchangeSchema, Backtest, System, Cache, Interval, alignToInterval, addWalkerSchema, overrideWalkerSchema, Walker, listenDoneWalker, Live, getCandles, checkCandles, warmCandles, listenRisk, listenStrategyCommit, listenSync, listenSignalNotify, Exchange, addSimulatorSchema, Simulator } from 'backtest-kit';
 import { singleshot, sleep, getErrorMessage, errorData, BehaviorSubject, Subject, str, compose, createAwaiter, execpool, queued, randomString, TIMEOUT_SYMBOL, typo, retry, trycatch, memoize, isObject } from 'functools-kit';
 import { exec, spawn } from 'child_process';
 import fs, { constants, realpathSync } from 'fs';
@@ -28,7 +28,7 @@ import Module, { createRequire } from 'module';
 import * as BacktestKitGraph from '@backtest-kit/graph';
 import * as BacktestKitOllama from '@backtest-kit/ollama';
 import * as BacktestKitPinets from '@backtest-kit/pinets';
-import { run as run$1, Code, toMarkdown } from '@backtest-kit/pinets';
+import { run as run$1, Code, toMarkdown as toMarkdown$1 } from '@backtest-kit/pinets';
 import * as BacktestKitSignals from '@backtest-kit/signals';
 import open from 'open';
 
@@ -208,14 +208,14 @@ const getReadySubject = singleshot(() => {
     return new Subject();
 });
 
-const main$i = () => {
+const main$j = () => {
     const entrySubject = getEntrySubject();
     entrySubject.subscribe(async (path) => {
         console.log("Running", path);
         await getReadySubject().next();
     });
 };
-main$i();
+main$j();
 
 const ERROR_HANDLER_INSTALLED = Symbol.for("error-handler-installed");
 function dumpStackTrace(error) {
@@ -866,6 +866,10 @@ const getArgs = singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            simulator: {
+                type: "boolean",
+                default: false,
+            },
             commit: {
                 type: "string",
                 default: "",
@@ -3502,14 +3506,14 @@ const cli = {
 };
 init();
 
-const MODES = ["backtest", "walker", "paper", "live", "main", "pine", "editor", "dump", "pnldebug", "brokerdebug", "flush", "init", "docker", "help", "version"];
+const MODES = ["backtest", "walker", "paper", "live", "main", "pine", "editor", "dump", "pnldebug", "brokerdebug", "simulator", "flush", "init", "docker", "help", "version"];
 const ENTRY_PATH$1 = "./node_modules/@backtest-kit/cli/build/index.mjs";
 const HELP_TEXT$1 = `
 Example:
 
   node ${ENTRY_PATH$1} --help
 `.trimStart();
-const main$h = async () => {
+const main$i = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3517,14 +3521,14 @@ const main$h = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"16.3.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"16.4.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
     process.stdout.write(HELP_TEXT$1);
     process.exit(0);
 };
-main$h();
+main$i();
 
 const notifyShutdown = singleshot(async () => {
     console.log("Graceful shutdown initiated.");
@@ -3540,7 +3544,7 @@ const flush = async (entryPoint) => {
         console.log(`Removed: ${target}`);
     }
 };
-const main$g = async () => {
+const main$h = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3557,7 +3561,7 @@ const main$g = async () => {
     }
     process.exit(0);
 };
-main$g();
+main$h();
 
 const BEFORE_EXIT_FN$6 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$6);
@@ -3580,7 +3584,7 @@ const BEFORE_EXIT_FN$6 = singleshot(async () => {
 const listenGracefulShutdown$6 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$6);
 });
-const main$f = async () => {
+const main$g = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3598,7 +3602,7 @@ const main$f = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$6();
 };
-main$f();
+main$g();
 
 const BEFORE_EXIT_FN$5 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$5);
@@ -3617,7 +3621,7 @@ const BEFORE_EXIT_FN$5 = singleshot(async () => {
 const listenGracefulShutdown$5 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$5);
 });
-const main$e = async () => {
+const main$f = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3636,7 +3640,7 @@ const main$e = async () => {
     listenGracefulShutdown$5();
     await cli.walkerMainService.connect();
 };
-main$e();
+main$f();
 
 const BEFORE_EXIT_FN$4 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$4);
@@ -3658,7 +3662,7 @@ const BEFORE_EXIT_FN$4 = singleshot(async () => {
 const listenGracefulShutdown$4 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$d = async () => {
+const main$e = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3672,7 +3676,7 @@ const main$d = async () => {
     await cli.paperMainService.connect();
     listenGracefulShutdown$4();
 };
-main$d();
+main$e();
 
 const BEFORE_EXIT_FN$3 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -3694,7 +3698,7 @@ const BEFORE_EXIT_FN$3 = singleshot(async () => {
 const listenGracefulShutdown$3 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$c = async () => {
+const main$d = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3708,7 +3712,7 @@ const main$c = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$3();
 };
-main$c();
+main$d();
 
 const stopBacktestList$1 = async () => {
     for (const item of await Backtest.list()) {
@@ -3772,7 +3776,7 @@ const BEFORE_EXIT_FN$2 = singleshot(async () => {
 const listenGracefulShutdown$2 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$b = async () => {
+const main$c = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3828,7 +3832,7 @@ const main$b = async () => {
     listenGracefulShutdown$2();
     await cli.resolveService.attachEntry(path.resolve(cwd, entryPoint));
 };
-main$b();
+main$c();
 
 const MODE_MODULE = {
     backtest: "backtest.module",
@@ -3931,7 +3935,7 @@ const createGracefulShutdown = (mode) => {
         process.on("SIGINT", handler);
     });
 };
-const main$a = async () => {
+const main$b = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4007,7 +4011,7 @@ const main$a = async () => {
     }
     await getEntrySubject().next(absolutePath);
 };
-main$a();
+main$b();
 
 const BEFORE_EXIT_FN$1 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -4018,7 +4022,7 @@ const BEFORE_EXIT_FN$1 = singleshot(async () => {
 const listenGracefulShutdown$1 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$9 = async () => {
+const main$a = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4028,7 +4032,7 @@ const main$9 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$9();
+main$a();
 
 const BEFORE_EXIT_FN = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -4039,7 +4043,7 @@ const BEFORE_EXIT_FN = singleshot(async () => {
 const listenGracefulShutdown = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$8 = async () => {
+const main$9 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4049,7 +4053,7 @@ const main$8 = async () => {
     }
     listenGracefulShutdown();
 };
-main$8();
+main$9();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -4071,7 +4075,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main$7 = async () => {
+const main$8 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4163,17 +4167,17 @@ const main$7 = async () => {
     if (values.markdown) {
         const filePath = resolve(dumpDir, `${dumpName}.md`);
         await mkdir(dumpDir, { recursive: true });
-        await writeFile(filePath, await toMarkdown(signalId, plots, signalSchema), "utf-8");
+        await writeFile(filePath, await toMarkdown$1(signalId, plots, signalSchema), "utf-8");
         console.log(`Saved: ${filePath}`);
         process.exit(0);
         return;
     }
-    console.log(await toMarkdown(signalId, plots, signalSchema));
+    console.log(await toMarkdown$1(signalId, plots, signalSchema));
     process.exit(0);
 };
-main$7();
+main$8();
 
-const main$6 = async () => {
+const main$7 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4236,9 +4240,9 @@ const main$6 = async () => {
     };
     process.on("SIGINT", beforeExit);
 };
-main$6();
+main$7();
 
-const main$5 = async () => {
+const main$6 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4319,9 +4323,9 @@ const main$5 = async () => {
     console.log(JSON.stringify(candles, null, 2));
     process.exit(0);
 };
-main$5();
+main$6();
 
-const main$4 = async () => {
+const main$5 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4435,6 +4439,221 @@ const main$4 = async () => {
     }
     process.exit(0);
 };
+main$5();
+
+const SIMULATOR_NAME = "cli_simulator";
+const IDEA_DIRECTIONS = ["LONG", "SHORT", "NEUTRAL"];
+const validateIdea = (idea, line) => {
+    if (typeof idea !== "object" || idea === null) {
+        return `line ${line}: not an object`;
+    }
+    if (typeof idea.id !== "number") {
+        return `line ${line}: "id" must be a number, got ${typeof idea.id}`;
+    }
+    if (typeof idea.ts !== "number") {
+        return `line ${line}: "ts" must be a number (unix ms), got ${typeof idea.ts}`;
+    }
+    if (typeof idea.symbol !== "string" || !idea.symbol) {
+        return `line ${line}: "symbol" must be a non-empty string`;
+    }
+    if (!IDEA_DIRECTIONS.includes(idea.direction)) {
+        return `line ${line}: "direction" must be one of ${IDEA_DIRECTIONS.join("|")}, got ${JSON.stringify(idea.direction)}`;
+    }
+    if (typeof idea.author !== "string" || !idea.author) {
+        return `line ${line}: "author" must be a non-empty string`;
+    }
+    return null;
+};
+const toMarkdown = (result) => {
+    const lines = [];
+    lines.push(`# Simulator Report — ${result.symbol}`);
+    lines.push("");
+    lines.push(`| Metric | Value |`);
+    lines.push(`| --- | --- |`);
+    lines.push(`| Ideas (total / directional) | ${result.ideasTotal} / ${result.ideasDirectional} |`);
+    lines.push(`| Profiles (truncated) | ${result.profileCount} (${result.truncatedCount}) |`);
+    lines.push(`| Authors allowed / banned | ${result.allowedAuthors.length} / ${result.bannedAuthors.length} |`);
+    lines.push(`| Grid points | ${result.reports.length} |`);
+    lines.push(`| Hold minutes avg / p95 / p99 | ${result.avgHoldMinutes.toFixed(0)} / ${result.p95HoldMinutes} / ${result.p99HoldMinutes} |`);
+    lines.push("");
+    lines.push(`## Ranking winners`);
+    lines.push("");
+    lines.push(`| Criterion | Stop% | Trailing% | Hold | Aligned | Track | HitRate | Trades | PNL% | WinRate | Sharpe | Sortino |`);
+    lines.push(`| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |`);
+    for (const best of result.best) {
+        if (!best.report) {
+            lines.push(`| ${best.criterion} | — | — | — | — | — | — | — | — | — | — | — |`);
+            continue;
+        }
+        const { point } = best.report;
+        lines.push(`| ${best.criterion} | ${point.hardStopPercent} | ${point.trailingTakePercent} | ${point.holdMinutes / 60}h | ${point.minIdeasAligned} | ${point.minAuthorTrack} | ${point.minAuthorHitRate} | ` +
+            `${best.report.trades} | ${best.report.totalPnlPercent.toFixed(2)}% | ${(best.report.winRate * 100).toFixed(0)}% | ${best.report.sharpe.toFixed(2)} | ${best.report.sortino.toFixed(2)} |`);
+    }
+    lines.push("");
+    lines.push(`## Allowed authors (production whitelist)`);
+    lines.push("");
+    lines.push(`| Author | Ideas | Hits | HitRate |`);
+    lines.push(`| --- | --- | --- | --- |`);
+    for (const stat of result.authorStats.filter(({ banned }) => !banned)) {
+        lines.push(`| ${stat.author} | ${stat.ideas} | ${stat.hits} | ${(stat.hitRate * 100).toFixed(0)}% |`);
+    }
+    return lines.join("\n");
+};
+const main$4 = async () => {
+    if (!getEntry(import.meta.url)) {
+        return;
+    }
+    const { values, positionals } = getArgs();
+    if (!values.simulator) {
+        return;
+    }
+    const [ideasPath = null] = positionals.filter((value) => value.endsWith(".jsonl"));
+    if (!ideasPath) {
+        console.error("Error: positional path to an ideas .jsonl file is required");
+        process.exit(1);
+    }
+    let ideas = [];
+    {
+        let content;
+        try {
+            content = await readFile(resolve(ideasPath), "utf-8");
+        }
+        catch (error) {
+            console.error(`Error: cannot read ideas file: ${ideasPath}`);
+            process.exit(1);
+        }
+        const rows = content.split("\n").filter(Boolean);
+        if (!rows.length) {
+            console.error(`Error: ideas file is empty: ${ideasPath}`);
+            process.exit(1);
+        }
+        for (let i = 0; i < rows.length; i++) {
+            let idea;
+            try {
+                idea = JSON.parse(rows[i]);
+            }
+            catch {
+                console.error(`Error: invalid JSON in ideas file, line ${i + 1}`);
+                process.exit(1);
+            }
+            const problem = validateIdea(idea, i + 1);
+            if (problem) {
+                console.error(`Error: ideas file does not match the idea structure — ${problem}`);
+                console.error(`Expected shape: { "id": number, "ts": number, "symbol": string, "direction": "LONG"|"SHORT"|"NEUTRAL", "author": string }`);
+                process.exit(1);
+            }
+            ideas.push(idea);
+        }
+    }
+    {
+        const cwd = process.cwd();
+        dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+    }
+    await cli.configConnectionService.loadConfig("setup.config");
+    {
+        const loader = await cli.configConnectionService.loadConfig("loader.config");
+        try {
+            if (typeof loader === "function") {
+                await loader();
+            }
+            if (typeof loader?.loader === "function") {
+                await loader.loader();
+            }
+        }
+        catch (error) {
+            console.error("Module loader failed", error);
+            process.exit(-1);
+        }
+    }
+    await cli.moduleConnectionService.loadModule("simulator.module");
+    {
+        await cli.exchangeSchemaService.addSchema();
+        await cli.symbolSchemaService.addSchema();
+    }
+    const [defaultExchangeName = null] = await listExchangeSchema();
+    const exchangeName = values.exchange || defaultExchangeName?.exchangeName;
+    const symbol = values.symbol || "BTCUSDT";
+    addSimulatorSchema({
+        simulatorName: SIMULATOR_NAME,
+        exchangeName,
+        callbacks: {
+            onIdeas: (symbol, ideasTotal, ideasDirectional) => {
+                if (values.verbose) {
+                    console.log("onIdeas", { symbol, ideasTotal, ideasDirectional });
+                }
+            },
+            onProfiles: (symbol, profiles, truncatedCount) => {
+                if (values.verbose) {
+                    console.log("onProfiles", { symbol, profiles: profiles.length, truncatedCount });
+                }
+            },
+            onAuthorsTrained: (symbol, stats, bannedIdeas) => {
+                if (values.verbose) {
+                    console.log("onAuthorsTrained", {
+                        symbol,
+                        authors: stats.length,
+                        banned: stats.filter(({ banned }) => banned).length,
+                        bannedIdeas,
+                    });
+                }
+            },
+            onGridPoint: (symbol, report) => {
+                if (values.verbose) {
+                    console.log("onGridPoint", {
+                        symbol,
+                        point: report.point,
+                        trades: report.trades,
+                        pnl: +report.totalPnlPercent.toFixed(2),
+                        sharpe: +report.sharpe.toFixed(2),
+                    });
+                }
+            },
+            onRanking: (symbol, criterion, _sorted, best) => {
+                if (values.verbose) {
+                    console.log("onRanking", {
+                        symbol,
+                        criterion,
+                        point: best.report?.point ?? null,
+                        pnl: best.report ? +best.report.totalPnlPercent.toFixed(2) : null,
+                    });
+                }
+            },
+            onDone: (symbol, result) => {
+                if (values.verbose) {
+                    console.log("onDone", {
+                        symbol,
+                        reports: result.reports.length,
+                        allowedAuthors: result.allowedAuthors.length,
+                        bannedAuthors: result.bannedAuthors.length,
+                    });
+                }
+            },
+        },
+    });
+    const result = await Simulator.run({
+        symbol,
+        simulatorName: SIMULATOR_NAME,
+        ideas,
+    });
+    const dumpName = values.output || `simulator_${symbol}_${Date.now()}`;
+    const dumpDir = join(process.cwd(), "dump");
+    if (values.json) {
+        const filePath = resolve(dumpDir, `${dumpName}.json`);
+        await mkdir(dumpDir, { recursive: true });
+        await writeFile(filePath, JSON.stringify(result, null, 2), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        process.exit(0);
+    }
+    if (values.markdown) {
+        const filePath = resolve(dumpDir, `${dumpName}.md`);
+        await mkdir(dumpDir, { recursive: true });
+        await writeFile(filePath, toMarkdown(result), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        process.exit(0);
+    }
+    console.log(toMarkdown(result));
+    process.exit(0);
+};
 main$4();
 
 const __filename$1 = fileURLToPath(import.meta.url);
@@ -4633,6 +4852,7 @@ Modes:
   --dump                Fetch and save raw OHLCV candles
   --pnldebug            Simulate PnL per minute for a given entry price and direction
   --brokerdebug         Fire a single broker commit against the live broker adapter
+  --simulator <ideas.jsonl>  Sweep exit/entry parameters over crowd ideas, train author whitelist
   --flush  <entry...>   Delete report/log/markdown/agent folders from strategy dump dir
   --init                Scaffold a new project in the current directory
   --docker              Scaffold a Docker workspace for running strategies in a container
@@ -4753,6 +4973,33 @@ Broker debug flags (--brokerdebug):
   Loads ./live.module, fetches the last candle for --symbol/--timeframe, and calls
   the selected broker commit with synthetic payload values derived from current price.
 
+Simulator flags (--simulator):
+
+  --symbol      <string>   Trading pair to simulate (default: BTCUSDT)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name (default: simulator_{SYMBOL}_{TIMESTAMP})
+  --json                   Save full ISimulatorResult to ./dump/<output>.json
+  --markdown               Save summary report to ./dump/<output>.md
+  --verbose                Log every simulator lifecycle callback to the console
+
+  Positional: path to an ideas .jsonl file — one idea per line with the exact shape
+  { "id": number, "ts": number, "symbol": string, "direction": "LONG"|"SHORT"|"NEUTRAL",
+  "author": string }. The file is validated BEFORE any work; a line that does not
+  match the structure aborts the run with an error.
+
+  Runs the backtest-kit Simulator entity: one 5-day candle pass per idea, flood
+  dedupe (one idea per author per direction per 8h), default-ban author filter
+  (ban thresholds are grid axes), grid evaluation with time-based Sharpe/Sortino,
+  three ranking winners. The report includes the production author whitelist.
+  Ideas of other symbols are filtered out — one shared feed serves any --symbol.
+
+  No output flag → print the Markdown summary to stdout. With --verbose every
+  simulator lifecycle callback (onIdeas, onProfiles, onAuthorsTrained, onGridPoint,
+  onRanking, onDone) is logged to the console as it fires.
+
+  Module file ./modules/simulator.module is loaded automatically if it exists
+  (register your exchange there); without it CCXT Binance is used by default.
+
 Flush flags (--flush):
 
   One or more positional entry points. For each entry point the following
@@ -4786,6 +5033,7 @@ Module hooks (loaded automatically by each mode):
   modules/dump.module       --dump       Exchange schema for candle dumps
   modules/pnldebug.module   --pnldebug      Exchange schema for PnL debug runs
   modules/brokerdebug.module  --brokerdebug   Broker adapter used for broker commit testing
+  modules/simulator.module  --simulator     Exchange schema for crowd-ideas simulation
 
   --flush has no associated module. It only removes dump subdirectories.
 
@@ -4814,6 +5062,8 @@ Examples:
   node ${ENTRY_PATH} --pnldebug --priceopen 67956.73 --direction long --when 1772064000000 --minutes 60 --markdown
   node ${ENTRY_PATH} --brokerdebug --commit signal-open --symbol BTCUSDT
   node ${ENTRY_PATH} --brokerdebug --commit partial-profit --symbol ETHUSDT
+  node ${ENTRY_PATH} --simulator --symbol BTCUSDT ./assets/ts-ideas.normalized.jsonl
+  node ${ENTRY_PATH} --simulator --symbol BTCUSDT --json --output jun_2026_sweep ./assets/ts-ideas.normalized.jsonl
   node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts
   node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts ./content/feb_2026.strategy/feb_2026.test.ts
   node ${ENTRY_PATH} --init --output my-trading-bot
@@ -4827,7 +5077,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"16.3.0"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"16.4.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -4841,7 +5091,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"16.3.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"16.4.0"}\n`);
     process.exit(0);
 };
 main();

package/docker/package.json

@@ -15,17 +15,17 @@
     "@types/node": "25.6.0"
   },
   "dependencies": {
-    "@backtest-kit/cli": "16.3.0",
-    "@backtest-kit/graph": "16.3.0",
-    "@backtest-kit/pinets": "16.3.0",
-    "@backtest-kit/signals": "16.3.0",
-    "@backtest-kit/ui": "16.3.0",
+    "@backtest-kit/cli": "16.4.0",
+    "@backtest-kit/graph": "16.4.0",
+    "@backtest-kit/pinets": "16.4.0",
+    "@backtest-kit/signals": "16.4.0",
+    "@backtest-kit/ui": "16.4.0",
     "@tavily/core": "0.7.2",
     "@tensorflow/tfjs": "4.22.0",
     "@tensorflow/tfjs-backend-wasm": "4.22.0",
     "@tensorflow/tfjs-core": "4.22.0",
     "agent-swarm-kit": "6.0.0",
-    "backtest-kit": "16.3.0",
+    "backtest-kit": "16.4.0",
     "dayjs": "1.11.20",
     "functools-kit": "5.0.0",
     "garch": "2.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtest-kit/cli",
-  "version": "16.3.0",
+  "version": "16.4.0",
   "description": "Zero-boilerplate CLI runner for backtest-kit strategies. Run backtests, paper trading, and live bots with candle cache warming, web dashboard, and Telegram notifications — no setup code required.",
   "author": {
     "name": "Petr Tripolsky",
@@ -63,11 +63,11 @@
   "devDependencies": {
     "@babel/plugin-transform-modules-umd": "7.27.1",
     "@babel/standalone": "7.29.1",
-    "@backtest-kit/graph": "16.3.0",
-    "@backtest-kit/ollama": "16.3.0",
-    "@backtest-kit/pinets": "16.3.0",
-    "@backtest-kit/signals": "16.3.0",
-    "@backtest-kit/ui": "16.3.0",
+    "@backtest-kit/graph": "16.4.0",
+    "@backtest-kit/ollama": "16.4.0",
+    "@backtest-kit/pinets": "16.4.0",
+    "@backtest-kit/signals": "16.4.0",
+    "@backtest-kit/ui": "16.4.0",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-typescript": "11.1.6",
     "@types/image-size": "0.7.0",
@@ -75,7 +75,7 @@
     "@types/mustache": "4.2.6",
     "@types/node": "22.9.0",
     "@types/stack-trace": "0.0.33",
-    "backtest-kit": "16.3.0",
+    "backtest-kit": "16.4.0",
     "glob": "11.0.1",
     "markdown-it": "14.1.1",
     "rimraf": "6.0.1",
@@ -92,14 +92,14 @@
   "peerDependencies": {
     "@babel/plugin-transform-modules-umd": "^7.27.1",
     "@babel/standalone": "^7.29.1",
-    "@backtest-kit/graph": "^16.3.0",
-    "@backtest-kit/ollama": "^16.3.0",
-    "@backtest-kit/pinets": "^16.3.0",
-    "@backtest-kit/signals": "^16.3.0",
-    "@backtest-kit/ui": "^16.3.0",
+    "@backtest-kit/graph": "^16.4.0",
+    "@backtest-kit/ollama": "^16.4.0",
+    "@backtest-kit/pinets": "^16.4.0",
+    "@backtest-kit/signals": "^16.4.0",
+    "@backtest-kit/ui": "^16.4.0",
     "pinets": "^0.9.29",
     "ccxt": "^4.5.39",
-    "backtest-kit": "^16.3.0",
+    "backtest-kit": "^16.4.0",
     "markdown-it": "^14.1.1",
     "typescript": "^5.0.0"
   },

package/template/project/package.mustache

@@ -13,12 +13,12 @@
   "license": "ISC",
   "type": "commonjs",
   "dependencies": {
-    "@backtest-kit/cli": "^16.3.0",
-    "@backtest-kit/graph": "^16.3.0",
-    "@backtest-kit/pinets": "^16.3.0",
-    "@backtest-kit/ui": "^16.3.0",
+    "@backtest-kit/cli": "^16.4.0",
+    "@backtest-kit/graph": "^16.4.0",
+    "@backtest-kit/pinets": "^16.4.0",
+    "@backtest-kit/ui": "^16.4.0",
     "agent-swarm-kit": "^6.0.0",
-    "backtest-kit": "^16.3.0",
+    "backtest-kit": "^16.4.0",
     "functools-kit": "^5.0.0",
     "garch": "^2.0.0",
     "get-moment-stamp": "^3.0.0",