@backtest-kit/cli 16.3.0 → 16.5.0

package/build/index.mjs

@@ -1,7 +1,7 @@
 #!/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 { singleshot, sleep, getErrorMessage, errorData, BehaviorSubject, Subject, str, compose, createAwaiter, execpool, queued, randomString, TIMEOUT_SYMBOL, typo, retry, trycatch, memoize, isObject } from 'functools-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, listenOrderFill, listenOrderReject, listenOrderContinue, listenOrderStop, 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, ttl, memoize, isObject } from 'functools-kit';
 import { exec, spawn } from 'child_process';
 import fs, { constants, realpathSync } from 'fs';
 import * as stackTrace from 'stack-trace';
@@ -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: "",
@@ -2312,6 +2316,13 @@ const STOP_BOT_FN = singleshot(async () => {
     const { stopBot } = await getTelegram();
     stopBot();
 });
+/**
+ * Throttle window for the per-tick order_continue decision channel: at most one
+ * Telegram notification per signalId per 15 minutes via functools-kit ttl. The
+ * terminal order_stop is NOT throttled (fires once per signal) and clears the
+ * throttle slot for its signalId.
+ */
+const ORDER_CHECK_NOTIFY_TTL = 15 * 60 * 1000;
 class TelegramLogicService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
@@ -2460,11 +2471,24 @@ class TelegramLogicService {
                 markdown,
             });
         };
-        this.notifySignalOpen = trycatch(async (event) => {
-            this.loggerService.log("telegramLogicService notifySignalOpen", {
+        this.notifyOrderFillOpen = trycatch(async (event) => {
+            this.loggerService.log("telegramLogicService notifyOrderFillOpen", {
+                event,
+            });
+            const markdown = await this.telegramTemplateService.getOrderFillOpenMarkdown(event);
+            if (!markdown) {
+                return;
+            }
+            await this.telegramWebService.publishNotify({
+                symbol: event.symbol,
+                markdown,
+            });
+        });
+        this.notifyOrderFillClose = trycatch(async (event) => {
+            this.loggerService.log("telegramLogicService notifyOrderFillClose", {
                 event,
             });
-            const markdown = await this.telegramTemplateService.getSignalOpenMarkdown(event);
+            const markdown = await this.telegramTemplateService.getOrderFillCloseMarkdown(event);
             if (!markdown) {
                 return;
             }
@@ -2473,11 +2497,64 @@ class TelegramLogicService {
                 markdown,
             });
         });
-        this.notifySignalClose = trycatch(async (event) => {
-            this.loggerService.log("telegramLogicService notifySignalClose", {
+        this.notifyOrderRejectOpen = trycatch(async (event) => {
+            this.loggerService.log("telegramLogicService notifyOrderRejectOpen", {
                 event,
             });
-            const markdown = await this.telegramTemplateService.getSignalCloseMarkdown(event);
+            const markdown = await this.telegramTemplateService.getOrderRejectOpenMarkdown(event);
+            if (!markdown) {
+                return;
+            }
+            await this.telegramWebService.publishNotify({
+                symbol: event.symbol,
+                markdown,
+            });
+        });
+        this.notifyOrderRejectClose = trycatch(async (event) => {
+            this.loggerService.log("telegramLogicService notifyOrderRejectClose", {
+                event,
+            });
+            const markdown = await this.telegramTemplateService.getOrderRejectCloseMarkdown(event);
+            if (!markdown) {
+                return;
+            }
+            await this.telegramWebService.publishNotify({
+                symbol: event.symbol,
+                markdown,
+            });
+        });
+        /**
+         * Post-verdict order-check CONTINUE (order_continue). Fires every live tick the
+         * order survives the check, so it is throttled via functools-kit ttl:
+         * one message per signalId per ORDER_CHECK_NOTIFY_TTL (15 minutes).
+         */
+        this.notifyOrderContinue = ttl(trycatch(async (event) => {
+            this.loggerService.log("telegramLogicService notifyOrderContinue", {
+                event,
+            });
+            const markdown = await this.telegramTemplateService.getOrderContinueMarkdown(event);
+            if (!markdown) {
+                return;
+            }
+            await this.telegramWebService.publishNotify({
+                symbol: event.symbol,
+                markdown,
+            });
+        }), {
+            key: ([event]) => event.signalId,
+            timeout: ORDER_CHECK_NOTIFY_TTL,
+        });
+        /**
+         * Post-verdict order-check STOP (order_stop). Terminal — fires once per signal,
+         * so no throttle; drops the continue throttle slot for this signalId
+         * (the signal leaves monitoring, the ttl entry would only leak otherwise).
+         */
+        this.notifyOrderStop = trycatch(async (event) => {
+            this.loggerService.log("telegramLogicService notifyOrderStop", {
+                event,
+            });
+            this.notifyOrderContinue.clear(event.signalId);
+            const markdown = await this.telegramTemplateService.getOrderStopMarkdown(event);
             if (!markdown) {
                 return;
             }
@@ -2582,26 +2659,51 @@ class TelegramLogicService {
                     return;
                 }
             });
-            const unSync = listenSync(async (event) => {
+            // Broker-CONFIRMED fills only (post-verdict orderFillSubject): a rejected or
+            // transient gate attempt never reaches this channel, so "Order Filled" is
+            // guaranteed truthful. The pre-verdict syncSubject is NOT consumed here.
+            const unOrderFill = listenOrderFill(async (event) => {
                 if (event.action === "signal-open") {
-                    // type "schedule" is a resting-order PLACEMENT, not a position open:
-                    // the user already got the "scheduled" notification from listenSignal
-                    if (event.type !== "active") {
-                        return;
-                    }
-                    await this.notifySignalOpen(event);
+                    // Both open outcomes notify: type "active" — the order opened at once
+                    // (immediate fill, no schedule phase), type "schedule" — the resting
+                    // order was placed on the exchange. Either way the broker confirmed a
+                    // real order; the template's Order field carries the type.
+                    await this.notifyOrderFillOpen(event);
+                    return;
+                }
+                if (event.action === "signal-close") {
+                    await this.notifyOrderFillClose(event);
+                    return;
+                }
+            });
+            // Terminal broker rejection (post-verdict orderRejectSubject): exactly one
+            // event per dropped order attempt — the engine consumes the rejected signal
+            // id, so this cannot repeat per-tick for the same signal. Dispatched by
+            // action to the dedicated open/close notifications (single responsibility).
+            const unOrderReject = listenOrderReject(async (event) => {
+                if (event.action === "signal-open") {
+                    await this.notifyOrderRejectOpen(event);
                     return;
                 }
                 if (event.action === "signal-close") {
-                    await this.notifySignalClose(event);
+                    await this.notifyOrderRejectClose(event);
                     return;
                 }
             });
+            // Post-verdict check decisions: CONTINUE fires every surviving tick and is
+            // throttled to one message per signalId per 15 minutes via ttl; terminal
+            // STOP fires once per signal, unthrottled.
+            const unOrderContinue = listenOrderContinue(async (event) => {
+                await this.notifyOrderContinue(event);
+            });
+            const unOrderStop = listenOrderStop(async (event) => {
+                await this.notifyOrderStop(event);
+            });
             const unSignalNotify = listenSignalNotify(async (event) => {
                 await this.notifySignalInfo(event);
             });
             const unConnect = () => this.connect.clear();
-            const unListen = compose(() => unRisk(), () => unSignal(), () => unCommit(), () => unSync(), () => unSignalNotify(), () => unConnect());
+            const unListen = compose(() => unRisk(), () => unSignal(), () => unCommit(), () => unOrderFill(), () => unOrderReject(), () => unOrderContinue(), () => unOrderStop(), () => this.notifyOrderContinue.clear(), () => unSignalNotify(), () => unConnect());
             return () => {
                 STOP_BOT_FN();
                 unListen();
@@ -2754,25 +2856,65 @@ class TelegramTemplateService {
             }
             return await RENDER_TEMPLATE_FN("average-buy.mustache", event, this);
         };
-        this.getSignalOpenMarkdown = async (event) => {
-            this.loggerService.log("telegramTemplateService getSignalOpenMarkdown", {
+        this.getOrderFillOpenMarkdown = async (event) => {
+            this.loggerService.log("telegramTemplateService getOrderFillOpenMarkdown", {
+                event,
+            });
+            const adapter = await this.getTelegramAdapter();
+            if (adapter?.getOrderFillOpenMarkdown) {
+                return await adapter.getOrderFillOpenMarkdown(event);
+            }
+            return await RENDER_TEMPLATE_FN("order-fill-open.mustache", event, this);
+        };
+        this.getOrderFillCloseMarkdown = async (event) => {
+            this.loggerService.log("telegramTemplateService getOrderFillCloseMarkdown", {
+                event,
+            });
+            const adapter = await this.getTelegramAdapter();
+            if (adapter?.getOrderFillCloseMarkdown) {
+                return await adapter.getOrderFillCloseMarkdown(event);
+            }
+            return await RENDER_TEMPLATE_FN("order-fill-close.mustache", event, this);
+        };
+        this.getOrderRejectOpenMarkdown = async (event) => {
+            this.loggerService.log("telegramTemplateService getOrderRejectOpenMarkdown", {
+                event,
+            });
+            const adapter = await this.getTelegramAdapter();
+            if (adapter?.getOrderRejectOpenMarkdown) {
+                return await adapter.getOrderRejectOpenMarkdown(event);
+            }
+            return await RENDER_TEMPLATE_FN("order-reject-open.mustache", event, this);
+        };
+        this.getOrderRejectCloseMarkdown = async (event) => {
+            this.loggerService.log("telegramTemplateService getOrderRejectCloseMarkdown", {
+                event,
+            });
+            const adapter = await this.getTelegramAdapter();
+            if (adapter?.getOrderRejectCloseMarkdown) {
+                return await adapter.getOrderRejectCloseMarkdown(event);
+            }
+            return await RENDER_TEMPLATE_FN("order-reject-close.mustache", event, this);
+        };
+        this.getOrderContinueMarkdown = async (event) => {
+            this.loggerService.log("telegramTemplateService getOrderContinueMarkdown", {
                 event,
             });
             const adapter = await this.getTelegramAdapter();
-            if (adapter?.getSignalOpenMarkdown) {
-                return await adapter.getSignalOpenMarkdown(event);
+            if (adapter?.getOrderContinueMarkdown) {
+                return await adapter.getOrderContinueMarkdown(event);
             }
-            return await RENDER_TEMPLATE_FN("signal-open.mustache", event, this);
+            return await RENDER_TEMPLATE_FN("order-continue.mustache", event, this);
         };
-        this.getSignalCloseMarkdown = async (event) => {
-            this.loggerService.log("telegramTemplateService getSignalCloseMarkdown", {
+        this.getOrderStopMarkdown = async (event) => {
+            this.loggerService.log("telegramTemplateService getOrderStopMarkdown", {
                 event,
             });
             const adapter = await this.getTelegramAdapter();
-            if (adapter?.getSignalCloseMarkdown) {
-                return await adapter.getSignalCloseMarkdown(event);
+            if (adapter?.getOrderStopMarkdown) {
+                return await adapter.getOrderStopMarkdown(event);
             }
-            return await RENDER_TEMPLATE_FN("signal-close.mustache", event, this);
+            return await RENDER_TEMPLATE_FN("order-stop.mustache", event, this);
         };
         this.getCancelScheduledMarkdown = async (event) => {
             this.loggerService.log("telegramTemplateService getCancelScheduledMarkdown", {
@@ -3502,14 +3644,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 +3659,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.5.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 +3682,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 +3699,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 +3722,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 +3740,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 +3759,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 +3778,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 +3800,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 +3814,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 +3836,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 +3850,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 +3914,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 +3970,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 +4073,7 @@ const createGracefulShutdown = (mode) => {
         process.on("SIGINT", handler);
     });
 };
-const main$a = async () => {
+const main$b = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -4007,7 +4149,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 +4160,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 +4170,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 +4181,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 +4191,7 @@ const main$8 = async () => {
     }
     listenGracefulShutdown();
 };
-main$8();
+main$9();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -4071,7 +4213,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 +4305,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 +4378,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 +4461,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 +4577,236 @@ 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,
+        gridAxes: {
+            hardStopPercent: [1, 1.5, 2, 2.5, 3, 4, 5, 7],
+            trailingTakePercent: [0.5, 1, 1.5, 2, 3, 4],
+            holdMinutes: [24 * 60, 2 * 24 * 60, 3 * 24 * 60],
+            minIdeasAligned: [1, 2, 3],
+            minAuthorTrack: [2, 3, 5],
+            minAuthorHitRate: [0.5, 0.6],
+            minWeightAligned: [0, 0.6, 1.2],
+            profitLockPercent: [0, 1.5, 2.5],
+        },
+        callbacks: {
+            onProgress: (symbol, stage, processed, total) => {
+                if (values.verbose) {
+                    console.log("onProgress", { symbol, stage, processed, total });
+                }
+            },
+            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 +5005,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 +5126,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,
+  four 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 (onProgress, 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 +5186,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 +5215,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/tv-ideas.normalized.jsonl
+  node ${ENTRY_PATH} --simulator --symbol BTCUSDT --json --output jun_2026_sweep ./assets/tv-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 +5230,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.5.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -4841,7 +5244,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.5.0"}\n`);
     process.exit(0);
 };
 main();