backtest-kit 1.11.4 → 1.11.6

package/build/index.cjs

@@ -10960,6 +10960,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 +11245,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();
+            }
+        };
     }
 }
 /**
@@ -19147,6 +19225,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 +19467,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 +19632,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 +19762,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 +19785,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 +19811,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 +19941,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 +19964,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 +19990,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,6 +20117,21 @@ class ScheduleReportService {
                 }, searchOptions);
             }
         };
+        /**
+         * 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);
@@ -19802,6 +20140,19 @@ class ScheduleReportService {
                 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 +20166,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 +20226,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 +20249,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 +20275,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 +20350,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 +20373,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 +20399,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") {
@@ -19937,6 +20454,7 @@ class HeatReportService {
                 backtest: data.backtest,
                 signalId: data.signal?.id,
                 position: data.signal?.position,
+                note: data.signal?.note,
                 pnl: data.pnl.pnlPercentage,
                 closeReason: data.closeReason,
                 openTime: data.signal?.pendingAt,
@@ -19950,6 +20468,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);
@@ -19958,6 +20491,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()) {
@@ -19972,9 +20518,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", {
@@ -20006,6 +20589,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", {
@@ -20037,6 +20627,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);
@@ -20047,6 +20652,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()) {
@@ -20060,9 +20678,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", {
@@ -20092,6 +20746,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);
@@ -20100,6 +20769,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()) {
@@ -20113,9 +20795,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", {
@@ -20149,6 +20867,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);
@@ -20157,6 +20890,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()) {