@tradejs/node 3.1.29-beta.282 → 3.1.29-beta.284

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,
@@ -6175,6 +6180,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 +6827,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 +7543,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7521,6 +7642,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 +8388,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 +9692,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 +9708,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 +9740,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 +9781,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 +9791,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 +10671,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-K56EW2BB.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-K56EW2BB.mjs}

@@ -1,5 +1,7 @@
 import {
   askAI,
+  buildAiPayload,
+  getDeterministicAiGateContext,
   getStrategyManifest,
   getStrategyProfileMlAdapter,
   resolveStrategyPolicyProfile,
@@ -3179,6 +3181,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 +4256,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 +4972,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -4953,6 +5071,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 +5222,10 @@ export {
   validateEntryProtectionAtArrival,
   executeEntryOrder,
   resolveStrategyConfig,
+  RESEARCH_ENTRY_POLICY_CAPABILITIES,
+  buildResearchEntryPayload,
+  parseResearchEntryPolicy,
+  matchesResearchEntryRules,
+  evaluateResearchEntryPolicy,
   createStrategyRuntime
 };

package/dist/diagnostics.d.mts

@@ -179,4 +179,57 @@ declare const verifyRuntimeFeedbackReplaySource: ({ bundleDir, runtimeEvidenceBu
     runtimeEvidence: VerifiedRuntimeEvidenceBundle;
 }>;
 
-export { RUNTIME_EVIDENCE_COMPLETE_FILE, RUNTIME_EVIDENCE_MANIFEST_FILE, RUNTIME_EVIDENCE_PAYLOAD_FILE, RUNTIME_FEEDBACK_COMPLETE_FILE, RUNTIME_FEEDBACK_LOG_FILE, RUNTIME_FEEDBACK_MANIFEST_FILE, RUNTIME_FEEDBACK_REPLAY_FILE, type RuntimeEvidenceArtifactManifest, type RuntimeEvidenceDeploymentSnapshot, type RuntimeEvidenceProducer, type RuntimeEvidenceStrategySnapshot, type RuntimeFeedbackReplayManifest, type VerifiedRuntimeEvidenceBundle, type VerifiedRuntimeFeedbackReplayBundle, activeRuntimeEvidenceStrategies, assertCurrentRuntimeEvidenceArtifact, discoverRuntimeEvidenceBundles, discoverRuntimeFeedbackReplayBundles, parseRuntimeEvidenceDeploymentSnapshot, parseRuntimeEvidenceProducer, publishRuntimeEvidenceBundle, resolveRuntimeEvidenceDeploymentSnapshot, resolveRuntimeEvidenceProducer, resolveRuntimeEvidenceTickerUniverse, runtimeDeploymentFromEvidence, runtimeLineageMatchesStrategySnapshot, sealRuntimeFeedbackReplayBundle, verifyRuntimeEvidenceBundle, verifyRuntimeFeedbackReplayBundle, verifyRuntimeFeedbackReplaySource };
+/** Version of the complete feedback read contract, independent of package versions. */
+declare const MCP_FEEDBACK_CONTRACT: {
+    readonly version: 1;
+    readonly hostProtocolVersion: 2;
+    readonly replayQueue: {
+        readonly waitingStates: readonly ["waiting_resources", "waiting_executor"];
+        readonly automaticFailedRetries: false;
+    };
+    readonly artifactEncoding: "base64";
+    readonly maximumChunkBytes: 48000;
+    readonly artifactFiles: readonly ["payload", "manifest.json", ".complete", "replay.log"];
+    readonly requiredTools: readonly ["tradejs_info", "diagnostics_list_reports", "diagnostics_get_report", "artifact_get", "job_get", "job_get_logs"];
+};
+type McpToolDescription = {
+    name: string;
+    inputSchema: {
+        properties?: Record<string, unknown>;
+    };
+};
+/** Check the actual client's tools/list, not only what the server advertises. */
+declare const assertMcpFeedbackContract: (version: unknown, tools: McpToolDescription[]) => void;
+
+type McpArtifactFile = 'payload' | 'manifest.json' | '.complete' | 'replay.log';
+type McpBundleDescriptor = {
+    id: string;
+    kind: 'runtime-evidence' | 'runtime-feedback-replay';
+    files: {
+        file: McpArtifactFile;
+        bytes: number;
+        sha256: string;
+        available: boolean;
+    }[];
+};
+declare class McpReadTransportError extends Error {
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, retryAfterMs?: number | undefined);
+}
+type ChunkRequest = {
+    artifactId: string;
+    file: McpArtifactFile;
+    offset: number;
+    length: number;
+};
+/** The caller owns the authenticated MCP connection. This function only reads artifacts. */
+declare const downloadMcpBundle: ({ descriptor, root, contractVersion, tools, readChunk, wait, }: {
+    descriptor: McpBundleDescriptor;
+    root: string;
+    contractVersion: unknown;
+    tools: McpToolDescription[];
+    readChunk: (request: ChunkRequest) => Promise<unknown>;
+    wait?: (ms: number) => Promise<unknown>;
+}) => Promise<VerifiedRuntimeEvidenceBundle | VerifiedRuntimeFeedbackReplayBundle>;
+
+export { MCP_FEEDBACK_CONTRACT, type McpArtifactFile, type McpBundleDescriptor, McpReadTransportError, type McpToolDescription, RUNTIME_EVIDENCE_COMPLETE_FILE, RUNTIME_EVIDENCE_MANIFEST_FILE, RUNTIME_EVIDENCE_PAYLOAD_FILE, RUNTIME_FEEDBACK_COMPLETE_FILE, RUNTIME_FEEDBACK_LOG_FILE, RUNTIME_FEEDBACK_MANIFEST_FILE, RUNTIME_FEEDBACK_REPLAY_FILE, type RuntimeEvidenceArtifactManifest, type RuntimeEvidenceDeploymentSnapshot, type RuntimeEvidenceProducer, type RuntimeEvidenceStrategySnapshot, type RuntimeFeedbackReplayManifest, type VerifiedRuntimeEvidenceBundle, type VerifiedRuntimeFeedbackReplayBundle, activeRuntimeEvidenceStrategies, assertCurrentRuntimeEvidenceArtifact, assertMcpFeedbackContract, discoverRuntimeEvidenceBundles, discoverRuntimeFeedbackReplayBundles, downloadMcpBundle, parseRuntimeEvidenceDeploymentSnapshot, parseRuntimeEvidenceProducer, publishRuntimeEvidenceBundle, resolveRuntimeEvidenceDeploymentSnapshot, resolveRuntimeEvidenceProducer, resolveRuntimeEvidenceTickerUniverse, runtimeDeploymentFromEvidence, runtimeLineageMatchesStrategySnapshot, sealRuntimeFeedbackReplayBundle, verifyRuntimeEvidenceBundle, verifyRuntimeFeedbackReplayBundle, verifyRuntimeFeedbackReplaySource };