@tradejs/node 2.0.19 → 2.0.20

package/dist/backtest.js

@@ -6513,6 +6513,7 @@ var createBacktestProgress = ({
 // src/backtest/session.ts
 var import_types2 = require("@tradejs/types");
 var import_ai3 = require("@tradejs/infra/ai");
+var import_coreResearch = require("@tradejs/infra/coreResearch");
 var import_ml3 = require("@tradejs/infra/ml");
 
 // src/executionCosts.ts
@@ -7611,6 +7612,37 @@ var createTestConnector = (connector, context) => {
   };
 };
 
+// src/backtest/researchTrace.ts
+var asRecord2 = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+var findSetupKey = (value, depth = 0) => {
+  if (depth > 5) return null;
+  const record = asRecord2(value);
+  if (!record) return null;
+  for (const key of ["setupIdentity", "setupId", "patternId", "candidateId"]) {
+    const candidate = record[key];
+    if (typeof candidate === "string" && candidate.trim() || typeof candidate === "number" && Number.isFinite(candidate)) {
+      return `${key}:${String(candidate)}`;
+    }
+  }
+  for (const [key, nested] of Object.entries(record)) {
+    if (/context|signal|setup|pattern|candidate|strategy/i.test(key) && nested != null) {
+      const found = findSetupKey(nested, depth + 1);
+      if (found) return found;
+    }
+  }
+  return null;
+};
+var resolveCoreResearchSetupIdentity = (signal) => {
+  const strategyKey = findSetupKey(signal.additionalIndicators);
+  return strategyKey ? {
+    setupIdentity: `${signal.strategy}|${signal.symbol}|${signal.direction}|${strategyKey}`,
+    setupIdentitySource: "strategy-context"
+  } : {
+    setupIdentity: `${signal.strategy}|${signal.symbol}|${signal.direction}|${signal.timestamp}`,
+    setupIdentitySource: "signal-time-fallback"
+  };
+};
+
 // src/backtest/session.ts
 var createWarningCounts = () => ({
   [import_types2.BACKTEST_WARNING_CODES.TAKE_PROFIT_CROSSED_BEFORE_ENTRY]: 0
@@ -7700,7 +7732,7 @@ var createBacktestSession = async ({
   const testConnector = createTestConnector(connector, {
     userName: test.userName,
     mlEnabled: test.ml,
-    aiEnabled: test.ai,
+    aiEnabled: Boolean(test.ai || test.researchTrace),
     fastMode: test.fast,
     instrument,
     executionCostModel,
@@ -7737,11 +7769,18 @@ var createBacktestSession = async ({
   );
   const pendingMlPayloadBySignalId = /* @__PURE__ */ new Map();
   const pendingAiRowBySignalId = /* @__PURE__ */ new Map();
+  const pendingResearchSetupBySignalId = /* @__PURE__ */ new Map();
+  const researchSkipCounts = /* @__PURE__ */ new Map();
+  const researchEventCounts = /* @__PURE__ */ new Map();
   const warningCounts = createWarningCounts();
   const replayEvaluations = test.collectReplaySignalEvaluations ? [] : null;
   const chunkId = test.chunkId ?? "single";
   const processSignal = async (signal, candle) => {
     recordSignalWarning(warningCounts, signal);
+    if (test.researchTrace && typeof signal === "string") {
+      const reason = signal.trim() || "NO_SIGNAL";
+      researchSkipCounts.set(reason, (researchSkipCounts.get(reason) ?? 0) + 1);
+    }
     if (typeof signal === "string" && signal.startsWith("BACKTEST_ENTRY_DELAY_")) {
       return;
     }
@@ -7758,6 +7797,32 @@ var createBacktestSession = async ({
         onStageStart: monitor.contextStage
       });
     }
+    if (test.researchTrace && signal && typeof signal !== "string" && signal.signalId) {
+      const identity = resolveCoreResearchSetupIdentity(signal);
+      pendingResearchSetupBySignalId.set(signal.signalId, identity);
+      await (0, import_coreResearch.appendCoreResearchTraceEvent)({
+        strategyName: test.strategyName,
+        chunkId,
+        event: {
+          schema: "tradejs-core-research-trace/v1",
+          event: signal.orderStatus === "failed" || signal.orderStatus === "skipped" ? "entry_rejected" : "signal_emitted",
+          timestamp: signal.timestamp,
+          strategy: signal.strategy || test.strategyName,
+          symbol: signal.symbol || test.symbol,
+          direction: signal.direction,
+          signalId: signal.signalId,
+          configId: test.configId,
+          backtestRunId: test.backtestRunId,
+          backtestTestKey: test.backtestTestKey,
+          ...identity
+        }
+      });
+      const traceEvent = signal.orderStatus === "failed" || signal.orderStatus === "skipped" ? "entry_rejected" : "signal_emitted";
+      researchEventCounts.set(
+        traceEvent,
+        (researchEventCounts.get(traceEvent) ?? 0) + 1
+      );
+    }
     if (test.ml && signal && typeof signal !== "string" && signal.signalId) {
       pendingMlPayloadBySignalId.set(
         signal.signalId,
@@ -7795,7 +7860,7 @@ var createBacktestSession = async ({
     }
   };
   const flush = async () => {
-    if (!test.ml && !test.ai) return;
+    if (!test.ml && !test.ai && !test.researchTrace) return;
     const batch = await testConnector.drainMlResultsBatch();
     for (const resultRecord of batch) {
       const payload = pendingMlPayloadBySignalId.get(resultRecord.signalId);
@@ -7824,9 +7889,63 @@ var createBacktestSession = async ({
             ...rowBase,
             payload: buildAiPayload(aiSignal),
             profit: resultRecord.profit,
-            tradeResult: resultRecord.tradeResult
+            tradeResult: resultRecord.tradeResult,
+            research: {
+              schema: "tradejs-core-research-row/v1",
+              ...resolveCoreResearchSetupIdentity(aiSignal)
+            }
+          }
+        });
+      }
+      const researchSetup = pendingResearchSetupBySignalId.get(
+        resultRecord.signalId
+      );
+      if (test.researchTrace && researchSetup && resultRecord.tradeResult) {
+        pendingResearchSetupBySignalId.delete(resultRecord.signalId);
+        await (0, import_coreResearch.appendCoreResearchTraceEvent)({
+          strategyName: test.strategyName,
+          chunkId,
+          event: {
+            schema: "tradejs-core-research-trace/v1",
+            event: "entry_executed",
+            timestamp: resultRecord.tradeResult.entryTimestamp,
+            strategy: test.strategyName,
+            symbol: test.symbol,
+            direction: resultRecord.tradeResult.direction,
+            signalId: resultRecord.signalId,
+            configId: test.configId,
+            backtestRunId: test.backtestRunId,
+            backtestTestKey: test.backtestTestKey,
+            ...researchSetup
           }
         });
+        researchEventCounts.set(
+          "entry_executed",
+          (researchEventCounts.get("entry_executed") ?? 0) + 1
+        );
+        await (0, import_coreResearch.appendCoreResearchTraceEvent)({
+          strategyName: test.strategyName,
+          chunkId,
+          event: {
+            schema: "tradejs-core-research-trace/v1",
+            event: "position_exited",
+            timestamp: resultRecord.tradeResult.exitTimestamp,
+            strategy: test.strategyName,
+            symbol: test.symbol,
+            direction: resultRecord.tradeResult.direction,
+            signalId: resultRecord.signalId,
+            configId: test.configId,
+            backtestRunId: test.backtestRunId,
+            backtestTestKey: test.backtestTestKey,
+            netProfit: resultRecord.tradeResult.netProfit,
+            exitReason: resultRecord.tradeResult.exitReason,
+            ...researchSetup
+          }
+        });
+        researchEventCounts.set(
+          "position_exited",
+          (researchEventCounts.get("position_exited") ?? 0) + 1
+        );
       }
     }
   };
@@ -7860,15 +7979,41 @@ var createBacktestSession = async ({
     flush: () => monitor.run("flush closed results", flush),
     result: async () => {
       await monitor.run("flush closed results", flush);
+      if (test.researchTrace) {
+        await (0, import_coreResearch.appendCoreResearchTraceEvent)({
+          strategyName: test.strategyName,
+          chunkId,
+          event: {
+            schema: "tradejs-core-research-trace/v1",
+            event: "skip_summary",
+            timestamp: test.options.end ?? test.options.start ?? 0,
+            strategy: test.strategyName,
+            symbol: test.symbol,
+            configId: test.configId,
+            backtestRunId: test.backtestRunId,
+            backtestTestKey: test.backtestTestKey,
+            skipCounts: Object.fromEntries(
+              [...researchSkipCounts.entries()].sort(
+                ([left], [right]) => left < right ? -1 : left > right ? 1 : 0
+              )
+            )
+          }
+        });
+      }
       const result = await monitor.run(
         "collect result",
         () => testConnector.getResult()
       );
+      const researchTraceSummary = test.researchTrace ? {
+        events: Object.fromEntries(researchEventCounts),
+        skipCounts: Object.fromEntries(researchSkipCounts)
+      } : void 0;
       return replayEvaluations ? {
         ...result,
         warningCounts,
-        inlineReplaySignalEvaluations: replayEvaluations
-      } : { ...result, warningCounts };
+        inlineReplaySignalEvaluations: replayEvaluations,
+        researchTraceSummary
+      } : { ...result, warningCounts, researchTraceSummary };
     }
   };
 };

package/dist/backtest.mjs

@@ -142,6 +142,7 @@ import {
   BACKTEST_WARNING_CODES
 } from "@tradejs/types";
 import { appendAiDatasetRow } from "@tradejs/infra/ai";
+import { appendCoreResearchTraceEvent } from "@tradejs/infra/coreResearch";
 import {
   appendMlDatasetRow,
   buildMlTrainingRow,
@@ -1256,6 +1257,37 @@ var createTestConnector = (connector, context) => {
   };
 };
 
+// src/backtest/researchTrace.ts
+var asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+var findSetupKey = (value, depth = 0) => {
+  if (depth > 5) return null;
+  const record = asRecord(value);
+  if (!record) return null;
+  for (const key of ["setupIdentity", "setupId", "patternId", "candidateId"]) {
+    const candidate = record[key];
+    if (typeof candidate === "string" && candidate.trim() || typeof candidate === "number" && Number.isFinite(candidate)) {
+      return `${key}:${String(candidate)}`;
+    }
+  }
+  for (const [key, nested] of Object.entries(record)) {
+    if (/context|signal|setup|pattern|candidate|strategy/i.test(key) && nested != null) {
+      const found = findSetupKey(nested, depth + 1);
+      if (found) return found;
+    }
+  }
+  return null;
+};
+var resolveCoreResearchSetupIdentity = (signal) => {
+  const strategyKey = findSetupKey(signal.additionalIndicators);
+  return strategyKey ? {
+    setupIdentity: `${signal.strategy}|${signal.symbol}|${signal.direction}|${strategyKey}`,
+    setupIdentitySource: "strategy-context"
+  } : {
+    setupIdentity: `${signal.strategy}|${signal.symbol}|${signal.direction}|${signal.timestamp}`,
+    setupIdentitySource: "signal-time-fallback"
+  };
+};
+
 // src/backtest/session.ts
 var createWarningCounts = () => ({
   [BACKTEST_WARNING_CODES.TAKE_PROFIT_CROSSED_BEFORE_ENTRY]: 0
@@ -1345,7 +1377,7 @@ var createBacktestSession = async ({
   const testConnector = createTestConnector(connector, {
     userName: test.userName,
     mlEnabled: test.ml,
-    aiEnabled: test.ai,
+    aiEnabled: Boolean(test.ai || test.researchTrace),
     fastMode: test.fast,
     instrument,
     executionCostModel,
@@ -1382,11 +1414,18 @@ var createBacktestSession = async ({
   );
   const pendingMlPayloadBySignalId = /* @__PURE__ */ new Map();
   const pendingAiRowBySignalId = /* @__PURE__ */ new Map();
+  const pendingResearchSetupBySignalId = /* @__PURE__ */ new Map();
+  const researchSkipCounts = /* @__PURE__ */ new Map();
+  const researchEventCounts = /* @__PURE__ */ new Map();
   const warningCounts = createWarningCounts();
   const replayEvaluations = test.collectReplaySignalEvaluations ? [] : null;
   const chunkId = test.chunkId ?? "single";
   const processSignal = async (signal, candle) => {
     recordSignalWarning(warningCounts, signal);
+    if (test.researchTrace && typeof signal === "string") {
+      const reason = signal.trim() || "NO_SIGNAL";
+      researchSkipCounts.set(reason, (researchSkipCounts.get(reason) ?? 0) + 1);
+    }
     if (typeof signal === "string" && signal.startsWith("BACKTEST_ENTRY_DELAY_")) {
       return;
     }
@@ -1403,6 +1442,32 @@ var createBacktestSession = async ({
         onStageStart: monitor.contextStage
       });
     }
+    if (test.researchTrace && signal && typeof signal !== "string" && signal.signalId) {
+      const identity = resolveCoreResearchSetupIdentity(signal);
+      pendingResearchSetupBySignalId.set(signal.signalId, identity);
+      await appendCoreResearchTraceEvent({
+        strategyName: test.strategyName,
+        chunkId,
+        event: {
+          schema: "tradejs-core-research-trace/v1",
+          event: signal.orderStatus === "failed" || signal.orderStatus === "skipped" ? "entry_rejected" : "signal_emitted",
+          timestamp: signal.timestamp,
+          strategy: signal.strategy || test.strategyName,
+          symbol: signal.symbol || test.symbol,
+          direction: signal.direction,
+          signalId: signal.signalId,
+          configId: test.configId,
+          backtestRunId: test.backtestRunId,
+          backtestTestKey: test.backtestTestKey,
+          ...identity
+        }
+      });
+      const traceEvent = signal.orderStatus === "failed" || signal.orderStatus === "skipped" ? "entry_rejected" : "signal_emitted";
+      researchEventCounts.set(
+        traceEvent,
+        (researchEventCounts.get(traceEvent) ?? 0) + 1
+      );
+    }
     if (test.ml && signal && typeof signal !== "string" && signal.signalId) {
       pendingMlPayloadBySignalId.set(
         signal.signalId,
@@ -1440,7 +1505,7 @@ var createBacktestSession = async ({
     }
   };
   const flush = async () => {
-    if (!test.ml && !test.ai) return;
+    if (!test.ml && !test.ai && !test.researchTrace) return;
     const batch = await testConnector.drainMlResultsBatch();
     for (const resultRecord of batch) {
       const payload = pendingMlPayloadBySignalId.get(resultRecord.signalId);
@@ -1469,10 +1534,64 @@ var createBacktestSession = async ({
             ...rowBase,
             payload: buildAiPayload(aiSignal),
             profit: resultRecord.profit,
-            tradeResult: resultRecord.tradeResult
+            tradeResult: resultRecord.tradeResult,
+            research: {
+              schema: "tradejs-core-research-row/v1",
+              ...resolveCoreResearchSetupIdentity(aiSignal)
+            }
           }
         });
       }
+      const researchSetup = pendingResearchSetupBySignalId.get(
+        resultRecord.signalId
+      );
+      if (test.researchTrace && researchSetup && resultRecord.tradeResult) {
+        pendingResearchSetupBySignalId.delete(resultRecord.signalId);
+        await appendCoreResearchTraceEvent({
+          strategyName: test.strategyName,
+          chunkId,
+          event: {
+            schema: "tradejs-core-research-trace/v1",
+            event: "entry_executed",
+            timestamp: resultRecord.tradeResult.entryTimestamp,
+            strategy: test.strategyName,
+            symbol: test.symbol,
+            direction: resultRecord.tradeResult.direction,
+            signalId: resultRecord.signalId,
+            configId: test.configId,
+            backtestRunId: test.backtestRunId,
+            backtestTestKey: test.backtestTestKey,
+            ...researchSetup
+          }
+        });
+        researchEventCounts.set(
+          "entry_executed",
+          (researchEventCounts.get("entry_executed") ?? 0) + 1
+        );
+        await appendCoreResearchTraceEvent({
+          strategyName: test.strategyName,
+          chunkId,
+          event: {
+            schema: "tradejs-core-research-trace/v1",
+            event: "position_exited",
+            timestamp: resultRecord.tradeResult.exitTimestamp,
+            strategy: test.strategyName,
+            symbol: test.symbol,
+            direction: resultRecord.tradeResult.direction,
+            signalId: resultRecord.signalId,
+            configId: test.configId,
+            backtestRunId: test.backtestRunId,
+            backtestTestKey: test.backtestTestKey,
+            netProfit: resultRecord.tradeResult.netProfit,
+            exitReason: resultRecord.tradeResult.exitReason,
+            ...researchSetup
+          }
+        });
+        researchEventCounts.set(
+          "position_exited",
+          (researchEventCounts.get("position_exited") ?? 0) + 1
+        );
+      }
     }
   };
   return {
@@ -1505,15 +1624,41 @@ var createBacktestSession = async ({
     flush: () => monitor.run("flush closed results", flush),
     result: async () => {
       await monitor.run("flush closed results", flush);
+      if (test.researchTrace) {
+        await appendCoreResearchTraceEvent({
+          strategyName: test.strategyName,
+          chunkId,
+          event: {
+            schema: "tradejs-core-research-trace/v1",
+            event: "skip_summary",
+            timestamp: test.options.end ?? test.options.start ?? 0,
+            strategy: test.strategyName,
+            symbol: test.symbol,
+            configId: test.configId,
+            backtestRunId: test.backtestRunId,
+            backtestTestKey: test.backtestTestKey,
+            skipCounts: Object.fromEntries(
+              [...researchSkipCounts.entries()].sort(
+                ([left], [right]) => left < right ? -1 : left > right ? 1 : 0
+              )
+            )
+          }
+        });
+      }
       const result = await monitor.run(
         "collect result",
         () => testConnector.getResult()
       );
+      const researchTraceSummary = test.researchTrace ? {
+        events: Object.fromEntries(researchEventCounts),
+        skipCounts: Object.fromEntries(researchSkipCounts)
+      } : void 0;
       return replayEvaluations ? {
         ...result,
         warningCounts,
-        inlineReplaySignalEvaluations: replayEvaluations
-      } : { ...result, warningCounts };
+        inlineReplaySignalEvaluations: replayEvaluations,
+        researchTraceSummary
+      } : { ...result, warningCounts, researchTraceSummary };
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tradejs/node",
-  "version": "2.0.19",
+  "version": "2.0.20",
   "description": "Node-only runtime for the TradeJS TypeScript framework: strategies, backtests, Pine strategy loading, and plugin registries.",
   "keywords": [
     "tradejs",
@@ -67,9 +67,9 @@
   "dependencies": {
     "@langchain/core": "^1.2.3",
     "@langchain/openai": "^1.5.5",
-    "@tradejs/core": "^2.0.19",
-    "@tradejs/infra": "^2.0.19",
-    "@tradejs/types": "^2.0.19",
+    "@tradejs/core": "^2.0.20",
+    "@tradejs/infra": "^2.0.20",
+    "@tradejs/types": "^2.0.20",
     "chalk": "4.1.2",
     "ioredis": "5.11.1",
     "lodash": "^4.18.1",
@@ -80,7 +80,7 @@
     "tsconfig-paths": "^4.2.0"
   },
   "devDependencies": {
-    "@tradejs/strategies": "^2.0.19",
+    "@tradejs/strategies": "^2.0.20",
     "@types/node": "^24",
     "tsup": "^8.5.1",
     "typescript": "^5.9"