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

package/dist/diagnostics.mjs

@@ -2,7 +2,7 @@ import {
   getRuntimeDeployment,
   loadResolvedRuntimeStrategies
 } from "./chunk-BO42QWAB.mjs";
-import "./chunk-SKY2HNZU.mjs";
+import "./chunk-K56EW2BB.mjs";
 import "./chunk-UL5Z46JL.mjs";
 import "./chunk-LZDXRXIU.mjs";
 import "./chunk-YR55Q355.mjs";
@@ -95,10 +95,10 @@ var parseRuntimeEvidenceDeploymentSnapshot = (value) => {
 };
 var activeRuntimeEvidenceStrategies = (deployment) => deployment.enabled ? deployment.strategies.filter((strategy) => strategy.enabled) : [];
 var unwrapRuntimeEvidenceRows = (value, field) => (Array.isArray(value) ? value : []).map((candidate) => {
-  const record = isRecord(candidate) ? candidate : null;
-  const nested = record && isRecord(record[field]) ? record[field] : null;
-  return nested ?? record;
-}).filter((record) => record != null);
+  const record2 = isRecord(candidate) ? candidate : null;
+  const nested = record2 && isRecord(record2[field]) ? record2[field] : null;
+  return nested ?? record2;
+}).filter((record2) => record2 != null);
 var assertCurrentRuntimeEvidenceArtifact = (artifact) => {
   if (!isRecord(artifact) || artifact.reportType !== "runtime-evidence") {
     throw new Error("Invalid runtime evidence artifact");
@@ -840,7 +840,168 @@ var verifyRuntimeFeedbackReplaySource = async ({
   });
   return { feedback, runtimeEvidence };
 };
+
+// src/diagnostics/mcpFeedbackContract.ts
+var MCP_FEEDBACK_CONTRACT = {
+  version: 1,
+  hostProtocolVersion: 2,
+  replayQueue: {
+    waitingStates: ["waiting_resources", "waiting_executor"],
+    automaticFailedRetries: false
+  },
+  artifactEncoding: "base64",
+  maximumChunkBytes: 48e3,
+  artifactFiles: ["payload", "manifest.json", ".complete", "replay.log"],
+  requiredTools: [
+    "tradejs_info",
+    "diagnostics_list_reports",
+    "diagnostics_get_report",
+    "artifact_get",
+    "job_get",
+    "job_get_logs"
+  ]
+};
+var assertMcpFeedbackContract = (version, tools) => {
+  if (version !== MCP_FEEDBACK_CONTRACT.version)
+    throw new Error("MCP feedback contract version mismatch");
+  for (const name of MCP_FEEDBACK_CONTRACT.requiredTools)
+    if (!tools.some((tool) => tool.name === name))
+      throw new Error(`MCP feedback requires tool ${name}`);
+  const properties = tools.find((tool) => tool.name === "artifact_get")?.inputSchema.properties;
+  if (!properties || !("file" in properties))
+    throw new Error(
+      "MCP feedback requires artifact_get.file; refresh the client tool schema"
+    );
+};
+
+// src/diagnostics/mcpBundleDownload.ts
+import { createHash as createHash4 } from "crypto";
+import fs4 from "fs/promises";
+import path4 from "path";
+var McpReadTransportError = class extends Error {
+  constructor(message, retryAfterMs) {
+    super(message);
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var digest = (bytes) => createHash4("sha256").update(bytes).digest("hex");
+var exists = async (file) => fs4.lstat(file).catch((error) => {
+  if (error.code === "ENOENT") return void 0;
+  throw error;
+});
+var checkFile = async (file) => {
+  const stat = await exists(file);
+  if (stat && (!stat.isFile() || stat.isSymbolicLink()))
+    throw new Error("Invalid local bundle file");
+  return stat;
+};
+var downloadMcpBundle = async ({
+  descriptor,
+  root,
+  contractVersion,
+  tools,
+  readChunk,
+  wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+}) => {
+  assertMcpFeedbackContract(contractVersion, tools);
+  if (!/^[a-f0-9]{64}$/.test(descriptor.id))
+    throw new Error("Invalid artifact identity");
+  const required = ["payload", "manifest.json", ".complete"];
+  if (descriptor.kind === "runtime-feedback-replay")
+    required.push("replay.log");
+  for (const name of required) {
+    const matches = descriptor.files.filter((f) => f.file === name);
+    if (matches.length !== 1 || !matches[0].available || !Number.isSafeInteger(matches[0].bytes) || matches[0].bytes < 0 || !/^[a-f0-9]{64}$/.test(matches[0].sha256))
+      throw new Error(`Incomplete bundle descriptor: ${name}`);
+  }
+  const bundleDir = path4.join(root, descriptor.id);
+  await fs4.mkdir(bundleDir, { recursive: true });
+  const dir = await fs4.lstat(bundleDir);
+  if (dir.isSymbolicLink()) throw new Error("Invalid bundle directory");
+  const lock = path4.join(bundleDir, ".download-lock");
+  await fs4.mkdir(lock);
+  try {
+    for (const name of [
+      ...required.filter((f) => f !== ".complete"),
+      ".complete"
+    ]) {
+      const expected = descriptor.files.find((f) => f.file === name);
+      if (!expected) throw new Error("Missing bundle file");
+      const filename = name === "payload" ? descriptor.kind === "runtime-evidence" ? "runtime-evidence.json" : "replay-runtime-evidence.json" : name;
+      const target = path4.join(bundleDir, filename);
+      const verified = await checkFile(target);
+      if (verified) {
+        if (verified.size !== expected.bytes || digest(await fs4.readFile(target)) !== expected.sha256)
+          throw new Error("Local bundle checksum mismatch");
+        continue;
+      }
+      const partial = target + ".part";
+      const checkpoint = partial + ".json";
+      const identity = JSON.stringify({
+        artifactId: descriptor.id,
+        file: name,
+        bytes: expected.bytes,
+        sha256: expected.sha256
+      });
+      await checkFile(checkpoint);
+      const stat = await checkFile(partial);
+      if (stat) {
+        if (await fs4.readFile(checkpoint, "utf8") !== identity || stat.size > expected.bytes)
+          throw new Error("Artifact changed during download");
+      } else {
+        if (await checkFile(checkpoint)) {
+          if (await fs4.readFile(checkpoint, "utf8") !== identity)
+            throw new Error("Artifact changed during download");
+        } else await fs4.writeFile(checkpoint, identity, { flag: "wx" });
+      }
+      let offset = stat?.size ?? 0;
+      if (!stat) await fs4.writeFile(partial, Buffer.alloc(0), { flag: "wx" });
+      while (offset < expected.bytes) {
+        const request = {
+          artifactId: descriptor.id,
+          file: name,
+          offset,
+          length: MCP_FEEDBACK_CONTRACT.maximumChunkBytes
+        };
+        let response;
+        for (let attempt = 0; ; attempt++) {
+          try {
+            response = await readChunk(request);
+            break;
+          } catch (error) {
+            if (!(error instanceof McpReadTransportError) || attempt >= 3)
+              throw error;
+            await wait(
+              Math.max([2e3, 5e3, 1e4][attempt], error.retryAfterMs ?? 0)
+            );
+          }
+        }
+        if (!record(response) || response.id !== descriptor.id || response.file !== name || response.offset !== offset || response.bytes !== expected.bytes || response.sha256 !== expected.sha256 || response.encoding !== "base64" || typeof response.data !== "string" || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+          response.data
+        ))
+          throw new Error("Invalid artifact chunk identity");
+        const bytes = Buffer.from(response.data, "base64");
+        const next = offset + bytes.length;
+        if (!bytes.length || bytes.length > request.length || next > expected.bytes || response.nextOffset !== (next === expected.bytes ? null : next))
+          throw new Error("Invalid artifact chunk range");
+        await fs4.appendFile(partial, bytes);
+        offset = next;
+      }
+      if (digest(await fs4.readFile(partial)) !== expected.sha256)
+        throw new Error("Downloaded bundle checksum mismatch");
+      await fs4.rename(partial, target);
+      await fs4.unlink(checkpoint);
+    }
+    const bundle = descriptor.kind === "runtime-evidence" ? await verifyRuntimeEvidenceBundle(bundleDir) : await verifyRuntimeFeedbackReplayBundle(bundleDir);
+    return bundle;
+  } finally {
+    await fs4.rmdir(lock);
+  }
+};
 export {
+  MCP_FEEDBACK_CONTRACT,
+  McpReadTransportError,
   RUNTIME_EVIDENCE_COMPLETE_FILE,
   RUNTIME_EVIDENCE_MANIFEST_FILE,
   RUNTIME_EVIDENCE_PAYLOAD_FILE,
@@ -850,8 +1011,10 @@ export {
   RUNTIME_FEEDBACK_REPLAY_FILE,
   activeRuntimeEvidenceStrategies,
   assertCurrentRuntimeEvidenceArtifact,
+  assertMcpFeedbackContract,
   discoverRuntimeEvidenceBundles,
   discoverRuntimeFeedbackReplayBundles,
+  downloadMcpBundle,
   parseRuntimeEvidenceDeploymentSnapshot,
   parseRuntimeEvidenceProducer,
   publishRuntimeEvidenceBundle,

package/dist/mcp.d.mts

@@ -12,7 +12,7 @@ declare const redactMcpJobLog: (line: string) => string;
 /** Offsets refer to the retained worker tail, which may shift while running. */
 declare const readMcpJobLogs: (principal: McpPrincipal, id: string, offset?: number, limit?: number) => Promise<{
     jobId: string;
-    status: "completed" | "failed" | "running" | "queued" | "cancelled";
+    status: "running" | "completed" | "failed" | "queued" | "waiting_resources" | "waiting_executor" | "cancelled";
     updatedAt: number;
     offset: number;
     nextOffset: number | null;
@@ -30,7 +30,7 @@ declare const publicMcpJob: (job: McpJob) => {
     userName: string;
     clientId: string;
     kind: "backtest" | "runtime-evidence" | "runtime-feedback-replay";
-    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    status: "queued" | "waiting_resources" | "waiting_executor" | "running" | "completed" | "failed" | "cancelled";
     createdAt: number;
     updatedAt: number;
     startedAt?: number;

package/dist/mcp.d.ts

@@ -12,7 +12,7 @@ declare const redactMcpJobLog: (line: string) => string;
 /** Offsets refer to the retained worker tail, which may shift while running. */
 declare const readMcpJobLogs: (principal: McpPrincipal, id: string, offset?: number, limit?: number) => Promise<{
     jobId: string;
-    status: "completed" | "failed" | "running" | "queued" | "cancelled";
+    status: "running" | "completed" | "failed" | "queued" | "waiting_resources" | "waiting_executor" | "cancelled";
     updatedAt: number;
     offset: number;
     nextOffset: number | null;
@@ -30,7 +30,7 @@ declare const publicMcpJob: (job: McpJob) => {
     userName: string;
     clientId: string;
     kind: "backtest" | "runtime-evidence" | "runtime-feedback-replay";
-    status: "queued" | "running" | "completed" | "failed" | "cancelled";
+    status: "queued" | "waiting_resources" | "waiting_executor" | "running" | "completed" | "failed" | "cancelled";
     createdAt: number;
     updatedAt: number;
     startedAt?: number;

package/dist/mcp.js

@@ -6211,6 +6211,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 +6855,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 +7571,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7557,6 +7670,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,
@@ -8912,7 +9041,10 @@ var cancelMcpJob = async (principal, id) => {
     const job = await readMcpJob(principal.userName, id);
     if (job.clientId !== principal.clientId)
       throw new Error("Only the submitting client can cancel this job");
-    if (!["queued", "running"].includes(job.status)) return job;
+    if (!["queued", "waiting_resources", "waiting_executor", "running"].includes(
+      job.status
+    ))
+      return job;
     const next = {
       ...job,
       cancelRequested: true,

package/dist/mcp.mjs

@@ -7,7 +7,7 @@ import {
   listRuntimeDeployments,
   loadResolvedRuntimeStrategies
 } from "./chunk-BO42QWAB.mjs";
-import "./chunk-SKY2HNZU.mjs";
+import "./chunk-K56EW2BB.mjs";
 import {
   ensureIndicatorPluginsLoaded
 } from "./chunk-UL5Z46JL.mjs";
@@ -236,7 +236,10 @@ var cancelMcpJob = async (principal, id) => {
     const job = await readMcpJob(principal.userName, id);
     if (job.clientId !== principal.clientId)
       throw new Error("Only the submitting client can cancel this job");
-    if (!["queued", "running"].includes(job.status)) return job;
+    if (!["queued", "waiting_resources", "waiting_executor", "running"].includes(
+      job.status
+    ))
+      return job;
     const next = {
       ...job,
       cancelRequested: true,

package/dist/registry.js

@@ -6213,6 +6213,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 +6857,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 +7573,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7559,6 +7672,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-K56EW2BB.mjs";
 import {
   ensureIndicatorPluginsLoaded,
   ensureStrategyPluginsLoaded,