@tradejs/node 3.1.29-beta.283 → 3.1.29-beta.285

package/dist/backtest.d.mts

@@ -1,5 +1,6 @@
 export * from '@tradejs/core/backtest';
-import { Test, TestingBox, TestingBoxResult, TestConnectorCreator, Connector, StrategyConfig, BacktestExecutionCosts, InstrumentDescriptor, ExecutionCostModel, FundingRatePoint } from '@tradejs/types';
+import * as _tradejs_types from '@tradejs/types';
+import { Test, TestingBox, TestingBoxResult, TestConnectorCreator, Connector, StrategyConfig, BacktestExecutionCosts, InstrumentDescriptor, ExecutionCostModel, FundingRatePoint, Signal, AiPayload, ResearchEntryPolicy } from '@tradejs/types';
 
 type TestingGroupResult = {
     test: Test;
@@ -32,4 +33,14 @@ declare const resolveExecutionCosts: (params: {
     fundingRates: FundingRatePoint[];
 }>;
 
-export { canRunTestsInSharedCandleLoop, createTestConnector, releaseTestingSymbolCache, resetTestingKlineCache, resolveExecutionCosts, testing, testingGroupInSharedCandleLoop };
+declare const RESEARCH_ENTRY_POLICY_CAPABILITIES: {
+    readonly directionSelection: true;
+};
+/** Preserve the canonical signal-time snapshot even when an AI adapter emits
+ * only its strategy-specific fields. Both discovery and execution use this. */
+declare const buildResearchEntryPayload: (signal: Signal, payload?: AiPayload) => AiPayload;
+declare const parseResearchEntryPolicy: (value: unknown) => ResearchEntryPolicy;
+declare const matchesResearchEntryRules: (payload: AiPayload, predicates: NonNullable<ResearchEntryPolicy["rules"]["LONG"]>) => boolean;
+declare const evaluateResearchEntryPolicy: (policy: ResearchEntryPolicy, signal: Signal, onDecision?: (decision: _tradejs_types.ResearchEntryDecision) => void) => Promise<boolean>;
+
+export { RESEARCH_ENTRY_POLICY_CAPABILITIES, buildResearchEntryPayload, canRunTestsInSharedCandleLoop, createTestConnector, evaluateResearchEntryPolicy, matchesResearchEntryRules, parseResearchEntryPolicy, releaseTestingSymbolCache, resetTestingKlineCache, resolveExecutionCosts, testing, testingGroupInSharedCandleLoop };

package/dist/backtest.d.ts

@@ -1,5 +1,6 @@
 export * from '@tradejs/core/backtest';
-import { Test, TestingBox, TestingBoxResult, TestConnectorCreator, Connector, StrategyConfig, BacktestExecutionCosts, InstrumentDescriptor, ExecutionCostModel, FundingRatePoint } from '@tradejs/types';
+import * as _tradejs_types from '@tradejs/types';
+import { Test, TestingBox, TestingBoxResult, TestConnectorCreator, Connector, StrategyConfig, BacktestExecutionCosts, InstrumentDescriptor, ExecutionCostModel, FundingRatePoint, Signal, AiPayload, ResearchEntryPolicy } from '@tradejs/types';
 
 type TestingGroupResult = {
     test: Test;
@@ -32,4 +33,14 @@ declare const resolveExecutionCosts: (params: {
     fundingRates: FundingRatePoint[];
 }>;
 
-export { canRunTestsInSharedCandleLoop, createTestConnector, releaseTestingSymbolCache, resetTestingKlineCache, resolveExecutionCosts, testing, testingGroupInSharedCandleLoop };
+declare const RESEARCH_ENTRY_POLICY_CAPABILITIES: {
+    readonly directionSelection: true;
+};
+/** Preserve the canonical signal-time snapshot even when an AI adapter emits
+ * only its strategy-specific fields. Both discovery and execution use this. */
+declare const buildResearchEntryPayload: (signal: Signal, payload?: AiPayload) => AiPayload;
+declare const parseResearchEntryPolicy: (value: unknown) => ResearchEntryPolicy;
+declare const matchesResearchEntryRules: (payload: AiPayload, predicates: NonNullable<ResearchEntryPolicy["rules"]["LONG"]>) => boolean;
+declare const evaluateResearchEntryPolicy: (policy: ResearchEntryPolicy, signal: Signal, onDecision?: (decision: _tradejs_types.ResearchEntryDecision) => void) => Promise<boolean>;
+
+export { RESEARCH_ENTRY_POLICY_CAPABILITIES, buildResearchEntryPayload, canRunTestsInSharedCandleLoop, createTestConnector, evaluateResearchEntryPolicy, matchesResearchEntryRules, parseResearchEntryPolicy, releaseTestingSymbolCache, resetTestingKlineCache, resolveExecutionCosts, testing, testingGroupInSharedCandleLoop };

package/dist/backtest.js

@@ -778,8 +778,13 @@ var init_jevTraining = __esm({
 // src/backtest.ts
 var backtest_exports = {};
 __export(backtest_exports, {
+  RESEARCH_ENTRY_POLICY_CAPABILITIES: () => RESEARCH_ENTRY_POLICY_CAPABILITIES,
+  buildResearchEntryPayload: () => buildResearchEntryPayload,
   canRunTestsInSharedCandleLoop: () => canRunTestsInSharedCandleLoop,
   createTestConnector: () => createTestConnector,
+  evaluateResearchEntryPolicy: () => evaluateResearchEntryPolicy,
+  matchesResearchEntryRules: () => matchesResearchEntryRules,
+  parseResearchEntryPolicy: () => parseResearchEntryPolicy,
   releaseTestingSymbolCache: () => releaseTestingSymbolCache,
   resetTestingKlineCache: () => resetTestingKlineCache,
   resolveExecutionCosts: () => resolveExecutionCosts,
@@ -2958,6 +2963,7 @@ var recordRuntimeTradeIncrease = async (params) => {
   const totalFee = (existing.totalFee ?? existing.fee ?? 0) + addedFee;
   const next = {
     ...existing,
+    ...params.orderLeverage ? { orderLeverage: params.orderLeverage } : {},
     qty: resultingQty,
     entryPrice: resultingEntryPrice,
     entryCount: Math.max(1, existing.entryCount ?? 1) + 1,
@@ -5686,6 +5692,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -5709,6 +5716,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -6175,6 +6183,115 @@ var buildAiHookContext = ({
   };
 };
 
+// src/researchEntryPolicy.ts
+var RESEARCH_ENTRY_POLICY_CAPABILITIES = {
+  directionSelection: true
+};
+var forbidden = /(?:^|\.)(?:__proto__|prototype|constructor|profit|pnl|outcome|tradeResult|backtestExecution|quality|deterministicQuality|approvalAllowedNow|timestamp|knownAt|source|coverage|points|rows|length)(?:\.|$)/i;
+var buildResearchEntryPayload = (signal, payload = buildAiPayload(signal)) => {
+  const additional = payload.additionalIndicators && typeof payload.additionalIndicators === "object" ? payload.additionalIndicators : {};
+  const raw = signal.additionalIndicators?.baseContext;
+  const adapted = additional.baseContext;
+  return {
+    ...payload,
+    additionalIndicators: {
+      ...additional,
+      ...signal.additionalIndicators?.jev && typeof signal.additionalIndicators.jev === "object" ? { jev: signal.additionalIndicators.jev } : {},
+      baseContext: {
+        ...raw && typeof raw === "object" ? raw : {},
+        ...adapted && typeof adapted === "object" ? adapted : {}
+      }
+    }
+  };
+};
+var parseResearchEntryPolicy = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid research entry policy");
+  const policy = value;
+  if (policy.schema !== "tradejs-research-entry-policy/v1" || typeof policy.strategy !== "string" || !policy.strategy.trim() || !["current-gate", "rules"].includes(policy.mode) || !Number.isInteger(policy.minQuality) || policy.minQuality < 1 || policy.minQuality > 5 || !policy.rules || typeof policy.rules !== "object")
+    throw new Error("Invalid research entry policy contract");
+  if (policy.directions !== void 0 && (!Array.isArray(policy.directions) || policy.directions.length > 2 || new Set(policy.directions).size !== policy.directions.length || policy.directions.some((side) => !["LONG", "SHORT"].includes(side))))
+    throw new Error("Invalid research policy directions");
+  for (const side of ["LONG", "SHORT"]) {
+    const predicates = policy.rules[side];
+    if (predicates === null) continue;
+    if (!Array.isArray(predicates) || predicates.length > 4)
+      throw new Error(
+        "Research policy needs bounded rules for both directions"
+      );
+    for (const predicate of predicates) {
+      if (!predicate || typeof predicate.path !== "string" || !/^additionalIndicators\.[a-zA-Z0-9_.]+$/.test(predicate.path) || forbidden.test(predicate.path) || !["<=", ">=", "=="].includes(predicate.op) || (predicate.op === "==" ? !["string", "boolean"].includes(typeof predicate.value) : typeof predicate.value !== "number" || !Number.isFinite(predicate.value)))
+        throw new Error(
+          "Research policy contains an unsupported or non-causal predicate"
+        );
+    }
+  }
+  return policy;
+};
+var matchesResearchEntryRules = (payload, predicates) => predicates.every((predicate) => {
+  const value = predicate.path.split(".").reduce(
+    (current, key) => current != null && typeof current === "object" && Object.hasOwn(current, key) ? Reflect.get(current, key) : void 0,
+    payload
+  );
+  if (value == null) return false;
+  if (predicate.op === "==") return value === predicate.value;
+  if (typeof value !== "number" || !Number.isFinite(value)) return false;
+  return predicate.op === "<=" ? value <= predicate.value : value >= predicate.value;
+});
+var evaluateResearchEntryPolicy = async (policy, signal, onDecision) => {
+  if (signal.strategy !== policy.strategy)
+    throw new Error("Research policy strategy mismatch");
+  if (policy.directions && !policy.directions.includes(signal.direction) || policy.mode === "rules" && policy.rules[signal.direction] === null) {
+    onDecision?.({
+      mode: policy.mode,
+      allowed: false,
+      reason: "DIRECTION_BLOCKED"
+    });
+    return false;
+  }
+  if (policy.mode === "current-gate") {
+    const analysis = await runAiPromptLocal(signal);
+    const allowed2 = analysis.direction === signal.direction && typeof analysis.quality === "number" && analysis.quality >= policy.minQuality;
+    onDecision?.({
+      mode: policy.mode,
+      allowed: allowed2,
+      quality: analysis.quality ?? null,
+      reason: allowed2 ? "CURRENT_GATE_APPROVED" : "CURRENT_GATE_REJECTED"
+    });
+    return allowed2;
+  }
+  const original = buildAiPayload(signal);
+  const gateContext = getDeterministicAiGateContext(original);
+  if (Array.isArray(gateContext?.structuralHardBlockReasons) && gateContext.structuralHardBlockReasons.length) {
+    onDecision?.({
+      mode: policy.mode,
+      allowed: false,
+      reason: "STRUCTURAL_HARD_BLOCK"
+    });
+    return false;
+  }
+  const rules = policy.rules[signal.direction];
+  const payload = buildResearchEntryPayload(signal, original);
+  const allowed = rules !== null && matchesResearchEntryRules(payload, rules);
+  onDecision?.({
+    mode: policy.mode,
+    allowed,
+    reason: allowed ? "RULES_APPROVED" : "PREDICATE_REJECTED",
+    predicates: rules?.map((rule) => {
+      const value = rule.path.split(".").reduce(
+        (current, key) => current && typeof current === "object" && Object.hasOwn(current, key) ? Reflect.get(current, key) : void 0,
+        payload
+      );
+      return {
+        path: rule.path,
+        actual: typeof value === "number" && Number.isFinite(value) || typeof value === "string" || typeof value === "boolean" ? value : null,
+        passed: matchesResearchEntryRules(payload, [rule])
+      };
+    })
+  });
+  return allowed;
+};
+
 // src/strategy/runtimeDecisionTelemetry.ts
 var finitePositive = (value) => {
   const parsed = Number(value);
@@ -6713,6 +6830,12 @@ var createStrategyRuntime = ({
     const projectConfig = await loadTradejsConfig(projectRoot);
     const projectHooks = projectConfig.hooks;
     const env = String(config.ENV ?? "BACKTEST");
+    const researchPolicyValue = baseConfig?.RESEARCH_ENTRY_POLICY ?? config.RESEARCH_ENTRY_POLICY;
+    const researchEntryPolicy = researchPolicyValue == null ? void 0 : parseResearchEntryPolicy(researchPolicyValue);
+    if (researchEntryPolicy && (env !== "BACKTEST" || Reflect.get(connector, "__tradejsTestConnector") !== true))
+      throw new Error(
+        "Research entry policies require a BACKTEST simulation connector"
+      );
     const jev = (0, import_jev6.parseJevConfig)(config.JEV);
     if (jev && env !== "BACKTEST" && jev.source === "provider" && !jev.provider)
       throw new Error(
@@ -7423,7 +7546,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7521,6 +7645,22 @@ var createStrategyRuntime = ({
         }
         return signal ?? decision.code;
       }
+      if (researchEntryPolicy && (!signal || !await evaluateResearchEntryPolicy(
+        researchEntryPolicy,
+        signal,
+        (decision2) => {
+          signal.additionalIndicators = {
+            ...signal.additionalIndicators,
+            researchEntryDecision: decision2
+          };
+        }
+      ))) {
+        if (signal) {
+          signal.orderStatus = "skipped";
+          signal.orderSkipReason = "RESEARCH_ENTRY_POLICY_REJECTED";
+        }
+        return signal ?? "RESEARCH_ENTRY_POLICY_REJECTED";
+      }
       const entryGate = await invokeGateHooks(
         "beforeEntryGate",
         decisionManifest?.hooks?.beforeEntryGate,
@@ -8251,7 +8391,7 @@ var createBacktestProgress = ({
 
 // src/backtest/session.ts
 var import_types2 = require("@tradejs/types");
-var import_ai3 = require("@tradejs/infra/ai");
+var import_ai4 = require("@tradejs/infra/ai");
 var import_coreResearch = require("@tradejs/infra/coreResearch");
 var import_ml3 = require("@tradejs/infra/ml");
 
@@ -9555,7 +9695,8 @@ var createBacktestSession = async ({
     }
     if (test.researchTrace && signal && typeof signal !== "string" && signal.signalId) {
       const identity = resolveCoreResearchSetupIdentity(signal);
-      pendingResearchSetupBySignalId.set(signal.signalId, identity);
+      if (signal.orderStatus !== "failed" && signal.orderStatus !== "skipped")
+        pendingResearchSetupBySignalId.set(signal.signalId, identity);
       await (0, import_coreResearch.appendCoreResearchTraceEvent)({
         strategyName: test.strategyName,
         chunkId,
@@ -9570,7 +9711,11 @@ var createBacktestSession = async ({
           configId: test.configId,
           backtestRunId: test.backtestRunId,
           backtestTestKey: test.backtestTestKey,
-          ...identity
+          ...identity,
+          ...test.strategyConfig.RESEARCH_ENTRY_POLICY ? {
+            reason: signal.orderSkipReason,
+            researchEntryDecision: signal.additionalIndicators?.researchEntryDecision
+          } : {}
         }
       });
       const traceEvent = signal.orderStatus === "failed" || signal.orderStatus === "skipped" ? "entry_rejected" : "signal_emitted";
@@ -9598,7 +9743,7 @@ var createBacktestSession = async ({
         })
       );
     }
-    if (test.ai && signal && typeof signal !== "string" && signal.signalId && !(signal.assessment && signal.orderStatus === "skipped")) {
+    if (test.ai && signal && typeof signal !== "string" && signal.signalId && !(test.strategyConfig.RESEARCH_ENTRY_POLICY && (signal.orderStatus === "skipped" || signal.orderStatus === "failed")) && !(signal.assessment && signal.orderStatus === "skipped")) {
       pendingAiRowBySignalId.set(signal.signalId, {
         signalId: signal.signalId,
         strategyName: signal.strategy || test.strategyName,
@@ -9639,7 +9784,7 @@ var createBacktestSession = async ({
       if (aiRowBase) {
         pendingAiRowBySignalId.delete(resultRecord.signalId);
         const { signal: aiSignal, ...rowBase } = aiRowBase;
-        await (0, import_ai3.appendAiDatasetRow)({
+        await (0, import_ai4.appendAiDatasetRow)({
           strategyName: test.strategyName,
           chunkId,
           row: {
@@ -9649,7 +9794,14 @@ var createBacktestSession = async ({
             tradeResult: resultRecord.tradeResult,
             research: {
               schema: "tradejs-core-research-row/v1",
-              ...resolveCoreResearchSetupIdentity(aiSignal)
+              ...resolveCoreResearchSetupIdentity(aiSignal),
+              ...test.researchTrace ? {
+                decisionContext: {
+                  schema: "tradejs-research-decision-context/v1",
+                  knownAt: aiSignal.timestamp,
+                  baseContext: aiSignal.additionalIndicators?.baseContext ?? null
+                }
+              } : {}
             }
           }
         });
@@ -10522,8 +10674,13 @@ var testingGroupInSharedCandleLoop = async (tests) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  RESEARCH_ENTRY_POLICY_CAPABILITIES,
+  buildResearchEntryPayload,
   canRunTestsInSharedCandleLoop,
   createTestConnector,
+  evaluateResearchEntryPolicy,
+  matchesResearchEntryRules,
+  parseResearchEntryPolicy,
   releaseTestingSymbolCache,
   resetTestingKlineCache,
   resolveExecutionCosts,

package/dist/backtest.mjs

@@ -3,9 +3,14 @@ import {
   getConnectorCreatorByName
 } from "./chunk-QVKUROR2.mjs";
 import {
+  RESEARCH_ENTRY_POLICY_CAPABILITIES,
   buildMlPayload,
-  enrichSignalWithMarketContextStages
-} from "./chunk-SKY2HNZU.mjs";
+  buildResearchEntryPayload,
+  enrichSignalWithMarketContextStages,
+  evaluateResearchEntryPolicy,
+  matchesResearchEntryRules,
+  parseResearchEntryPolicy
+} from "./chunk-KOV3U6ZZ.mjs";
 import {
   buildAiPayload,
   getStrategyCreator
@@ -1468,7 +1473,8 @@ var createBacktestSession = async ({
     }
     if (test.researchTrace && signal && typeof signal !== "string" && signal.signalId) {
       const identity = resolveCoreResearchSetupIdentity(signal);
-      pendingResearchSetupBySignalId.set(signal.signalId, identity);
+      if (signal.orderStatus !== "failed" && signal.orderStatus !== "skipped")
+        pendingResearchSetupBySignalId.set(signal.signalId, identity);
       await appendCoreResearchTraceEvent({
         strategyName: test.strategyName,
         chunkId,
@@ -1483,7 +1489,11 @@ var createBacktestSession = async ({
           configId: test.configId,
           backtestRunId: test.backtestRunId,
           backtestTestKey: test.backtestTestKey,
-          ...identity
+          ...identity,
+          ...test.strategyConfig.RESEARCH_ENTRY_POLICY ? {
+            reason: signal.orderSkipReason,
+            researchEntryDecision: signal.additionalIndicators?.researchEntryDecision
+          } : {}
         }
       });
       const traceEvent = signal.orderStatus === "failed" || signal.orderStatus === "skipped" ? "entry_rejected" : "signal_emitted";
@@ -1511,7 +1521,7 @@ var createBacktestSession = async ({
         })
       );
     }
-    if (test.ai && signal && typeof signal !== "string" && signal.signalId && !(signal.assessment && signal.orderStatus === "skipped")) {
+    if (test.ai && signal && typeof signal !== "string" && signal.signalId && !(test.strategyConfig.RESEARCH_ENTRY_POLICY && (signal.orderStatus === "skipped" || signal.orderStatus === "failed")) && !(signal.assessment && signal.orderStatus === "skipped")) {
       pendingAiRowBySignalId.set(signal.signalId, {
         signalId: signal.signalId,
         strategyName: signal.strategy || test.strategyName,
@@ -1562,7 +1572,14 @@ var createBacktestSession = async ({
             tradeResult: resultRecord.tradeResult,
             research: {
               schema: "tradejs-core-research-row/v1",
-              ...resolveCoreResearchSetupIdentity(aiSignal)
+              ...resolveCoreResearchSetupIdentity(aiSignal),
+              ...test.researchTrace ? {
+                decisionContext: {
+                  schema: "tradejs-research-decision-context/v1",
+                  knownAt: aiSignal.timestamp,
+                  baseContext: aiSignal.additionalIndicators?.baseContext ?? null
+                }
+              } : {}
             }
           }
         });
@@ -2434,8 +2451,13 @@ var testingGroupInSharedCandleLoop = async (tests) => {
   }
 };
 export {
+  RESEARCH_ENTRY_POLICY_CAPABILITIES,
+  buildResearchEntryPayload,
   canRunTestsInSharedCandleLoop,
   createTestConnector,
+  evaluateResearchEntryPolicy,
+  matchesResearchEntryRules,
+  parseResearchEntryPolicy,
   releaseTestingSymbolCache,
   resetTestingKlineCache,
   resolveExecutionCosts,

package/dist/{chunk-SKY2HNZU.mjs → chunk-KOV3U6ZZ.mjs}

@@ -1,5 +1,7 @@
 import {
   askAI,
+  buildAiPayload,
+  getDeterministicAiGateContext,
   getStrategyManifest,
   getStrategyProfileMlAdapter,
   resolveStrategyPolicyProfile,
@@ -2181,6 +2183,7 @@ var recordRuntimeTradeIncrease = async (params) => {
   const totalFee = (existing.totalFee ?? existing.fee ?? 0) + addedFee;
   const next = {
     ...existing,
+    ...params.orderLeverage ? { orderLeverage: params.orderLeverage } : {},
     qty: resultingQty,
     entryPrice: resultingEntryPrice,
     entryCount: Math.max(1, existing.entryCount ?? 1) + 1,
@@ -3099,6 +3102,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -3122,6 +3126,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -3179,6 +3184,115 @@ var resolveStrategyConfig = async ({
   return { config, isConfigFromBacktest };
 };
 
+// src/researchEntryPolicy.ts
+var RESEARCH_ENTRY_POLICY_CAPABILITIES = {
+  directionSelection: true
+};
+var forbidden = /(?:^|\.)(?:__proto__|prototype|constructor|profit|pnl|outcome|tradeResult|backtestExecution|quality|deterministicQuality|approvalAllowedNow|timestamp|knownAt|source|coverage|points|rows|length)(?:\.|$)/i;
+var buildResearchEntryPayload = (signal, payload = buildAiPayload(signal)) => {
+  const additional = payload.additionalIndicators && typeof payload.additionalIndicators === "object" ? payload.additionalIndicators : {};
+  const raw = signal.additionalIndicators?.baseContext;
+  const adapted = additional.baseContext;
+  return {
+    ...payload,
+    additionalIndicators: {
+      ...additional,
+      ...signal.additionalIndicators?.jev && typeof signal.additionalIndicators.jev === "object" ? { jev: signal.additionalIndicators.jev } : {},
+      baseContext: {
+        ...raw && typeof raw === "object" ? raw : {},
+        ...adapted && typeof adapted === "object" ? adapted : {}
+      }
+    }
+  };
+};
+var parseResearchEntryPolicy = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid research entry policy");
+  const policy = value;
+  if (policy.schema !== "tradejs-research-entry-policy/v1" || typeof policy.strategy !== "string" || !policy.strategy.trim() || !["current-gate", "rules"].includes(policy.mode) || !Number.isInteger(policy.minQuality) || policy.minQuality < 1 || policy.minQuality > 5 || !policy.rules || typeof policy.rules !== "object")
+    throw new Error("Invalid research entry policy contract");
+  if (policy.directions !== void 0 && (!Array.isArray(policy.directions) || policy.directions.length > 2 || new Set(policy.directions).size !== policy.directions.length || policy.directions.some((side) => !["LONG", "SHORT"].includes(side))))
+    throw new Error("Invalid research policy directions");
+  for (const side of ["LONG", "SHORT"]) {
+    const predicates = policy.rules[side];
+    if (predicates === null) continue;
+    if (!Array.isArray(predicates) || predicates.length > 4)
+      throw new Error(
+        "Research policy needs bounded rules for both directions"
+      );
+    for (const predicate of predicates) {
+      if (!predicate || typeof predicate.path !== "string" || !/^additionalIndicators\.[a-zA-Z0-9_.]+$/.test(predicate.path) || forbidden.test(predicate.path) || !["<=", ">=", "=="].includes(predicate.op) || (predicate.op === "==" ? !["string", "boolean"].includes(typeof predicate.value) : typeof predicate.value !== "number" || !Number.isFinite(predicate.value)))
+        throw new Error(
+          "Research policy contains an unsupported or non-causal predicate"
+        );
+    }
+  }
+  return policy;
+};
+var matchesResearchEntryRules = (payload, predicates) => predicates.every((predicate) => {
+  const value = predicate.path.split(".").reduce(
+    (current, key) => current != null && typeof current === "object" && Object.hasOwn(current, key) ? Reflect.get(current, key) : void 0,
+    payload
+  );
+  if (value == null) return false;
+  if (predicate.op === "==") return value === predicate.value;
+  if (typeof value !== "number" || !Number.isFinite(value)) return false;
+  return predicate.op === "<=" ? value <= predicate.value : value >= predicate.value;
+});
+var evaluateResearchEntryPolicy = async (policy, signal, onDecision) => {
+  if (signal.strategy !== policy.strategy)
+    throw new Error("Research policy strategy mismatch");
+  if (policy.directions && !policy.directions.includes(signal.direction) || policy.mode === "rules" && policy.rules[signal.direction] === null) {
+    onDecision?.({
+      mode: policy.mode,
+      allowed: false,
+      reason: "DIRECTION_BLOCKED"
+    });
+    return false;
+  }
+  if (policy.mode === "current-gate") {
+    const analysis = await runAiPromptLocal(signal);
+    const allowed2 = analysis.direction === signal.direction && typeof analysis.quality === "number" && analysis.quality >= policy.minQuality;
+    onDecision?.({
+      mode: policy.mode,
+      allowed: allowed2,
+      quality: analysis.quality ?? null,
+      reason: allowed2 ? "CURRENT_GATE_APPROVED" : "CURRENT_GATE_REJECTED"
+    });
+    return allowed2;
+  }
+  const original = buildAiPayload(signal);
+  const gateContext = getDeterministicAiGateContext(original);
+  if (Array.isArray(gateContext?.structuralHardBlockReasons) && gateContext.structuralHardBlockReasons.length) {
+    onDecision?.({
+      mode: policy.mode,
+      allowed: false,
+      reason: "STRUCTURAL_HARD_BLOCK"
+    });
+    return false;
+  }
+  const rules = policy.rules[signal.direction];
+  const payload = buildResearchEntryPayload(signal, original);
+  const allowed = rules !== null && matchesResearchEntryRules(payload, rules);
+  onDecision?.({
+    mode: policy.mode,
+    allowed,
+    reason: allowed ? "RULES_APPROVED" : "PREDICATE_REJECTED",
+    predicates: rules?.map((rule) => {
+      const value = rule.path.split(".").reduce(
+        (current, key) => current && typeof current === "object" && Object.hasOwn(current, key) ? Reflect.get(current, key) : void 0,
+        payload
+      );
+      return {
+        path: rule.path,
+        actual: typeof value === "number" && Number.isFinite(value) || typeof value === "string" || typeof value === "boolean" ? value : null,
+        passed: matchesResearchEntryRules(payload, [rule])
+      };
+    })
+  });
+  return allowed;
+};
+
 // src/strategyRuntime.ts
 import { parseJevConfig } from "@tradejs/core/jev";
 import {
@@ -4145,6 +4259,12 @@ var createStrategyRuntime = ({
     const projectConfig = await loadTradejsConfig(projectRoot);
     const projectHooks = projectConfig.hooks;
     const env = String(config.ENV ?? "BACKTEST");
+    const researchPolicyValue = baseConfig?.RESEARCH_ENTRY_POLICY ?? config.RESEARCH_ENTRY_POLICY;
+    const researchEntryPolicy = researchPolicyValue == null ? void 0 : parseResearchEntryPolicy(researchPolicyValue);
+    if (researchEntryPolicy && (env !== "BACKTEST" || Reflect.get(connector, "__tradejsTestConnector") !== true))
+      throw new Error(
+        "Research entry policies require a BACKTEST simulation connector"
+      );
     const jev = parseJevConfig(config.JEV);
     if (jev && env !== "BACKTEST" && jev.source === "provider" && !jev.provider)
       throw new Error(
@@ -4855,7 +4975,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -4953,6 +5074,22 @@ var createStrategyRuntime = ({
         }
         return signal ?? decision.code;
       }
+      if (researchEntryPolicy && (!signal || !await evaluateResearchEntryPolicy(
+        researchEntryPolicy,
+        signal,
+        (decision2) => {
+          signal.additionalIndicators = {
+            ...signal.additionalIndicators,
+            researchEntryDecision: decision2
+          };
+        }
+      ))) {
+        if (signal) {
+          signal.orderStatus = "skipped";
+          signal.orderSkipReason = "RESEARCH_ENTRY_POLICY_REJECTED";
+        }
+        return signal ?? "RESEARCH_ENTRY_POLICY_REJECTED";
+      }
       const entryGate = await invokeGateHooks(
         "beforeEntryGate",
         decisionManifest?.hooks?.beforeEntryGate,
@@ -5088,5 +5225,10 @@ export {
   validateEntryProtectionAtArrival,
   executeEntryOrder,
   resolveStrategyConfig,
+  RESEARCH_ENTRY_POLICY_CAPABILITIES,
+  buildResearchEntryPayload,
+  parseResearchEntryPolicy,
+  matchesResearchEntryRules,
+  evaluateResearchEntryPolicy,
   createStrategyRuntime
 };