@citeark/agent 0.3.20

package/src/contracts/execution-contract.mjs

@@ -0,0 +1,819 @@
+import { executionGraphContext } from '../research/execution-graph-context.mjs';
+import { reproductionScopeIssues } from "../research/reproduction-scope.mjs";
+import { revisedInventoryClaims } from "../research/inventory-revisions.mjs";
+import { publicContractPolicyIssues, researchPublicContract } from "./public-contract.mjs";
+import { randomBytes } from "node:crypto";
+
+import { capPolicyCommitment } from "../cap/v2/core.mjs";
+import { CiteArkError, readJson, safeRelativePath, sha256Value, writeJson } from "../util.mjs";
+import {
+  loadResearchStructure,
+} from "../research/structure.mjs";
+import {
+  describeSupportedPreflightSchemaVersions,
+  MAX_PREFLIGHT_MINUTES,
+  MIN_PUBLIC_ASSET_PREFLIGHT_MINUTES,
+  PREFLIGHT_CHECK_KINDS,
+  supportsPreflightSchemaVersion,
+} from "./preflight-schema.mjs";
+import { resolveComputeRequirement, validateDeclaredComputeRequirement } from "../compute/requirements.mjs";
+import { resolveVerificationTolerance } from "../verification/tolerance.mjs";
+import { EXECUTION_MODES } from "./execution-mode.mjs";
+import { executionWorkloadIssues } from "./execution-workload.mjs";
+import { measurementHardwareIssues } from "../compute/measurement-hardware.mjs";
+import {
+  executionTimeoutCapMinutes,
+  LEGACY_EXECUTION_TIMEOUT_FALLBACK_MINUTES,
+} from "./execution-timeouts.mjs";
+import {
+  ASSET_ACQUISITION_MODES,
+  ASSET_SCIENTIFIC_ROLES,
+} from "../assets/plan.mjs";
+
+export const EXECUTION_CONTRACT_VERSION = "1.0";
+export const VERIFICATION_POLICY_VERSION = "1.0";
+
+export async function createExecutionContract({
+  researchPath,
+  claimId,
+  experimentId,
+  executionClaimIds,
+  restrictToAssignedMeasurements = false,
+  outputPath,
+  policyPath,
+  tolerance,
+}) {
+  const research = await loadResearchStructure(researchPath);
+  if (research.compilationStage === "inventory") throw new CiteArkError("研究清单尚未进行复现准备；请先根据固定清单生成执行计划，再创建执行契约");
+  const claim = research.claims.find((item) => item.id === claimId);
+  if (!claim) throw new CiteArkError(`找不到 claim：${claimId}`);
+  const experiment = experimentId
+    ? research.experiments.find((item) => item.id === experimentId)
+    : research.experiments.find((item) => item.claimIds.includes(claimId));
+  if (!experiment) throw new CiteArkError(`找不到绑定 claim ${claimId} 的实验`);
+  if (!experiment.claimIds.includes(claimId)) throw new CiteArkError("实验没有绑定所选 claim");
+  const bindings = resolveMeasurementBindings(research, claim, experiment);
+  if (!bindings.length) throw new CiteArkError("claim 的报告指标与实验测量定义不匹配");
+  const requestedExecutionClaimIds = [...new Set(
+    Array.isArray(executionClaimIds) && executionClaimIds.length
+      ? executionClaimIds
+      : [claim.id],
+  )];
+  const executionClaims = requestedExecutionClaimIds.map((id) => {
+    const candidate = research.claims.find((item) => item.id === id);
+    if (!candidate) throw new CiteArkError(`找不到共享执行 claim：${id}`);
+    if (!experiment.claimIds.includes(id)) {
+      throw new CiteArkError(`共享执行 claim ${id} 没有绑定实验 ${experiment.id}`);
+    }
+    return candidate;
+  });
+  const executionBindings = deduplicateMeasurementBindings(
+    executionClaims.flatMap((candidate) =>
+      resolveMeasurementBindings(research, candidate, experiment)),
+  );
+  if (!executionBindings.length) {
+    throw new CiteArkError("共享执行单元没有可执行测量定义");
+  }
+  const claimMeasurementIds = [...new Set(executionClaims.flatMap((candidate) =>
+    candidate.reportedMeasurements.map((measurement) => measurement.id)))];
+  const measurementIds = executionBindings.map(({ measurementId }) => measurementId);
+  const boundMeasurementIds = new Set(measurementIds);
+  const uncoveredMeasurementIds = claimMeasurementIds.filter((measurementId) =>
+    !boundMeasurementIds.has(measurementId));
+  const paper = research.sources.find((source) => source.kind === "paper");
+  const editablePlan = experiment.protocol?.executionMode === "agent_planned";
+  const executionGoalBindings = editablePlan && !restrictToAssignedMeasurements && research.reproductionScope === undefined
+    ? deduplicateMeasurementBindings(executionClaims.flatMap((candidate) =>
+        candidate.reportedMeasurements.map((reported) => ({
+          measurementId: reported.id,
+          reported,
+          measurement: executionBindings.find(
+            (binding) => binding.measurementId === reported.id,
+          )?.measurement ?? reported,
+        }))))
+    : executionBindings;
+  const verificationBindings = editablePlan && !restrictToAssignedMeasurements && research.reproductionScope === undefined
+    ? claim.reportedMeasurements.map((reported) => ({
+        measurementId: reported.id,
+        reported,
+        measurement: bindings.find(
+          (binding) => binding.measurementId === reported.id,
+        )?.measurement ?? reported,
+      }))
+    : bindings;
+  const targets = verificationBindings.map(({ measurementId, reported, measurement }) => {
+    const resolvedTolerance = resolveVerificationTolerance({
+      unit: reported.unit,
+      tolerance: measurement.verificationTolerance ?? reported.verificationTolerance ?? tolerance,
+    });
+    return {
+      measurementId,
+      metric: reported.metric,
+      unit: reported.unit,
+      reportedValue: reported.value,
+      comparator: "absolute-difference",
+      tolerance: resolvedTolerance.value,
+      toleranceSource: resolvedTolerance.source,
+      evidenceBasis: reported.evidenceBasis ?? "reported_numeric",
+      ...(reported.extractionUncertainty !== undefined
+        ? { extractionUncertainty: reported.extractionUncertainty }
+        : {}),
+    };
+  });
+  const committedPolicy = { claimVersionId: claim.versionId, targets };
+  const commitmentNonce = randomBytes(16).toString("base64url");
+  const verificationPolicyCommitment = capPolicyCommitment({
+    nonce: commitmentNonce,
+    policy: committedPolicy,
+  });
+  const reconstructionFidelity = experiment.reconstructionFidelity
+    ?? (experiment.implementationOrigin === "citeark_reconstruction" ? "approximate" : "faithful");
+  const executionBudget = fidelityExecutionBudget(reconstructionFidelity, experiment);
+
+  const researchGraph = executionGraphContext(research, experiment);
+  const contractBody = {
+    ...(researchGraph ? { researchGraph } : {}),
+    schemaVersion: EXECUTION_CONTRACT_VERSION,
+    kind: "citeark.execution-contract",
+    name: `${research.work.id}-${claim.id}-${experiment.id}`,
+    research: {
+      workId: research.work.id,
+      claimId: claim.id,
+      claimVersionId: claim.versionId,
+      experimentId: experiment.id,
+      experimentVersionId: experiment.versionId,
+      measurementIds,
+      claimMeasurementIds,
+      ...(restrictToAssignedMeasurements ? { assignedMeasurementsOnly: true } : {}),
+      ...(requestedExecutionClaimIds.length > 1
+        ? { executionClaimIds: requestedExecutionClaimIds }
+        : {}),
+      claimCoverage: uncoveredMeasurementIds.length ? "partial" : "complete",
+      ...(uncoveredMeasurementIds.length ? { uncoveredMeasurementIds } : {}),
+    },
+    paper: { title: research.work.title, url: paper?.uri },
+    repository: experiment.repository,
+    claim: {
+      text: research.sourceInventory
+        ? `Evaluate the assigned source question ${claim.id}. Source context is not execution evidence; the private numeric verification policy is withheld until independent verification.`
+        : `Evaluate the protocol-bound claim ${claim.id}; the paper's reported outcome is intentionally withheld until independent verification.`,
+      source: `${claim.sourceLocator.sourceId}:${claim.sourceLocator.locator}`,
+    },
+    measurements: executionBindings.map(({ measurementId, reported, measurement }) => ({
+      measurementId,
+      metric: measurement.metric,
+      ...(measurement.quantityKind ? { quantityKind: measurement.quantityKind } : {}),
+      unit: measurement.unit,
+      ...blindMeasurementScope(reported, measurement),
+      parser: measurement.parser,
+    })),
+    protocol: experiment.protocol,
+    ...(editablePlan ? { workspacePlan: {
+      version: 2,
+      ...(research.sourceInventory ? { sourceInventory: executionInventoryContext(research.sourceInventory) } : {}),
+      measurements: executionGoalBindings.map(({ measurementId, reported, measurement }) => ({
+        measurementId, metric: reported.metric, unit: reported.unit,
+        ...blindMeasurementScope(reported, measurement),
+        source: reported.sourceLocator ?? claim.sourceLocator,
+      })),
+    } } : {}),
+    reproductionLevel: experiment.reproductionLevel,
+    ...(research.reproductionScope ? { reproductionScope: research.reproductionScope, requiredReproductionScope: experiment.requiredReproductionScope } : {}),
+    reconstructionFidelity,
+    computeRequirement: resolveComputeRequirement(experiment),
+    verificationPolicyCommitment,
+    agent: {
+      runtime: experiment.agent?.runtime ?? null,
+      model: experiment.agent?.model ?? null,
+      subagentModel: experiment.agent?.subagentModel ?? null,
+      autoCompactWindow: experiment.agent?.autoCompactWindow ?? 786432,
+      effort: experiment.agent?.effort ?? "max",
+      reasoningMode: experiment.agent?.reasoningMode ?? "standard",
+      maxTurns: executionBudget.maxTurns,
+      maxBudgetUsd: executionBudget.maxBudgetUsd,
+      ...(executionBudget.hardCaps ? {
+        budgetCaps: {
+          maxTurns: executionBudget.maxTurns,
+          maxBudgetUsd: executionBudget.maxBudgetUsd,
+        },
+      } : {}),
+      validationRetries: experiment.agent?.validationRetries ?? 1,
+    },
+    environment: {
+      image: experiment.environment?.image ?? "citeark-agent/runtime:0.2.0",
+      timeoutMinutes: executionBudget.timeoutMinutes,
+      cpus: experiment.environment?.cpus ?? 8,
+      memoryGb: experiment.environment?.memoryGb ?? 32,
+      shmGb: experiment.environment?.shmGb ?? 8,
+      gpu: experiment.environment?.gpu ?? "none",
+      networkAccess: true,
+    },
+  };
+  const contract = { ...contractBody, contractDigest: `sha256:${sha256Value(contractBody)}` };
+  const policyBody = {
+    schemaVersion: VERIFICATION_POLICY_VERSION,
+    kind: "citeark.private-verification-policy",
+    contractDigest: contract.contractDigest,
+    claimVersionId: claim.versionId,
+    targets,
+    commitment: {
+      algorithm: "citeark-policy-commitment-v1",
+      nonce: commitmentNonce,
+      digest: verificationPolicyCommitment,
+    },
+  };
+  const policy = { ...policyBody, policyDigest: `sha256:${sha256Value(policyBody)}` };
+  // Contract construction is a deterministic boundary. Validate before either
+  // file is published so schema drift can never masquerade as an Agent start.
+  validateExecutionContract(contract);
+  if (outputPath) await writeJson(outputPath, contract);
+  if (policyPath) await writeJson(policyPath, policy);
+  return { research, contract, policy };
+}
+
+export function fidelityExecutionBudget(fidelity, experiment = {}) {
+  const requested = {
+    maxTurns: positiveNumber(experiment.agent?.maxTurns, 120),
+    maxBudgetUsd: positiveNumber(experiment.agent?.maxBudgetUsd, 10),
+    timeoutMinutes: positiveNumber(
+      experiment.environment?.timeoutMinutes,
+      LEGACY_EXECUTION_TIMEOUT_FALLBACK_MINUTES,
+    ),
+  };
+  const caps = fidelity === "proxy"
+    ? { maxTurns: 30, maxBudgetUsd: 2, timeoutMinutes: executionTimeoutCapMinutes("proxy") }
+    : fidelity === "approximate"
+      ? { maxTurns: 80, maxBudgetUsd: 6, timeoutMinutes: executionTimeoutCapMinutes("approximate") }
+      : { ...requested, timeoutMinutes: executionTimeoutCapMinutes(fidelity) };
+  return {
+    maxTurns: Math.max(1, Math.floor(Math.min(requested.maxTurns, caps.maxTurns))),
+    maxBudgetUsd: Math.min(requested.maxBudgetUsd, caps.maxBudgetUsd),
+    timeoutMinutes: Math.min(requested.timeoutMinutes, caps.timeoutMinutes),
+    hardCaps: fidelity === "proxy" || fidelity === "approximate",
+  };
+}
+
+function positiveNumber(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
+}
+
+export async function loadExecutionContract(target) {
+  const contract = await readJson(target);
+  validateExecutionContract(contract);
+  return contract;
+}
+
+export async function loadVerificationPolicy(target, contract) {
+  const policy = await readJson(target);
+  const issues = [];
+  if (policy.schemaVersion !== VERIFICATION_POLICY_VERSION) issues.push(`policy.schemaVersion 必须是 ${VERIFICATION_POLICY_VERSION}`);
+  if (policy.kind !== "citeark.private-verification-policy") issues.push("policy.kind 无效");
+  if (policy.contractDigest !== contract.contractDigest) issues.push("policy 与 execution contract 未绑定");
+  if (policy.claimVersionId !== contract.research.claimVersionId) issues.push("policy 与 claim version 未绑定");
+  const contractMeasurements = [1, 2].includes(contract.workspacePlan?.version)
+    ? contract.workspacePlan.measurements : executionContractMeasurements(contract);
+  const targets = verificationPolicyTargets(policy);
+  if (!targets.length) issues.push("policy.targets 必须至少包含一个测量目标");
+  for (const [index, target] of targets.entries()) {
+    const measurement = contractMeasurements.find((item) => item.measurementId === target.measurementId);
+    if (!measurement || target.metric !== measurement.metric || target.unit !== measurement.unit) {
+      issues.push(`policy.targets[${index}] 与 contract measurement 不一致`);
+    }
+    if (typeof target.reportedValue !== "number" || !Number.isFinite(target.reportedValue)) issues.push(`policy.targets[${index}].reportedValue 无效`);
+    if (target.comparator !== "absolute-difference") issues.push(`policy.targets[${index}] 目前只支持 absolute-difference`);
+    if (typeof target.tolerance !== "number" || target.tolerance < 0) issues.push(`policy.targets[${index}].tolerance 无效`);
+    if (target.toleranceSource !== undefined) {
+      if (!target.toleranceSource || typeof target.toleranceSource !== "object") issues.push(`policy.targets[${index}].toleranceSource 无效`);
+      else if (!new Set(["explicit", "unit-default", "unconfigured"]).has(target.toleranceSource.kind)) issues.push(`policy.targets[${index}].toleranceSource.kind 无效`);
+      else {
+        if (target.toleranceSource.unit !== target.unit) issues.push(`policy.targets[${index}].toleranceSource.unit 与目标单位不一致`);
+        if (target.toleranceSource.kind === "unconfigured") {
+          if (target.tolerance !== 0) issues.push(`policy.targets[${index}] 未配置容差时 tolerance 必须为 0`);
+          if (typeof target.toleranceSource.reason !== "string" || !target.toleranceSource.reason.trim()) {
+            issues.push(`policy.targets[${index}] 未配置容差时必须记录原因`);
+          }
+        }
+      }
+    }
+    if (
+      target.evidenceBasis !== undefined
+      && !new Set(["reported_numeric", "digitized_figure", "derived_reported_relation"])
+        .has(target.evidenceBasis)
+    ) {
+      issues.push(`policy.targets[${index}].evidenceBasis 无效`);
+    }
+    if (
+      target.extractionUncertainty !== undefined
+      && (!Number.isFinite(target.extractionUncertainty) || target.extractionUncertainty < 0)
+    ) {
+      issues.push(`policy.targets[${index}].extractionUncertainty 无效`);
+    }
+  }
+  const committedPolicy = verificationPolicyCommitmentInput(policy);
+  const commitment = policy.commitment;
+  if (commitment?.algorithm !== "citeark-policy-commitment-v1") {
+    issues.push("policy.commitment.algorithm 无效");
+  } else {
+    try {
+      const observed = capPolicyCommitment({
+        nonce: commitment.nonce,
+        policy: committedPolicy,
+      });
+      if (commitment.digest !== observed) issues.push("policy.commitment.digest 与策略内容不一致");
+      if (contract.verificationPolicyCommitment !== observed) issues.push("policy commitment 与 execution contract 不一致");
+    } catch (error) {
+      issues.push(`policy.commitment 无效：${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const policyBody = { ...policy };
+  delete policyBody.policyDigest;
+  if (policy.policyDigest !== `sha256:${sha256Value(policyBody)}`) issues.push("policyDigest 与内容不一致");
+  if (issues.length) throw new CiteArkError(`私有验证策略校验失败：\n- ${issues.join("\n- ")}`);
+  return policy;
+}
+
+export function validateExecutionContract(contract) {
+  const issues = reproductionScopeIssues({ reproductionScope: contract?.reproductionScope, experiments: contract ? [contract] : [] });
+  if (contract?.campaign !== undefined) {
+    const campaign = contract.campaign;
+    if (campaign?.version !== 1 || !Array.isArray(campaign.members) || !campaign.members.length) {
+      issues.push("campaign 必须包含启动前绑定的实验目标");
+    } else {
+      const targets = new Set(), mapped = new Set();
+      for (const member of campaign.members) {
+        if (!member?.contract || member.contract.campaign) { issues.push("campaign 成员契约无效"); continue; }
+        try { validateExecutionContract(member.contract); } catch (error) { issues.push(error.message); }
+        const { experimentId, claimId } = member.contract.research ?? {};
+        const key = `${experimentId}:${claimId}`;
+        if (targets.has(key) || member.target?.experimentId !== experimentId || member.target?.claimId !== claimId) issues.push("campaign 目标绑定不一致或重复");
+        targets.add(key);
+        const ids = (member.contract.measurements ?? []).map(m => m.measurementId);
+        if (Object.keys(member.measurementMap ?? {}).length !== ids.length) issues.push("campaign 测量映射数量不一致");
+        for (const id of ids) {
+          const namespaced = `${experimentId}::${id}`;
+          if (member.measurementMap?.[id] !== namespaced) issues.push("campaign 测量必须绑定原实验身份");
+          mapped.add(namespaced);
+        }
+      }
+      const ids = (contract.measurements ?? []).map(m => m.measurementId);
+      if (mapped.size !== ids.length || ids.some(id => !mapped.has(id))) issues.push("campaign 的测量与成员范围不一致");
+      if (campaign.workloads !== undefined) {
+        const experiments = new Set(campaign.members.map(m => m.target?.experimentId));
+        const workIds = new Set();
+        if (!Array.isArray(campaign.workloads)) issues.push("campaign.workloads 必须是数组");
+        else for (const work of campaign.workloads) {
+          if (typeof work?.id !== "string" || !work.id || workIds.has(work.id)
+            || typeof work.description !== "string" || !work.description
+            || !Array.isArray(work.experimentIds) || !work.experimentIds.length
+            || work.experimentIds.some(id => !experiments.has(id))
+            || new Set(work.experimentIds).size !== work.experimentIds.length) {
+            issues.push("campaign.workloads 计算身份或使用实验无效");
+          }
+          workIds.add(work?.id);
+        }
+      }
+    }
+  }
+  if (contract?.schemaVersion !== EXECUTION_CONTRACT_VERSION) issues.push(`contract.schemaVersion 必须是 ${EXECUTION_CONTRACT_VERSION}`);
+  if (contract?.kind !== "citeark.execution-contract") issues.push("contract.kind 无效");
+  for (const path of [
+    [contract?.research?.workId, "research.workId"],
+    [contract?.research?.claimVersionId, "research.claimVersionId"],
+    [contract?.research?.experimentVersionId, "research.experimentVersionId"],
+    [contract?.repository?.url, "repository.url"],
+    [contract?.repository?.commit, "repository.commit"],
+  ]) {
+    if (typeof path[0] !== "string" || !path[0]) issues.push(`${path[1]} 必须是非空字符串`);
+  }
+  if (
+    contract?.repository?.implementationOrigin !== undefined
+    && !new Set(["official", "citeark_reconstruction"]).has(contract.repository.implementationOrigin)
+  ) {
+    issues.push("repository.implementationOrigin 无效");
+  }
+  if (
+    contract?.reconstructionFidelity !== undefined
+    && !new Set(["exact", "faithful", "approximate", "proxy"]).has(contract.reconstructionFidelity)
+  ) {
+    issues.push("reconstructionFidelity 无效");
+  }
+  validateContractPreflight(contract?.protocol?.preflight, issues);
+  if (
+    contract?.protocol?.executionMode !== undefined
+    && !EXECUTION_MODES.has(contract.protocol.executionMode)
+  ) {
+    issues.push("protocol.executionMode 无效");
+  }
+  if (
+    contract?.protocol?.executionMode === "agent_planned"
+    && (typeof contract.protocol.objective !== "string" || !contract.protocol.objective.trim())
+  ) {
+    issues.push("protocol.executionMode=agent_planned 时 protocol.objective 必须是非空字符串");
+  }
+  const measurements = executionContractMeasurements(contract);
+  if (!measurements.length) issues.push("contract.measurements 必须至少包含一个测量项");
+  const measurementIds = new Set();
+  for (const [index, measurement] of measurements.entries()) {
+    for (const [value, label] of [
+      [measurement.measurementId, "measurementId"],
+      [measurement.metric, "metric"],
+      [measurement.unit, "unit"],
+      [measurement.parser?.id, "parser.id"],
+      [measurement.parser?.version, "parser.version"],
+      [measurement.parser?.evidencePath, "parser.evidencePath"],
+    ]) {
+      if (typeof value !== "string" || !value) issues.push(`measurements[${index}].${label} 必须是非空字符串`);
+    }
+    if (
+      typeof measurement.parser?.evidencePath === "string"
+      && measurement.parser.evidencePath
+      && !safeRelativePath(measurement.parser.evidencePath)
+    ) {
+      issues.push(`measurements[${index}].parser.evidencePath 必须是安全相对路径`);
+    }
+    if (
+      measurement.dimensions !== undefined
+      && (
+        !measurement.dimensions
+        || typeof measurement.dimensions !== "object"
+        || Array.isArray(measurement.dimensions)
+      )
+    ) {
+      issues.push(`measurements[${index}].dimensions 必须是对象`);
+    }
+    if (
+      measurement.aggregation !== undefined
+      && (typeof measurement.aggregation !== "string" || !measurement.aggregation.trim())
+    ) {
+      issues.push(`measurements[${index}].aggregation 必须是非空字符串`);
+    }
+    if (measurementIds.has(measurement.measurementId)) issues.push(`contract measurementId 重复：${measurement.measurementId}`);
+    measurementIds.add(measurement.measurementId);
+    if (Object.hasOwn(measurement, "reportedValue")) issues.push("公开 contract 不得包含 reportedValue");
+  }
+  const declaredIds = Array.isArray(contract?.research?.measurementIds) ? contract.research.measurementIds : [];
+  if (declaredIds.length !== measurements.length || declaredIds.some((id) => !measurementIds.has(id))) {
+    issues.push("research.measurementIds 与 contract.measurements 不一致");
+  }
+  const claimMeasurementIds = Array.isArray(contract?.research?.claimMeasurementIds)
+    ? contract.research.claimMeasurementIds
+    : declaredIds;
+  const executionClaimIds = contract?.research?.executionClaimIds;
+  if (executionClaimIds !== undefined && (
+    !Array.isArray(executionClaimIds)
+    || executionClaimIds.length < 2
+    || new Set(executionClaimIds).size !== executionClaimIds.length
+    || executionClaimIds.some((id) => typeof id !== "string" || !id)
+    || !executionClaimIds.includes(contract.research.claimId)
+  )) {
+    issues.push("research.executionClaimIds 必须是包含当前 claim 的唯一非空字符串数组");
+  }
+  if (contract.workspacePlan !== undefined) {
+    const context = contract.workspacePlan.sourceInventory;
+    if (context !== undefined) {
+      if (context?.view !== "source-context" || !/^sha256:[0-9a-f]{64}$/.test(context?.digest ?? "")
+        || !Array.isArray(context.sources) || !Array.isArray(context.claims)
+        || !context.claims.some((claim) => claim?.id === contract.research.claimId)) {
+        issues.push("workspacePlan source inventory must identify the original context and assigned claim");
+      }
+      for (const claim of Array.isArray(context?.claims) ? context.claims : []) {
+        if (!Array.isArray(claim?.reportedMeasurements)
+          || claim.reportedMeasurements.some((measurement) => !measurement || typeof measurement !== "object"
+            || ["value", "reportedValue", "verificationTolerance"].some((key) => Object.hasOwn(measurement, key))))
+          issues.push("workspacePlan source context must omit structured reported targets and tolerances");
+      }
+    }
+    const goals = contract.workspacePlan?.measurements;
+    const allowedGoalIds = contract.reproductionScope || contract.research.assignedMeasurementsOnly ? declaredIds : claimMeasurementIds;
+    if (![1, 2].includes(contract.workspacePlan?.version) || contract.protocol?.executionMode !== "agent_planned"
+      || !Array.isArray(goals) || goals.length !== allowedGoalIds.length
+      || new Set((Array.isArray(goals) ? goals : []).map((item) => item?.measurementId)).size !== allowedGoalIds.length) {
+      issues.push("workspacePlan must enable version 1 or 2 for agent_planned with the allowed measurement catalog");
+    }
+    for (const goal of Array.isArray(goals) ? goals : []) {
+      if (!allowedGoalIds.includes(goal.measurementId) || !goal.metric || !goal.unit
+        || Object.hasOwn(goal, "value") || Object.hasOwn(goal, "reportedValue")) {
+        issues.push("workspacePlan measurements must retain claim identity and omit reported values");
+      }
+    }
+  }
+  const uncoveredMeasurementIds = Array.isArray(contract?.research?.uncoveredMeasurementIds)
+    ? contract.research.uncoveredMeasurementIds
+    : [];
+  if (new Set(claimMeasurementIds).size !== claimMeasurementIds.length || claimMeasurementIds.some((id) => typeof id !== "string" || !id)) {
+    issues.push("research.claimMeasurementIds 必须是唯一非空字符串数组");
+  }
+  if (declaredIds.some((id) => !claimMeasurementIds.includes(id))) {
+    issues.push("research.claimMeasurementIds 必须包含所有 research.measurementIds");
+  }
+  if (new Set(uncoveredMeasurementIds).size !== uncoveredMeasurementIds.length || uncoveredMeasurementIds.some((id) => !claimMeasurementIds.includes(id) || declaredIds.includes(id))) {
+    issues.push("research.uncoveredMeasurementIds 必须是 claim 中未执行的唯一 measurementId");
+  }
+  if (
+    contract?.research?.claimCoverage !== undefined
+    && !new Set(["complete", "partial"]).has(contract.research.claimCoverage)
+  ) {
+    issues.push("research.claimCoverage 无效");
+  }
+  if (contract?.research?.claimCoverage === "partial" && uncoveredMeasurementIds.length === 0) {
+    issues.push("research.claimCoverage=partial 时必须声明 uncoveredMeasurementIds");
+  }
+  if (contract?.research?.claimCoverage === "complete" && uncoveredMeasurementIds.length > 0) {
+    issues.push("research.claimCoverage=complete 时不能声明 uncoveredMeasurementIds");
+  }
+  issues.push(...publicContractPolicyIssues(researchPublicContract({
+    ...contract, compute: contract?.computeRequirement,
+  })).map((issue) => `publicContract: ${issue}`));
+  if (Object.hasOwn(contract ?? {}, "target")) issues.push("公开 contract 不得包含 target");
+  if (!/^sha256:[0-9a-f]{64}$/.test(contract?.verificationPolicyCommitment ?? "")) {
+    issues.push("contract.verificationPolicyCommitment 必须是有效 SHA-256 摘要");
+  }
+  if (
+    contract?.agent?.runtime !== null &&
+    contract?.agent?.runtime !== undefined &&
+    !new Set(["claude-code", "codex", "opencode"]).has(contract.agent.runtime)
+  ) {
+    issues.push("agent.runtime 必须是 claude-code、codex、opencode 或 null");
+  }
+  if (
+    contract?.agent?.reasoningMode !== undefined &&
+    !new Set(["standard", "pro"]).has(contract.agent.reasoningMode)
+  ) {
+    issues.push("agent.reasoningMode 必须是 standard 或 pro");
+  }
+  if (contract?.agent?.reasoningMode === "pro" && contract?.agent?.runtime === "claude-code") {
+    issues.push("agent.reasoningMode=pro 仅支持 Codex 和 OpenCode");
+  }
+  if (contract?.agent?.budgetCaps !== undefined) {
+    if (
+      !Number.isInteger(contract.agent.budgetCaps?.maxTurns)
+      || contract.agent.budgetCaps.maxTurns < 1
+    ) {
+      issues.push("agent.budgetCaps.maxTurns 必须是正整数");
+    }
+    if (!isFinitePositive(contract.agent.budgetCaps?.maxBudgetUsd)) {
+      issues.push("agent.budgetCaps.maxBudgetUsd 必须大于 0");
+    }
+    if (contract.agent.maxTurns > contract.agent.budgetCaps.maxTurns) {
+      issues.push("agent.maxTurns 不能超过 agent.budgetCaps.maxTurns");
+    }
+    if (contract.agent.maxBudgetUsd > contract.agent.budgetCaps.maxBudgetUsd) {
+      issues.push("agent.maxBudgetUsd 不能超过 agent.budgetCaps.maxBudgetUsd");
+    }
+  }
+  if (!isFinitePositive(contract?.environment?.timeoutMinutes)) issues.push("environment.timeoutMinutes 必须大于 0");
+  issues.push(...executionWorkloadIssues(contract?.protocol?.workload));
+  issues.push(...measurementHardwareIssues({ ...contract, compute: contract.computeRequirement }));
+  if (contract?.environment?.networkAccess !== true) issues.push("当前运行器要求 environment.networkAccess=true");
+  if (contract?.computeRequirement) {
+    issues.push(...validateDeclaredComputeRequirement(contract.computeRequirement, "computeRequirement"));
+    if (!new Set(["research-declared", "research-derived"]).has(contract.computeRequirement.source)) issues.push("computeRequirement.source 无效");
+    if (!new Set(["cpu-only", "gpu-optional", "gpu-required"]).has(contract.computeRequirement.classification)) issues.push("computeRequirement.classification 无效");
+  }
+  const body = { ...contract };
+  delete body.contractDigest;
+  const expected = `sha256:${sha256Value(body)}`;
+  if (contract?.contractDigest !== expected) issues.push("contractDigest 与内容不一致");
+  if (issues.length) throw new CiteArkError(`执行契约校验失败：\n- ${issues.join("\n- ")}`);
+  return contract;
+}
+
+function validateContractPreflight(value, issues) {
+  // Contracts from Research Plan records created before this gate remain valid.
+  if (value === undefined) return;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    issues.push("protocol.preflight 必须是对象");
+    return;
+  }
+  if (!supportsPreflightSchemaVersion(value.schemaVersion)) {
+    issues.push(`protocol.preflight.schemaVersion 必须是 ${describeSupportedPreflightSchemaVersions()}`);
+  }
+  if (!new Set(["declared", "defaulted"]).has(value.source)) issues.push("protocol.preflight.source 无效");
+  if (!Number.isFinite(value.maxMinutes) || value.maxMinutes < 1 || value.maxMinutes > MAX_PREFLIGHT_MINUTES) {
+    issues.push(`protocol.preflight.maxMinutes 必须在 1 到 ${MAX_PREFLIGHT_MINUTES} 之间`);
+  }
+  if (!safeRelativePath(value.evidencePath)) issues.push("protocol.preflight.evidencePath 必须是安全相对路径");
+  if (!Array.isArray(value.checks) || value.checks.length === 0) {
+    issues.push("protocol.preflight.checks 必须至少包含一项");
+  } else {
+    const ids = new Set();
+    for (const [index, check] of value.checks.entries()) {
+      if (!check || typeof check !== "object" || Array.isArray(check)) {
+        issues.push(`protocol.preflight.checks[${index}] 必须是对象`);
+        continue;
+      }
+      if (typeof check.id !== "string" || !check.id.trim()) issues.push(`protocol.preflight.checks[${index}].id 无效`);
+      if (ids.has(check.id)) issues.push(`protocol.preflight.checks[${index}].id 重复`);
+      ids.add(check.id);
+      if (!PREFLIGHT_CHECK_KINDS.has(check.kind)) issues.push(`protocol.preflight.checks[${index}].kind 无效`);
+      if (typeof check.successCriterion !== "string" || !check.successCriterion.trim()) {
+        issues.push(`protocol.preflight.checks[${index}].successCriterion 无效`);
+      }
+    }
+  }
+  if (!Array.isArray(value.assets)) {
+    issues.push("protocol.preflight.assets 必须是数组");
+  } else {
+    const ids = new Set();
+    for (const [index, asset] of value.assets.entries()) {
+      if (!asset || typeof asset !== "object" || Array.isArray(asset)) {
+        issues.push(`protocol.preflight.assets[${index}] 必须是对象`);
+        continue;
+      }
+      if (typeof asset.id !== "string" || !asset.id.trim()) issues.push(`protocol.preflight.assets[${index}].id 无效`);
+      if (ids.has(asset.id)) issues.push(`protocol.preflight.assets[${index}].id 重复`);
+      ids.add(asset.id);
+      if (asset.scientificRole !== undefined && !ASSET_SCIENTIFIC_ROLES.has(asset.scientificRole)) {
+        issues.push(`protocol.preflight.assets[${index}].scientificRole 无效`);
+      }
+      validateContractAssetAcquisition(asset.acquisition, index, issues);
+      validateContractAssetSourceEvidence(asset.sourceEvidence, index, issues);
+      const sourceUrls = asset.sourceUrls === undefined ? [] : asset.sourceUrls;
+      if (!Array.isArray(sourceUrls)) {
+        issues.push(`protocol.preflight.assets[${index}].sourceUrls 必须是数组`);
+      } else {
+        for (const [sourceIndex, sourceUrl] of sourceUrls.entries()) {
+          if (!validPublicAssetSourceUrl(sourceUrl)) {
+            issues.push(`protocol.preflight.assets[${index}].sourceUrls[${sourceIndex}] 必须是无凭据的 HTTP(S) URL`);
+          }
+        }
+      }
+      if (asset.registryDatasetId !== undefined && (typeof asset.registryDatasetId !== "string" || !asset.registryDatasetId.trim())) {
+        issues.push(`protocol.preflight.assets[${index}].registryDatasetId 无效`);
+      }
+      if (
+        asset.required === true
+        && asset.availability === "public_unverified"
+        && (!Array.isArray(sourceUrls) || sourceUrls.length === 0)
+        && !(typeof asset.registryDatasetId === "string" && asset.registryDatasetId.trim())
+      ) {
+        issues.push(`protocol.preflight.assets[${index}] 是必需的 public_unverified 资产，必须声明 sourceUrls 或 registryDatasetId`);
+      }
+    }
+    if (
+      value.assets.some((asset) =>
+        asset && typeof asset === "object" && asset.required === true && asset.availability === "public_unverified",
+      )
+      && value.maxMinutes < MIN_PUBLIC_ASSET_PREFLIGHT_MINUTES
+    ) {
+      issues.push(`protocol.preflight.maxMinutes 对必需的 public_unverified 资产不得低于 ${MIN_PUBLIC_ASSET_PREFLIGHT_MINUTES}`);
+    }
+  }
+}
+
+function validateContractAssetAcquisition(value, assetIndex, issues) {
+  if (value === undefined) return;
+  const label = `protocol.preflight.assets[${assetIndex}].acquisition`;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    issues.push(`${label} 必须是对象`);
+    return;
+  }
+  if (!ASSET_ACQUISITION_MODES.has(value.mode)) issues.push(`${label}.mode 无效`);
+  for (const field of ["requiredPaths", "excludedPaths"]) {
+    if (value[field] === undefined) continue;
+    if (!Array.isArray(value[field])) {
+      issues.push(`${label}.${field} 必须是数组`);
+      continue;
+    }
+    for (const [index, pattern] of value[field].entries()) {
+      if (!safeAssetPattern(pattern)) issues.push(`${label}.${field}[${index}] 不是安全相对路径或 glob`);
+    }
+  }
+  for (const field of ["expectedDownloadBytes", "expectedExpandedBytes"]) {
+    if (value[field] !== undefined && (!Number.isSafeInteger(value[field]) || value[field] < 0)) {
+      issues.push(`${label}.${field} 必须是非负安全整数`);
+    }
+  }
+  if (
+    value.maximumDownloadBytes !== undefined
+    && (!Number.isSafeInteger(value.maximumDownloadBytes) || value.maximumDownloadBytes < 1)
+  ) {
+    issues.push(`${label}.maximumDownloadBytes 必须是正安全整数`);
+  }
+  if (value.supportsStreaming !== undefined && typeof value.supportsStreaming !== "boolean") {
+    issues.push(`${label}.supportsStreaming 必须是布尔值`);
+  }
+}
+
+function validateContractAssetSourceEvidence(value, assetIndex, issues) {
+  if (value === undefined) return;
+  const label = `protocol.preflight.assets[${assetIndex}].sourceEvidence`;
+  if (!Array.isArray(value)) {
+    issues.push(`${label} 必须是数组`);
+    return;
+  }
+  for (const [index, entry] of value.entries()) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      issues.push(`${label}[${index}] 必须是对象`);
+      continue;
+    }
+    if (!new Set(["paper", "repository", "dataset_registry"]).has(entry.source)) {
+      issues.push(`${label}[${index}].source 无效`);
+    }
+    if (typeof entry.locator !== "string" || !entry.locator.trim()) {
+      issues.push(`${label}[${index}].locator 无效`);
+    }
+    if (entry.path !== undefined && !safeAssetPattern(entry.path)) {
+      issues.push(`${label}[${index}].path 无效`);
+    }
+  }
+}
+
+function safeAssetPattern(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  const normalized = value.replaceAll("\\", "/");
+  return !normalized.startsWith("/")
+    && !normalized.split("/").includes("..")
+    && !/[\u0000-\u001f]/.test(normalized);
+}
+
+function validPublicAssetSourceUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return false;
+  try {
+    const parsed = new URL(value);
+    return new Set(["http:", "https:"]).has(parsed.protocol)
+      && !parsed.username
+      && !parsed.password;
+  } catch {
+    return false;
+  }
+}
+
+export function executionContractMeasurements(contract) {
+  return Array.isArray(contract?.measurements) ? contract.measurements : [];
+}
+
+export function verificationPolicyTargets(policy) {
+  return Array.isArray(policy?.targets) ? policy.targets : [];
+}
+
+export function verificationPolicyCommitmentInput(policy) {
+  return {
+    claimVersionId: policy?.claimVersionId,
+    targets: verificationPolicyTargets(policy),
+  };
+}
+
+function resolveMeasurementBindings(research, claim, experiment) {
+  const reportedById = new Map(claim.reportedMeasurements.map((measurement) => [measurement.id, measurement]));
+  return experiment.measurements.flatMap((measurement) => {
+    const reported = reportedById.get(measurement.reportedMeasurementId);
+    return reported ? [{ measurementId: reported.id, reported, measurement }] : [];
+  });
+}
+
+function deduplicateMeasurementBindings(bindings) {
+  const output = [];
+  const seen = new Set();
+  for (const binding of bindings) {
+    if (seen.has(binding.measurementId)) continue;
+    seen.add(binding.measurementId);
+    output.push(binding);
+  }
+  return output;
+}
+
+/** The original inventory is retained in the research artifact. Execution gets
+ * source context and locators, without structured reported targets/tolerances.
+ * As with the original paper, source statements are not blinded observations.
+ */
+export function executionInventoryContext(inventory) {
+  const pick = (record, keys) => Object.fromEntries(keys.filter((key) => record?.[key] !== undefined)
+    .map((key) => [key, structuredClone(record[key])]));
+  return {
+    digest: inventory.digest, view: "source-context",
+    sources: structuredClone(inventory.research.sources),
+    ...(inventory.revisions?.length ? { revisions: inventory.revisions.map(({ claimId, reason, sources }) => ({ claimId, reason, sources })) } : {}),
+    claims: revisedInventoryClaims(inventory.research, inventory.revisions).map((claim) => ({
+      ...pick(claim, ["id", "type", "statement", "description", "sourceLocator", "sourceLocators", "conditions", "relations", "ambiguities", "verificationHint"]),
+      reportedMeasurements: claim.reportedMeasurements.map((measurement) => pick(measurement,
+        ["id", "metric", "unit", "sourceLocator", "dimensions", "conditions", "aggregation", "observationId"])),
+    })),
+  };
+}
+
+function blindMeasurementScope(reported, measurement) {
+  const protocolDimensions = measurement?.dimensions && typeof measurement.dimensions === "object"
+    && !Array.isArray(measurement.dimensions)
+    ? measurement.dimensions
+    : {};
+  const reportedDimensions = reported?.dimensions && typeof reported.dimensions === "object"
+    && !Array.isArray(reported.dimensions)
+    ? reported.dimensions
+    : {};
+  const dimensions = { ...protocolDimensions, ...reportedDimensions };
+  const aggregation = typeof reported?.aggregation === "string" && reported.aggregation.trim()
+    ? reported.aggregation.trim()
+    : typeof measurement?.aggregation === "string" && measurement.aggregation.trim()
+      ? measurement.aggregation.trim()
+      : null;
+  return {
+    ...(Object.keys(dimensions).length ? { dimensions } : {}),
+    ...(aggregation ? { aggregation } : {}),
+  };
+}
+
+function isFinitePositive(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}