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

package/dist/diagnostics.d.ts

@@ -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 };

package/dist/diagnostics.js

@@ -43,7 +43,7 @@ var init_jevInput = __esm({
     import_data = require("@tradejs/core/data");
     import_jev = require("@tradejs/core/jev");
     object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
-    at = (value, ...path7) => path7.reduce((current, key) => object(current)[key], value);
+    at = (value, ...path8) => path8.reduce((current, key) => object(current)[key], value);
     finite = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
     fact = (value) => {
       if (value == null || typeof value === "boolean") return value ?? null;
@@ -453,25 +453,25 @@ var init_jevTraining = __esm({
           "Jev training is bounded to 20000 rows; select a frozen sample first"
         );
       for (const row of rows) {
-        const record = row?.record;
-        if (row?.schema !== "tradejs-jev-study/v4" || !row.signalId || record?.schema !== "tradejs-jev-record/v4" || record.input?.schema !== "tradejs-jev-input/v4" || record.input.questionSet !== import_jev2.JEV_QUESTION_SET || !Number.isFinite(record.input.timestamp) || record.inputHash !== (0, import_jev3.jevHash)(record.input) || record.questionsHash !== (0, import_jev3.jevHash)(questionsForJevInput(record.input)) || record.id !== (0, import_jev3.jevHash)({
-          inputHash: record.inputHash,
-          questionsHash: record.questionsHash,
-          provider: record.provider
+        const record2 = row?.record;
+        if (row?.schema !== "tradejs-jev-study/v4" || !row.signalId || record2?.schema !== "tradejs-jev-record/v4" || record2.input?.schema !== "tradejs-jev-input/v4" || record2.input.questionSet !== import_jev2.JEV_QUESTION_SET || !Number.isFinite(record2.input.timestamp) || record2.inputHash !== (0, import_jev3.jevHash)(record2.input) || record2.questionsHash !== (0, import_jev3.jevHash)(questionsForJevInput(record2.input)) || record2.id !== (0, import_jev3.jevHash)({
+          inputHash: record2.inputHash,
+          questionsHash: record2.questionsHash,
+          provider: record2.provider
         }))
           throw new Error("Invalid Jev study provenance");
-        (0, import_jev3.validateJevResponse)(record.response, record.input.questions);
+        (0, import_jev3.validateJevResponse)(record2.response, record2.input.questions);
         for (const dimension of import_jev2.JEV_DIMENSIONS) {
-          const expected = record.input.questions.includes(dimension) ? record.response.answers[dimension].score / (0, import_jev3.jevScoreMaximum)(dimension) : null;
-          if (record.scores[dimension] !== expected)
+          const expected = record2.input.questions.includes(dimension) ? record2.response.answers[dimension].score / (0, import_jev3.jevScoreMaximum)(dimension) : null;
+          if (record2.scores[dimension] !== expected)
             throw new Error("Jev study scores do not match the teacher response");
         }
         if (row.profit != null && !Number.isFinite(row.profit))
           throw new Error("Invalid study outcome");
-        const prior = unique.get(record.inputHash);
-        if (prior && (prior.record.id !== record.id || prior.profit !== row.profit || (0, import_jev3.jevHash)(prior.record.response) !== (0, import_jev3.jevHash)(record.response)))
+        const prior = unique.get(record2.inputHash);
+        if (prior && (prior.record.id !== record2.id || prior.profit !== row.profit || (0, import_jev3.jevHash)(prior.record.response) !== (0, import_jev3.jevHash)(record2.response)))
           throw new Error("Conflicting duplicated Jev sample");
-        unique.set(record.inputHash, row);
+        unique.set(record2.inputHash, row);
       }
       const ordered = [...unique.values()].sort(
         (a, b) => a.record.input.timestamp - b.record.input.timestamp || a.record.id.localeCompare(b.record.id)
@@ -777,6 +777,8 @@ var init_jevTraining = __esm({
 // src/diagnostics.ts
 var diagnostics_exports = {};
 __export(diagnostics_exports, {
+  MCP_FEEDBACK_CONTRACT: () => MCP_FEEDBACK_CONTRACT,
+  McpReadTransportError: () => McpReadTransportError,
   RUNTIME_EVIDENCE_COMPLETE_FILE: () => RUNTIME_EVIDENCE_COMPLETE_FILE,
   RUNTIME_EVIDENCE_MANIFEST_FILE: () => RUNTIME_EVIDENCE_MANIFEST_FILE,
   RUNTIME_EVIDENCE_PAYLOAD_FILE: () => RUNTIME_EVIDENCE_PAYLOAD_FILE,
@@ -786,8 +788,10 @@ __export(diagnostics_exports, {
   RUNTIME_FEEDBACK_REPLAY_FILE: () => RUNTIME_FEEDBACK_REPLAY_FILE,
   activeRuntimeEvidenceStrategies: () => activeRuntimeEvidenceStrategies,
   assertCurrentRuntimeEvidenceArtifact: () => assertCurrentRuntimeEvidenceArtifact,
+  assertMcpFeedbackContract: () => assertMcpFeedbackContract,
   discoverRuntimeEvidenceBundles: () => discoverRuntimeEvidenceBundles,
   discoverRuntimeFeedbackReplayBundles: () => discoverRuntimeFeedbackReplayBundles,
+  downloadMcpBundle: () => downloadMcpBundle,
   parseRuntimeEvidenceDeploymentSnapshot: () => parseRuntimeEvidenceDeploymentSnapshot,
   parseRuntimeEvidenceProducer: () => parseRuntimeEvidenceProducer,
   publishRuntimeEvidenceBundle: () => publishRuntimeEvidenceBundle,
@@ -982,24 +986,24 @@ var evaluateJevInput = async ({
     promise = getRecord();
     pending.set(pendingKey, promise);
   }
-  let record;
+  let record2;
   try {
-    record = await promise;
+    record2 = await promise;
   } finally {
     pending.delete(pendingKey);
   }
   return {
-    record,
+    record: record2,
     assessment: {
       ...base,
       status: "available",
       recordId: id,
-      model: record.response.model,
-      scores: record.scores,
+      model: record2.response.model,
+      scores: record2.scores,
       confidence: Object.fromEntries(
         import_jev4.JEV_DIMENSIONS.map((key) => [
           key,
-          record.response.answers[key]?.confidence ?? null
+          record2.response.answers[key]?.confidence ?? null
         ])
       )
     }
@@ -2922,7 +2926,7 @@ var recordRuntimeTradeOpen = async (params) => {
   if (!userName) {
     return null;
   }
-  const record = {
+  const record2 = {
     ...params,
     entryCount: 1,
     lastEntryPrice: params.entryPrice,
@@ -2936,33 +2940,33 @@ var recordRuntimeTradeOpen = async (params) => {
     exitTimestamp: null,
     lastSyncedAt: now()
   };
-  const dayKey = (0, import_time.getRuntimeStorageDayKey)(record.entryTimestamp);
-  const runtimeScopeId = record.deploymentId ?? record.accountId;
+  const dayKey = (0, import_time.getRuntimeStorageDayKey)(record2.entryTimestamp);
+  const runtimeScopeId = record2.deploymentId ?? record2.accountId;
   try {
     await Promise.all([
-      (0, import_redis2.setData)(import_redis2.redisKeys.runtimeTrade(userName, record.orderId), record, {
+      (0, import_redis2.setData)(import_redis2.redisKeys.runtimeTrade(userName, record2.orderId), record2, {
         expire: 0
       }),
       (0, import_redis2.setHashJsonField)(
         import_redis2.redisKeys.runtimeTradeBucket(userName, dayKey),
-        record.orderId,
-        record,
+        record2.orderId,
+        record2,
         { expire: 0 }
       ),
       (0, import_redis2.setData)(
-        import_redis2.redisKeys.runtimeActiveTrade(userName, record.symbol, runtimeScopeId),
-        { orderId: record.orderId },
+        import_redis2.redisKeys.runtimeActiveTrade(userName, record2.symbol, runtimeScopeId),
+        { orderId: record2.orderId },
         { expire: 0 }
       )
     ]);
   } catch (error) {
     import_logger2.logger.error(
       "runtime trade open journal failed: %s %s",
-      record.symbol,
+      record2.symbol,
       error?.message || String(error)
     );
   }
-  return record;
+  return record2;
 };
 var recordRuntimeTradeIncrease = async (params) => {
   const {
@@ -6213,6 +6217,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 +6861,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 +7577,8 @@ var createStrategyRuntime = ({
           await enrichSignalWithMarketContextStages({
             signal,
             env,
-            includeHyperliquidWhales: false
+            includeHyperliquidWhales: Boolean(researchEntryPolicy),
+            ...researchEntryPolicy ? { coinMarketCapEnabled: true } : {}
           });
           if (jev) {
             await assessSignalWithJev({
@@ -7559,6 +7676,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,
@@ -8287,10 +8420,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 = isRecord2(candidate) ? candidate : null;
-  const nested = record && isRecord2(record[field]) ? record[field] : null;
-  return nested ?? record;
-}).filter((record) => record != null);
+  const record2 = isRecord2(candidate) ? candidate : null;
+  const nested = record2 && isRecord2(record2[field]) ? record2[field] : null;
+  return nested ?? record2;
+}).filter((record2) => record2 != null);
 var assertCurrentRuntimeEvidenceArtifact = (artifact) => {
   if (!isRecord2(artifact) || artifact.reportType !== "runtime-evidence") {
     throw new Error("Invalid runtime evidence artifact");
@@ -9032,8 +9165,169 @@ 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
+var import_node_crypto8 = require("crypto");
+var import_promises6 = __toESM(require("fs/promises"));
+var import_node_path6 = __toESM(require("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) => (0, import_node_crypto8.createHash)("sha256").update(bytes).digest("hex");
+var exists = async (file) => import_promises6.default.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 = import_node_path6.default.join(root, descriptor.id);
+  await import_promises6.default.mkdir(bundleDir, { recursive: true });
+  const dir = await import_promises6.default.lstat(bundleDir);
+  if (dir.isSymbolicLink()) throw new Error("Invalid bundle directory");
+  const lock = import_node_path6.default.join(bundleDir, ".download-lock");
+  await import_promises6.default.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 = import_node_path6.default.join(bundleDir, filename);
+      const verified = await checkFile(target);
+      if (verified) {
+        if (verified.size !== expected.bytes || digest(await import_promises6.default.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 import_promises6.default.readFile(checkpoint, "utf8") !== identity || stat.size > expected.bytes)
+          throw new Error("Artifact changed during download");
+      } else {
+        if (await checkFile(checkpoint)) {
+          if (await import_promises6.default.readFile(checkpoint, "utf8") !== identity)
+            throw new Error("Artifact changed during download");
+        } else await import_promises6.default.writeFile(checkpoint, identity, { flag: "wx" });
+      }
+      let offset = stat?.size ?? 0;
+      if (!stat) await import_promises6.default.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 import_promises6.default.appendFile(partial, bytes);
+        offset = next;
+      }
+      if (digest(await import_promises6.default.readFile(partial)) !== expected.sha256)
+        throw new Error("Downloaded bundle checksum mismatch");
+      await import_promises6.default.rename(partial, target);
+      await import_promises6.default.unlink(checkpoint);
+    }
+    const bundle = descriptor.kind === "runtime-evidence" ? await verifyRuntimeEvidenceBundle(bundleDir) : await verifyRuntimeFeedbackReplayBundle(bundleDir);
+    return bundle;
+  } finally {
+    await import_promises6.default.rmdir(lock);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MCP_FEEDBACK_CONTRACT,
+  McpReadTransportError,
   RUNTIME_EVIDENCE_COMPLETE_FILE,
   RUNTIME_EVIDENCE_MANIFEST_FILE,
   RUNTIME_EVIDENCE_PAYLOAD_FILE,
@@ -9043,8 +9337,10 @@ var verifyRuntimeFeedbackReplaySource = async ({
   RUNTIME_FEEDBACK_REPLAY_FILE,
   activeRuntimeEvidenceStrategies,
   assertCurrentRuntimeEvidenceArtifact,
+  assertMcpFeedbackContract,
   discoverRuntimeEvidenceBundles,
   discoverRuntimeFeedbackReplayBundles,
+  downloadMcpBundle,
   parseRuntimeEvidenceDeploymentSnapshot,
   parseRuntimeEvidenceProducer,
   publishRuntimeEvidenceBundle,