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

package/dist/runtimeDashboard.js

@@ -3978,6 +3978,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,
@@ -6706,6 +6707,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -6729,6 +6731,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -7195,6 +7198,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);
@@ -7733,6 +7842,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(
@@ -8443,7 +8558,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -8541,6 +8657,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/runtimeDashboard.mjs

@@ -9,7 +9,7 @@ import {
   listRuntimeDeployments,
   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/runtimeStrategies.js

@@ -2975,6 +2975,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,
@@ -5703,6 +5704,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -5726,6 +5728,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -6192,6 +6195,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);
@@ -6730,6 +6839,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(
@@ -7440,7 +7555,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7538,6 +7654,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/runtimeStrategies.mjs

@@ -9,7 +9,7 @@ import {
   resolveRuntimeComposition,
   verifyRuntimeDeclaration
 } 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/strategies.js

@@ -3068,6 +3068,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,
@@ -5965,6 +5966,7 @@ var executeEntryOrder = async ({
       openFee: estimatedOpenFee,
       totalFee: estimatedOpenFee,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       universe: signal.universe,
       assetClass: signal.assetClass,
       accountId: signal.accountId,
@@ -5988,6 +5990,7 @@ var executeEntryOrder = async ({
       addedQty: filledQty,
       addedEntryPrice: fillPrice,
       entryTimestamp: timestamp,
+      ...signal.orderLeverage ? { orderLeverage: signal.orderLeverage } : {},
       fee: estimatedOpenFee,
       accountId: signal.accountId,
       deploymentId: signal.deploymentId
@@ -6454,6 +6457,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);
@@ -6992,6 +7101,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(
@@ -7702,7 +7817,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7800,6 +7916,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/strategies.mjs

@@ -23,7 +23,7 @@ import {
   resolveHyperliquidPerpFromSignalSymbol,
   resolveStrategyConfig,
   validateEntryProtectionAtArrival
-} from "./chunk-SKY2HNZU.mjs";
+} from "./chunk-KOV3U6ZZ.mjs";
 import {
   DEFAULT_AI_MODEL,
   MAX_AI_SERIES_POINTS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tradejs/node",
-  "version": "3.1.29-beta.283",
+  "version": "3.1.29-beta.285",
   "description": "Node-only runtime for the TradeJS TypeScript framework: strategies, backtests, Pine strategy loading, and plugin registries.",
   "keywords": [
     "tradejs",
@@ -105,9 +105,9 @@
   "dependencies": {
     "@langchain/core": "^1.2.3",
     "@langchain/openai": "^1.5.5",
-    "@tradejs/core": "^3.1.29-beta.283",
-    "@tradejs/infra": "^3.1.29-beta.283",
-    "@tradejs/types": "^3.1.29-beta.283",
+    "@tradejs/core": "^3.1.29-beta.285",
+    "@tradejs/infra": "^3.1.29-beta.285",
+    "@tradejs/types": "^3.1.29-beta.285",
     "@types/node": "^24",
     "chalk": "4.1.2",
     "ioredis": "5.11.1",
@@ -120,7 +120,7 @@
     "typescript": "^5.9"
   },
   "devDependencies": {
-    "@tradejs/indicators": "^3.1.29-beta.283",
+    "@tradejs/indicators": "^3.1.29-beta.285",
     "@tradejs/strategy-adaptive-momentum-ribbon": "3.0.5",
     "@tradejs/strategy-hyperliquid-consensus": "3.0.5",
     "@tradejs/strategy-kit": "3.0.6",