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

package/dist/diagnostics.js

@@ -3000,6 +3000,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,
@@ -5728,6 +5729,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -5751,6 +5753,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -6217,6 +6220,112 @@ var buildAiHookContext = ({
   };
 };
 
+// src/researchEntryPolicy.ts
+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);
@@ -6755,6 +6864,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(
@@ -7465,7 +7580,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7563,6 +7679,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,

package/dist/diagnostics.mjs

@@ -2,7 +2,7 @@ import {
   getRuntimeDeployment,
   loadResolvedRuntimeStrategies
 } from "./chunk-BO42QWAB.mjs";
-import "./chunk-SKY2HNZU.mjs";
+import "./chunk-KOV3U6ZZ.mjs";
 import "./chunk-UL5Z46JL.mjs";
 import "./chunk-LZDXRXIU.mjs";
 import "./chunk-YR55Q355.mjs";

package/dist/mcp.js

@@ -2994,6 +2994,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,
@@ -5722,6 +5723,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -5745,6 +5747,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -6211,6 +6214,112 @@ var buildAiHookContext = ({
   };
 };
 
+// src/researchEntryPolicy.ts
+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);
@@ -6749,6 +6858,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(
@@ -7459,7 +7574,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7557,6 +7673,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,

package/dist/mcp.mjs

@@ -7,7 +7,7 @@ import {
   listRuntimeDeployments,
   loadResolvedRuntimeStrategies
 } from "./chunk-BO42QWAB.mjs";
-import "./chunk-SKY2HNZU.mjs";
+import "./chunk-KOV3U6ZZ.mjs";
 import {
   ensureIndicatorPluginsLoaded
 } from "./chunk-UL5Z46JL.mjs";

package/dist/registry.js

@@ -2996,6 +2996,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,
@@ -5724,6 +5725,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -5747,6 +5749,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -6213,6 +6216,112 @@ var buildAiHookContext = ({
   };
 };
 
+// src/researchEntryPolicy.ts
+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);
@@ -6751,6 +6860,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(
@@ -7461,7 +7576,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7559,6 +7675,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,

package/dist/registry.mjs

@@ -1,5 +1,5 @@
 import "./chunk-JQOLTLEY.mjs";
-import "./chunk-SKY2HNZU.mjs";
+import "./chunk-KOV3U6ZZ.mjs";
 import {
   ensureIndicatorPluginsLoaded,
   ensureStrategyPluginsLoaded,