backtest-kit 1.11.5 → 1.11.7

package/build/index.cjs

@@ -10217,6 +10217,48 @@ const partial_columns = [
         format: (data) => `${data.currentPrice.toFixed(8)} USD`,
         isVisible: () => true,
     },
+    {
+        key: "priceOpen",
+        label: "Entry Price",
+        format: (data) => (data.priceOpen ? `${data.priceOpen.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "priceTakeProfit",
+        label: "Take Profit",
+        format: (data) => (data.priceTakeProfit ? `${data.priceTakeProfit.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "priceStopLoss",
+        label: "Stop Loss",
+        format: (data) => (data.priceStopLoss ? `${data.priceStopLoss.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "originalPriceTakeProfit",
+        label: "Original TP",
+        format: (data) => (data.originalPriceTakeProfit ? `${data.originalPriceTakeProfit.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "originalPriceStopLoss",
+        label: "Original SL",
+        format: (data) => (data.originalPriceStopLoss ? `${data.originalPriceStopLoss.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "totalExecuted",
+        label: "Total Executed %",
+        format: (data) => (data.totalExecuted !== undefined ? `${data.totalExecuted.toFixed(2)}%` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "note",
+        label: "Note",
+        format: (data) => data.note || "",
+        isVisible: () => GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE,
+    },
     {
         key: "timestamp",
         label: "Timestamp",
@@ -10303,6 +10345,42 @@ const breakeven_columns = [
         format: (data) => `${data.currentPrice.toFixed(8)} USD`,
         isVisible: () => true,
     },
+    {
+        key: "priceTakeProfit",
+        label: "Take Profit",
+        format: (data) => (data.priceTakeProfit ? `${data.priceTakeProfit.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "priceStopLoss",
+        label: "Stop Loss",
+        format: (data) => (data.priceStopLoss ? `${data.priceStopLoss.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "originalPriceTakeProfit",
+        label: "Original TP",
+        format: (data) => (data.originalPriceTakeProfit ? `${data.originalPriceTakeProfit.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "originalPriceStopLoss",
+        label: "Original SL",
+        format: (data) => (data.originalPriceStopLoss ? `${data.originalPriceStopLoss.toFixed(8)} USD` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "totalExecuted",
+        label: "Total Executed %",
+        format: (data) => (data.totalExecuted !== undefined ? `${data.totalExecuted.toFixed(2)}%` : "N/A"),
+        isVisible: () => true,
+    },
+    {
+        key: "note",
+        label: "Note",
+        format: (data) => data.note || "",
+        isVisible: () => GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE,
+    },
     {
         key: "timestamp",
         label: "Timestamp",
@@ -10960,6 +11038,7 @@ const DEFAULT_COLUMNS = Object.freeze({ ...COLUMN_CONFIG });
 
 var _a$1, _b$1, _c$1;
 const MARKDOWN_METHOD_NAME_ENABLE = "MarkdownUtils.enable";
+const MARKDOWN_METHOD_NAME_DISABLE = "MarkdownUtils.disable";
 const MARKDOWN_METHOD_NAME_USE_ADAPTER = "MarkdownAdapter.useMarkdownAdapter";
 const WAIT_FOR_INIT_SYMBOL$1 = Symbol("wait-for-init");
 const WRITE_SAFE_SYMBOL$1 = Symbol("write-safe");
@@ -11244,6 +11323,83 @@ class MarkdownUtils {
             }
             return functoolsKit.compose(...unList.map((un) => () => void un()));
         };
+        /**
+         * Disables markdown report services selectively.
+         *
+         * Unsubscribes from specified markdown services to stop report generation.
+         * Use this method to stop markdown report generation for specific services while keeping others active.
+         *
+         * Each disabled service will:
+         * - Stop listening to events immediately
+         * - Stop accumulating data for reports
+         * - Stop generating markdown files
+         * - Free up event listener and memory resources
+         *
+         * Unlike enable(), this method does NOT return an unsubscribe function.
+         * Services are unsubscribed immediately upon calling this method.
+         *
+         * @param config - Service configuration object specifying which services to disable. Defaults to disabling all services.
+         * @param config.backtest - Disable backtest result reports with full trade history
+         * @param config.breakeven - Disable breakeven event tracking
+         * @param config.partial - Disable partial profit/loss event tracking
+         * @param config.heat - Disable portfolio heatmap analysis
+         * @param config.walker - Disable walker strategy comparison reports
+         * @param config.performance - Disable performance bottleneck analysis
+         * @param config.risk - Disable risk rejection tracking
+         * @param config.schedule - Disable scheduled signal tracking
+         * @param config.live - Disable live trading event reports
+         *
+         * @example
+         * ```typescript
+         * import { Markdown } from "backtest-kit";
+         *
+         * // Disable specific services
+         * Markdown.disable({ backtest: true, walker: true });
+         *
+         * // Disable all services
+         * Markdown.disable();
+         * ```
+         */
+        this.disable = ({ backtest: bt$1 = false, breakeven = false, heat = false, live = false, partial = false, performance = false, risk = false, schedule = false, walker = false, } = WILDCARD_TARGET$1) => {
+            bt.loggerService.debug(MARKDOWN_METHOD_NAME_DISABLE, {
+                backtest: bt$1,
+                breakeven,
+                heat,
+                live,
+                partial,
+                performance,
+                risk,
+                schedule,
+                walker,
+            });
+            if (bt$1) {
+                bt.backtestMarkdownService.unsubscribe();
+            }
+            if (breakeven) {
+                bt.breakevenMarkdownService.unsubscribe();
+            }
+            if (heat) {
+                bt.heatMarkdownService.unsubscribe();
+            }
+            if (live) {
+                bt.liveMarkdownService.unsubscribe();
+            }
+            if (partial) {
+                bt.partialMarkdownService.unsubscribe();
+            }
+            if (performance) {
+                bt.performanceMarkdownService.unsubscribe();
+            }
+            if (risk) {
+                bt.riskMarkdownService.unsubscribe();
+            }
+            if (schedule) {
+                bt.scheduleMarkdownService.unsubscribe();
+            }
+            if (walker) {
+                bt.walkerMarkdownService.unsubscribe();
+            }
+        };
     }
 }
 /**
@@ -16824,6 +16980,13 @@ let ReportStorage$2 = class ReportStorage {
             position: data.position,
             currentPrice,
             level,
+            priceOpen: data.priceOpen,
+            priceTakeProfit: data.priceTakeProfit,
+            priceStopLoss: data.priceStopLoss,
+            originalPriceTakeProfit: data.originalPriceTakeProfit,
+            originalPriceStopLoss: data.originalPriceStopLoss,
+            totalExecuted: data.totalExecuted,
+            note: data.note,
             backtest,
         });
         // Trim queue if exceeded MAX_EVENTS
@@ -16849,6 +17012,13 @@ let ReportStorage$2 = class ReportStorage {
             position: data.position,
             currentPrice,
             level,
+            priceOpen: data.priceOpen,
+            priceTakeProfit: data.priceTakeProfit,
+            priceStopLoss: data.priceStopLoss,
+            originalPriceTakeProfit: data.originalPriceTakeProfit,
+            originalPriceStopLoss: data.originalPriceStopLoss,
+            totalExecuted: data.totalExecuted,
+            note: data.note,
             backtest,
         });
         // Trim queue if exceeded MAX_EVENTS
@@ -17901,7 +18071,7 @@ let ReportStorage$1 = class ReportStorage {
     /**
      * Adds a breakeven event to the storage.
      *
-     * @param data - Signal row data
+     * @param data - Signal row data with original prices
      * @param currentPrice - Current market price when breakeven was reached
      * @param backtest - True if backtest mode
      * @param timestamp - Event timestamp in milliseconds
@@ -17915,6 +18085,12 @@ let ReportStorage$1 = class ReportStorage {
             position: data.position,
             currentPrice,
             priceOpen: data.priceOpen,
+            priceTakeProfit: data.priceTakeProfit,
+            priceStopLoss: data.priceStopLoss,
+            originalPriceTakeProfit: data.originalPriceTakeProfit,
+            originalPriceStopLoss: data.originalPriceStopLoss,
+            totalExecuted: data.totalExecuted,
+            note: data.note,
             backtest,
         });
         // Trim queue if exceeded MAX_EVENTS
@@ -19147,6 +19323,7 @@ const REPORT_BASE_METHOD_NAME_WRITE = "ReportBase.write";
 const REPORT_UTILS_METHOD_NAME_USE_REPORT_ADAPTER = "ReportUtils.useReportAdapter";
 const REPORT_UTILS_METHOD_NAME_WRITE_DATA = "ReportUtils.writeReportData";
 const REPORT_UTILS_METHOD_NAME_ENABLE = "ReportUtils.enable";
+const REPORT_UTILS_METHOD_NAME_DISABLE = "ReportUtils.disable";
 const REPORT_UTILS_METHOD_NAME_USE_DUMMY = "ReportUtils.useDummy";
 const REPORT_UTILS_METHOD_NAME_USE_JSONL = "ReportUtils.useJsonl";
 const WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
@@ -19388,6 +19565,82 @@ class ReportUtils {
             }
             return functoolsKit.compose(...unList.map((un) => () => void un()));
         };
+        /**
+         * Disables report services selectively.
+         *
+         * Unsubscribes from specified report services to stop event logging.
+         * Use this method to stop JSONL logging for specific services while keeping others active.
+         *
+         * Each disabled service will:
+         * - Stop listening to events immediately
+         * - Stop writing to JSONL files
+         * - Free up event listener resources
+         *
+         * Unlike enable(), this method does NOT return an unsubscribe function.
+         * Services are unsubscribed immediately upon calling this method.
+         *
+         * @param config - Service configuration object specifying which services to disable. Defaults to disabling all services.
+         * @param config.backtest - Disable backtest closed signal logging
+         * @param config.breakeven - Disable breakeven event logging
+         * @param config.partial - Disable partial close event logging
+         * @param config.heat - Disable heatmap data logging
+         * @param config.walker - Disable walker iteration logging
+         * @param config.performance - Disable performance metrics logging
+         * @param config.risk - Disable risk rejection logging
+         * @param config.schedule - Disable scheduled signal logging
+         * @param config.live - Disable live trading event logging
+         *
+         * @example
+         * ```typescript
+         * import { Report } from "backtest-kit";
+         *
+         * // Disable specific services
+         * Report.disable({ backtest: true, live: true });
+         *
+         * // Disable all services
+         * Report.disable();
+         * ```
+         */
+        this.disable = ({ backtest: bt$1 = false, breakeven = false, heat = false, live = false, partial = false, performance = false, risk = false, schedule = false, walker = false, } = WILDCARD_TARGET) => {
+            bt.loggerService.debug(REPORT_UTILS_METHOD_NAME_DISABLE, {
+                backtest: bt$1,
+                breakeven,
+                heat,
+                live,
+                partial,
+                performance,
+                risk,
+                schedule,
+                walker,
+            });
+            if (bt$1) {
+                bt.backtestReportService.unsubscribe();
+            }
+            if (breakeven) {
+                bt.breakevenReportService.unsubscribe();
+            }
+            if (heat) {
+                bt.heatReportService.unsubscribe();
+            }
+            if (live) {
+                bt.liveReportService.unsubscribe();
+            }
+            if (partial) {
+                bt.partialReportService.unsubscribe();
+            }
+            if (performance) {
+                bt.performanceReportService.unsubscribe();
+            }
+            if (risk) {
+                bt.riskReportService.unsubscribe();
+            }
+            if (schedule) {
+                bt.scheduleReportService.unsubscribe();
+            }
+            if (walker) {
+                bt.walkerReportService.unsubscribe();
+            }
+        };
     }
 }
 /**
@@ -19477,9 +19730,46 @@ const Report = new ReportAdapter();
 const BACKTEST_REPORT_METHOD_NAME_SUBSCRIBE = "BacktestReportService.subscribe";
 const BACKTEST_REPORT_METHOD_NAME_UNSUBSCRIBE = "BacktestReportService.unsubscribe";
 const BACKTEST_REPORT_METHOD_NAME_TICK = "BacktestReportService.tick";
+/**
+ * Service for logging backtest strategy tick events to SQLite database.
+ *
+ * Captures all backtest signal lifecycle events (idle, opened, active, closed)
+ * and stores them in the Report database for analysis and debugging.
+ *
+ * Features:
+ * - Listens to backtest signal events via signalBacktestEmitter
+ * - Logs all tick event types with full signal details
+ * - Stores events in Report.writeData() for persistence
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { BacktestReportService } from "backtest-kit";
+ *
+ * const reportService = new BacktestReportService();
+ *
+ * // Subscribe to backtest events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run backtest...
+ * // Events are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class BacktestReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes backtest tick events and logs them to the database.
+         * Handles all event types: idle, opened, active, closed.
+         *
+         * @param data - Backtest tick result with signal lifecycle information
+         *
+         * @internal
+         */
         this.tick = async (data) => {
             this.loggerService.log(BACKTEST_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
@@ -19570,6 +19860,21 @@ class BacktestReportService {
                 }, { ...searchOptions, signalId: data.signal?.id });
             }
         };
+        /**
+         * Subscribes to backtest signal emitter to receive tick events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving backtest events
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(BACKTEST_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = signalBacktestEmitter.subscribe(this.tick);
@@ -19578,6 +19883,19 @@ class BacktestReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from backtest signal emitter to stop receiving tick events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(BACKTEST_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -19591,9 +19909,46 @@ class BacktestReportService {
 const LIVE_REPORT_METHOD_NAME_SUBSCRIBE = "LiveReportService.subscribe";
 const LIVE_REPORT_METHOD_NAME_UNSUBSCRIBE = "LiveReportService.unsubscribe";
 const LIVE_REPORT_METHOD_NAME_TICK = "LiveReportService.tick";
+/**
+ * Service for logging live trading strategy tick events to SQLite database.
+ *
+ * Captures all live trading signal lifecycle events (idle, opened, active, closed)
+ * and stores them in the Report database for real-time monitoring and analysis.
+ *
+ * Features:
+ * - Listens to live signal events via signalLiveEmitter
+ * - Logs all tick event types with full signal details
+ * - Stores events in Report.writeData() for persistence
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { LiveReportService } from "backtest-kit";
+ *
+ * const reportService = new LiveReportService();
+ *
+ * // Subscribe to live trading events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run live trading...
+ * // Events are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class LiveReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes live trading tick events and logs them to the database.
+         * Handles all event types: idle, opened, active, closed.
+         *
+         * @param data - Live trading tick result with signal lifecycle information
+         *
+         * @internal
+         */
         this.tick = async (data) => {
             this.loggerService.log(LIVE_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
@@ -19684,6 +20039,21 @@ class LiveReportService {
                 }, { ...searchOptions, signalId: data.signal?.id });
             }
         };
+        /**
+         * Subscribes to live signal emitter to receive tick events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving live trading events
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(LIVE_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = signalLiveEmitter.subscribe(this.tick);
@@ -19692,6 +20062,19 @@ class LiveReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from live signal emitter to stop receiving tick events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(LIVE_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -19705,9 +20088,47 @@ class LiveReportService {
 const SCHEDULE_REPORT_METHOD_NAME_SUBSCRIBE = "ScheduleReportService.subscribe";
 const SCHEDULE_REPORT_METHOD_NAME_UNSUBSCRIBE = "ScheduleReportService.unsubscribe";
 const SCHEDULE_REPORT_METHOD_NAME_TICK = "ScheduleReportService.tick";
+/**
+ * Service for logging scheduled signal events to SQLite database.
+ *
+ * Captures all scheduled signal lifecycle events (scheduled, opened, cancelled)
+ * and stores them in the Report database for tracking delayed order execution.
+ *
+ * Features:
+ * - Listens to signal events via signalEmitter
+ * - Logs scheduled, opened (from scheduled), and cancelled events
+ * - Calculates duration between scheduling and execution/cancellation
+ * - Stores events in Report.writeData() for schedule tracking
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { ScheduleReportService } from "backtest-kit";
+ *
+ * const reportService = new ScheduleReportService();
+ *
+ * // Subscribe to scheduled signal events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run strategy with scheduled orders...
+ * // Scheduled events are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class ScheduleReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes signal tick events and logs scheduled signal lifecycle to the database.
+         * Handles scheduled, opened (from scheduled), and cancelled event types.
+         *
+         * @param data - Strategy tick result with signal lifecycle information
+         *
+         * @internal
+         */
         this.tick = async (data) => {
             this.loggerService.log(SCHEDULE_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
@@ -19794,14 +20215,42 @@ class ScheduleReportService {
                 }, searchOptions);
             }
         };
-        this.subscribe = functoolsKit.singleshot(() => {
-            this.loggerService.log(SCHEDULE_REPORT_METHOD_NAME_SUBSCRIBE);
-            const unsubscribe = signalEmitter.subscribe(this.tick);
-            return () => {
-                this.subscribe.clear();
-                unsubscribe();
-            };
+        /**
+         * Subscribes to signal emitter to receive scheduled signal events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving scheduled signal events
+         *
+         * @example
+         * ```typescript
+         * const service = new ScheduleReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
+        this.subscribe = functoolsKit.singleshot(() => {
+            this.loggerService.log(SCHEDULE_REPORT_METHOD_NAME_SUBSCRIBE);
+            const unsubscribe = signalEmitter.subscribe(this.tick);
+            return () => {
+                this.subscribe.clear();
+                unsubscribe();
+            };
         });
+        /**
+         * Unsubscribes from signal emitter to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new ScheduleReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(SCHEDULE_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -19815,9 +20264,45 @@ class ScheduleReportService {
 const PERFORMANCE_REPORT_METHOD_NAME_SUBSCRIBE = "PerformanceReportService.subscribe";
 const PERFORMANCE_REPORT_METHOD_NAME_UNSUBSCRIBE = "PerformanceReportService.unsubscribe";
 const PERFORMANCE_REPORT_METHOD_NAME_TRACK = "PerformanceReportService.track";
+/**
+ * Service for logging performance metrics to SQLite database.
+ *
+ * Captures all performance timing events from strategy execution
+ * and stores them in the Report database for bottleneck analysis and optimization.
+ *
+ * Features:
+ * - Listens to performance events via performanceEmitter
+ * - Logs all timing metrics with duration and metadata
+ * - Stores events in Report.writeData() for performance analysis
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { PerformanceReportService } from "backtest-kit";
+ *
+ * const reportService = new PerformanceReportService();
+ *
+ * // Subscribe to performance events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run strategy...
+ * // Performance metrics are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class PerformanceReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes performance tracking events and logs them to the database.
+         *
+         * @param event - Performance contract with timing and metric information
+         *
+         * @internal
+         */
         this.track = async (event) => {
             this.loggerService.log(PERFORMANCE_REPORT_METHOD_NAME_TRACK, { event });
             await Report.writeData("performance", {
@@ -19839,6 +20324,21 @@ class PerformanceReportService {
                 walkerName: "",
             });
         };
+        /**
+         * Subscribes to performance emitter to receive timing events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving performance events
+         *
+         * @example
+         * ```typescript
+         * const service = new PerformanceReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(PERFORMANCE_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = performanceEmitter.subscribe(this.track);
@@ -19847,6 +20347,19 @@ class PerformanceReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from performance emitter to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new PerformanceReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(PERFORMANCE_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -19860,9 +20373,46 @@ class PerformanceReportService {
 const WALKER_REPORT_METHOD_NAME_SUBSCRIBE = "WalkerReportService.subscribe";
 const WALKER_REPORT_METHOD_NAME_UNSUBSCRIBE = "WalkerReportService.unsubscribe";
 const WALKER_REPORT_METHOD_NAME_TICK = "WalkerReportService.tick";
+/**
+ * Service for logging walker optimization progress to SQLite database.
+ *
+ * Captures walker strategy optimization results and stores them in the Report database
+ * for tracking parameter optimization and comparing strategy performance.
+ *
+ * Features:
+ * - Listens to walker events via walkerEmitter
+ * - Logs each strategy test result with metrics and statistics
+ * - Tracks best strategy and optimization progress
+ * - Stores events in Report.writeData() for optimization analysis
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { WalkerReportService } from "backtest-kit";
+ *
+ * const reportService = new WalkerReportService();
+ *
+ * // Subscribe to walker optimization events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run walker optimization...
+ * // Each strategy result is automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class WalkerReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes walker optimization events and logs them to the database.
+         *
+         * @param data - Walker contract with strategy optimization results
+         *
+         * @internal
+         */
         this.tick = async (data) => {
             this.loggerService.log(WALKER_REPORT_METHOD_NAME_TICK, { data });
             await Report.writeData("walker", {
@@ -19898,6 +20448,21 @@ class WalkerReportService {
                 walkerName: data.walkerName,
             });
         };
+        /**
+         * Subscribes to walker emitter to receive optimization progress events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving walker optimization events
+         *
+         * @example
+         * ```typescript
+         * const service = new WalkerReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(WALKER_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = walkerEmitter.subscribe(this.tick);
@@ -19906,6 +20471,19 @@ class WalkerReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from walker emitter to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new WalkerReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(WALKER_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -19919,9 +20497,46 @@ class WalkerReportService {
 const HEAT_REPORT_METHOD_NAME_SUBSCRIBE = "HeatReportService.subscribe";
 const HEAT_REPORT_METHOD_NAME_UNSUBSCRIBE = "HeatReportService.unsubscribe";
 const HEAT_REPORT_METHOD_NAME_TICK = "HeatReportService.tick";
+/**
+ * Service for logging heatmap (closed signals) events to SQLite database.
+ *
+ * Captures closed signal events across all symbols for portfolio-wide
+ * heatmap analysis and stores them in the Report database.
+ *
+ * Features:
+ * - Listens to signal events via signalEmitter
+ * - Logs only closed signals with PNL data
+ * - Stores events in Report.writeData() for heatmap generation
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { HeatReportService } from "backtest-kit";
+ *
+ * const reportService = new HeatReportService();
+ *
+ * // Subscribe to signal events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run strategy...
+ * // Closed signals are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class HeatReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes signal tick events and logs closed signals to the database.
+         * Only processes closed signals - other actions are ignored.
+         *
+         * @param data - Strategy tick result with signal lifecycle information
+         *
+         * @internal
+         */
         this.tick = async (data) => {
             this.loggerService.log(HEAT_REPORT_METHOD_NAME_TICK, { data });
             if (data.action !== "closed") {
@@ -19951,6 +20566,21 @@ class HeatReportService {
                 walkerName: "",
             });
         };
+        /**
+         * Subscribes to signal emitter to receive closed signal events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving signal events
+         *
+         * @example
+         * ```typescript
+         * const service = new HeatReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(HEAT_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = signalEmitter.subscribe(this.tick);
@@ -19959,6 +20589,19 @@ class HeatReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from signal emitter to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new HeatReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(HEAT_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -19973,9 +20616,46 @@ const PARTIAL_REPORT_METHOD_NAME_SUBSCRIBE = "PartialReportService.subscribe";
 const PARTIAL_REPORT_METHOD_NAME_UNSUBSCRIBE = "PartialReportService.unsubscribe";
 const PARTIAL_REPORT_METHOD_NAME_TICK_PROFIT = "PartialReportService.tickProfit";
 const PARTIAL_REPORT_METHOD_NAME_TICK_LOSS = "PartialReportService.tickLoss";
+/**
+ * Service for logging partial profit/loss events to SQLite database.
+ *
+ * Captures all partial position exit events (profit and loss levels)
+ * and stores them in the Report database for tracking partial closures.
+ *
+ * Features:
+ * - Listens to partial profit events via partialProfitSubject
+ * - Listens to partial loss events via partialLossSubject
+ * - Logs all partial exit events with level and price information
+ * - Stores events in Report.writeData() for persistence
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { PartialReportService } from "backtest-kit";
+ *
+ * const reportService = new PartialReportService();
+ *
+ * // Subscribe to partial events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run strategy with partial exits...
+ * // Partial events are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class PartialReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes partial profit events and logs them to the database.
+         *
+         * @param data - Partial profit event data with signal, level, and price information
+         *
+         * @internal
+         */
         this.tickProfit = async (data) => {
             this.loggerService.log(PARTIAL_REPORT_METHOD_NAME_TICK_PROFIT, { data });
             await Report.writeData("partial", {
@@ -19993,6 +20673,9 @@ class PartialReportService {
                 priceOpen: data.data.priceOpen,
                 priceTakeProfit: data.data.priceTakeProfit,
                 priceStopLoss: data.data.priceStopLoss,
+                originalPriceTakeProfit: data.data.originalPriceTakeProfit,
+                originalPriceStopLoss: data.data.originalPriceStopLoss,
+                totalExecuted: data.data.totalExecuted,
                 _partial: data.data._partial,
                 note: data.data.note,
                 pendingAt: data.data.pendingAt,
@@ -20007,6 +20690,13 @@ class PartialReportService {
                 walkerName: "",
             });
         };
+        /**
+         * Processes partial loss events and logs them to the database.
+         *
+         * @param data - Partial loss event data with signal, level, and price information
+         *
+         * @internal
+         */
         this.tickLoss = async (data) => {
             this.loggerService.log(PARTIAL_REPORT_METHOD_NAME_TICK_LOSS, { data });
             await Report.writeData("partial", {
@@ -20024,6 +20714,9 @@ class PartialReportService {
                 priceOpen: data.data.priceOpen,
                 priceTakeProfit: data.data.priceTakeProfit,
                 priceStopLoss: data.data.priceStopLoss,
+                originalPriceTakeProfit: data.data.originalPriceTakeProfit,
+                originalPriceStopLoss: data.data.originalPriceStopLoss,
+                totalExecuted: data.data.totalExecuted,
                 _partial: data.data._partial,
                 note: data.data.note,
                 pendingAt: data.data.pendingAt,
@@ -20038,6 +20731,21 @@ class PartialReportService {
                 walkerName: "",
             });
         };
+        /**
+         * Subscribes to partial profit/loss emitters to receive partial exit events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving partial events
+         *
+         * @example
+         * ```typescript
+         * const service = new PartialReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(PARTIAL_REPORT_METHOD_NAME_SUBSCRIBE);
             const unProfit = partialProfitSubject.subscribe(this.tickProfit);
@@ -20048,6 +20756,19 @@ class PartialReportService {
                 unLoss();
             };
         });
+        /**
+         * Unsubscribes from partial profit/loss emitters to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new PartialReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(PARTIAL_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -20061,9 +20782,45 @@ class PartialReportService {
 const BREAKEVEN_REPORT_METHOD_NAME_SUBSCRIBE = "BreakevenReportService.subscribe";
 const BREAKEVEN_REPORT_METHOD_NAME_UNSUBSCRIBE = "BreakevenReportService.unsubscribe";
 const BREAKEVEN_REPORT_METHOD_NAME_TICK = "BreakevenReportService.tickBreakeven";
+/**
+ * Service for logging breakeven events to SQLite database.
+ *
+ * Captures all breakeven events (when signal reaches breakeven point)
+ * and stores them in the Report database for analysis and tracking.
+ *
+ * Features:
+ * - Listens to breakeven events via breakevenSubject
+ * - Logs all breakeven achievements with full signal details
+ * - Stores events in Report.writeData() for persistence
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { BreakevenReportService } from "backtest-kit";
+ *
+ * const reportService = new BreakevenReportService();
+ *
+ * // Subscribe to breakeven events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run strategy...
+ * // Breakeven events are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class BreakevenReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes breakeven events and logs them to the database.
+         *
+         * @param data - Breakeven event data with signal and price information
+         *
+         * @internal
+         */
         this.tickBreakeven = async (data) => {
             this.loggerService.log(BREAKEVEN_REPORT_METHOD_NAME_TICK, { data });
             await Report.writeData("breakeven", {
@@ -20079,6 +20836,9 @@ class BreakevenReportService {
                 priceOpen: data.data.priceOpen,
                 priceTakeProfit: data.data.priceTakeProfit,
                 priceStopLoss: data.data.priceStopLoss,
+                originalPriceTakeProfit: data.data.originalPriceTakeProfit,
+                originalPriceStopLoss: data.data.originalPriceStopLoss,
+                totalExecuted: data.data.totalExecuted,
                 _partial: data.data._partial,
                 note: data.data.note,
                 pendingAt: data.data.pendingAt,
@@ -20093,6 +20853,21 @@ class BreakevenReportService {
                 walkerName: "",
             });
         };
+        /**
+         * Subscribes to breakeven signal emitter to receive breakeven events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving breakeven events
+         *
+         * @example
+         * ```typescript
+         * const service = new BreakevenReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(BREAKEVEN_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = breakevenSubject.subscribe(this.tickBreakeven);
@@ -20101,6 +20876,19 @@ class BreakevenReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from breakeven signal emitter to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new BreakevenReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(BREAKEVEN_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {
@@ -20114,9 +20902,45 @@ class BreakevenReportService {
 const RISK_REPORT_METHOD_NAME_SUBSCRIBE = "RiskReportService.subscribe";
 const RISK_REPORT_METHOD_NAME_UNSUBSCRIBE = "RiskReportService.unsubscribe";
 const RISK_REPORT_METHOD_NAME_TICK = "RiskReportService.tickRejection";
+/**
+ * Service for logging risk rejection events to SQLite database.
+ *
+ * Captures all signal rejection events from the risk management system
+ * and stores them in the Report database for risk analysis and auditing.
+ *
+ * Features:
+ * - Listens to risk rejection events via riskSubject
+ * - Logs all rejected signals with reason and pending signal details
+ * - Stores events in Report.writeData() for risk tracking
+ * - Protected against multiple subscriptions using singleshot
+ *
+ * @example
+ * ```typescript
+ * import { RiskReportService } from "backtest-kit";
+ *
+ * const reportService = new RiskReportService();
+ *
+ * // Subscribe to risk rejection events
+ * const unsubscribe = reportService.subscribe();
+ *
+ * // Run strategy with risk management...
+ * // Rejection events are automatically logged
+ *
+ * // Later: unsubscribe
+ * await reportService.unsubscribe();
+ * ```
+ */
 class RiskReportService {
     constructor() {
+        /** Logger service for debug output */
         this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Processes risk rejection events and logs them to the database.
+         *
+         * @param data - Risk event with rejection reason and pending signal information
+         *
+         * @internal
+         */
         this.tickRejection = async (data) => {
             this.loggerService.log(RISK_REPORT_METHOD_NAME_TICK, { data });
             await Report.writeData("risk", {
@@ -20150,6 +20974,21 @@ class RiskReportService {
                 walkerName: "",
             });
         };
+        /**
+         * Subscribes to risk rejection emitter to receive rejection events.
+         * Protected against multiple subscriptions.
+         * Returns an unsubscribe function to stop receiving events.
+         *
+         * @returns Unsubscribe function to stop receiving risk rejection events
+         *
+         * @example
+         * ```typescript
+         * const service = new RiskReportService();
+         * const unsubscribe = service.subscribe();
+         * // ... later
+         * unsubscribe();
+         * ```
+         */
         this.subscribe = functoolsKit.singleshot(() => {
             this.loggerService.log(RISK_REPORT_METHOD_NAME_SUBSCRIBE);
             const unsubscribe = riskSubject.subscribe(this.tickRejection);
@@ -20158,6 +20997,19 @@ class RiskReportService {
                 unsubscribe();
             };
         });
+        /**
+         * Unsubscribes from risk rejection emitter to stop receiving events.
+         * Calls the unsubscribe function returned by subscribe().
+         * If not subscribed, does nothing.
+         *
+         * @example
+         * ```typescript
+         * const service = new RiskReportService();
+         * service.subscribe();
+         * // ... later
+         * await service.unsubscribe();
+         * ```
+         */
         this.unsubscribe = async () => {
             this.loggerService.log(RISK_REPORT_METHOD_NAME_UNSUBSCRIBE);
             if (this.subscribe.hasValue()) {