@citeark/agent 0.3.20

package/src/compute/scheduler.mjs

@@ -0,0 +1,452 @@
+import { DEFAULT_COMPUTE_POLICY, validateComputeCatalog, validateComputePolicy } from "./catalog.mjs";
+import { resolveComputeRequirement } from "./requirements.mjs";
+import { CiteArkError, readJson, sha256Value, writeJson } from "../util.mjs";
+import { LEGACY_EXECUTION_TIMEOUT_FALLBACK_MINUTES } from "../contracts/execution-timeouts.mjs";
+import { measurementHardwareConstraint, measurementHardwareRejections } from "./measurement-hardware.mjs";
+
+export async function scheduleCompute({
+  experiment,
+  contract,
+  catalog,
+  policy = DEFAULT_COMPUTE_POLICY,
+  resourceLimits,
+  profileOverride,
+  selectionConstraints,
+  decidedAt = new Date().toISOString(),
+  outputPath,
+}) {
+  policy = { ...DEFAULT_COMPUTE_POLICY, ...policy };
+  // This mode comes from the host's per-job authorization, never research JSON.
+  if (resourceLimits?.maximumCost === null) policy.maxEstimatedComputeUsd = null;
+  validateComputeCatalog(catalog);
+  validateComputePolicy(policy);
+  const selection = normalizeSelectionConstraints(selectionConstraints, {
+    allowFallbackProfiles: Boolean(profileOverride),
+  });
+  selection.measurementHardware = measurementHardwareConstraint(contract ?? experiment);
+  if (contract?.research?.experimentVersionId && experiment?.versionId !== contract.research.experimentVersionId) {
+    throw new CiteArkError("计算调度的 experiment 与 execution contract 未绑定");
+  }
+  const requirement = contract?.computeRequirement ?? resolveComputeRequirement(experiment);
+  const contractEnvironment = contract?.environment ?? experiment?.environment ?? {};
+  const evaluatedProfiles = catalog.profiles
+    .map((profile) => evaluateProfile(
+      profile,
+      requirement,
+      policy,
+      contractEnvironment,
+      selection,
+    ));
+  const candidates = evaluatedProfiles.filter((candidate) => candidate.compatible);
+  const selected = profileOverride
+    ? candidates.find((candidate) => candidate.profile.id === profileOverride)
+    : [...candidates].sort(compareCandidates)[0];
+  if (!selected) {
+    const overrideMessage = profileOverride ? `指定的 profile ${profileOverride} 不可用或不兼容。` : "没有兼容的计算资源。";
+    const rejections = evaluatedProfiles.map((result) =>
+      `${result.profile.id}: ${result.reasons.join("；") || "未知原因"}`);
+    const error = new CiteArkError(`${overrideMessage}\n- ${rejections.join("\n- ")}`);
+    error.computeAvailability = publicComputeAvailability({
+      requirement,
+      policy,
+      evaluatedProfiles,
+    });
+    throw error;
+  }
+
+  const alternatives = evaluatedProfiles.map((evaluated) => {
+    const profile = evaluated.profile;
+    return {
+      profileId: profile.id,
+      profile: publicProfile(profile),
+      compatible: evaluated.compatible,
+      estimatedDurationMinutes: evaluated.estimatedDurationMinutes,
+      estimatedCostUsd: evaluated.estimatedCostUsd,
+      estimatedCostCny: evaluated.estimatedCostCny,
+      reasons: evaluated.reasons,
+      warnings: evaluated.warnings,
+    };
+  });
+  const body = {
+    schemaVersion: "0.1",
+    kind: "citeark.compute-decision",
+    experimentId: experiment?.id ?? contract?.research?.experimentId ?? null,
+    experimentVersionId: experiment?.versionId ?? contract?.research?.experimentVersionId ?? null,
+    contractDigest: contract?.contractDigest ?? null,
+    requirement,
+    measurementHardware: selection.measurementHardware,
+    selectedProfile: publicProfile(selected.profile),
+    environment: executionEnvironment(
+      selected.profile,
+      contractEnvironment,
+    ),
+    estimate: {
+      durationMinutes: selected.estimatedDurationMinutes,
+      costUsd: selected.estimatedCostUsd,
+      costCny: selected.estimatedCostCny,
+      pricingKnown: selected.estimatedCostUsd !== null || selected.estimatedCostCny !== null,
+      durationBasis: selected.estimatedDurationMinutes === null ? "unknown" : "research_estimate",
+    },
+    allocation: runtimeAllocation(selected.profile, contractEnvironment),
+    policy: {
+      allowCpuFallback: policy.allowCpuFallback ?? true,
+      maxEstimatedComputeUsd: policy.maxEstimatedComputeUsd ?? null,
+      maxNonResumableSpotDurationMinutes: policy.maxNonResumableSpotDurationMinutes ?? null,
+      manualProfileOverride: profileOverride ?? null,
+      requiredExecutor: selection.requiredExecutor,
+      requiredProvisioningModel: selection.requiredProvisioningModel,
+      allowFallbackProfiles: selection.allowFallbackProfiles,
+      selectionReason: selection.reason,
+    },
+    catalogDigest: `sha256:${sha256Value(catalog)}`,
+    policyDigest: `sha256:${sha256Value(policy)}`,
+    reasonCodes: selectionReasonCodes(selected, requirement, profileOverride, selection),
+    rationale: selectionRationale(selected, requirement, profileOverride, selection),
+    alternatives,
+    decidedAt,
+    scheduler: { name: "citeark-compute-scheduler", version: "0.2.0", strategy: "compatible-preemption-safety-then-estimated-total-cost" },
+  };
+  const decision = { ...body, decisionDigest: `sha256:${sha256Value(body)}` };
+  if (outputPath) await writeJson(outputPath, decision);
+  return decision;
+}
+
+function publicComputeAvailability({ requirement, policy, evaluatedProfiles }) {
+  const nearest = [...evaluatedProfiles].sort(compareRejectedProfiles)[0] ?? null;
+  return {
+    requirements: {
+      accelerator: requirement.accelerator,
+      cpuCores: requirement.cpuCores,
+      memoryGb: requirement.memoryGb,
+      gpuCount: requirement.gpuCount,
+      minVramGb: requirement.minVramGb,
+      preferredGpuTypes: uniquePublicStrings(requirement.preferredGpuTypes),
+    },
+    policy: {
+      maxEstimatedComputeUsd: finitePublicNumber(policy.maxEstimatedComputeUsd),
+      allowedGpuTypes: uniquePublicStrings(policy.allowedGpuTypes),
+      maximumGpuCount: finitePublicNumber(policy.maximumGpuCount),
+    },
+    nearestProfile: nearest ? {
+      label: nearest.profile.label ?? nearest.profile.id,
+      accelerator: nearest.profile.accelerator,
+      cpuCores: nearest.profile.cpuCores,
+      memoryGb: nearest.profile.memoryGb,
+      gpuType: nearest.profile.gpu?.type ?? null,
+      gpuCount: nearest.profile.gpu?.count ?? null,
+      vramGb: nearest.profile.gpu?.vramGb ?? null,
+      estimatedDurationMinutes: nearest.estimatedDurationMinutes,
+      estimatedCostUsd: nearest.estimatedCostUsd,
+      estimatedCostCny: nearest.estimatedCostCny,
+      blockerCodes: uniquePublicStrings(nearest.reasons.map(publicBlockerCode)),
+    } : null,
+  };
+}
+
+function compareRejectedProfiles(left, right) {
+  const score = (candidate) => candidate.reasons.reduce(
+    (total, reason) => total + blockerWeight(publicBlockerCode(reason)),
+    0,
+  );
+  const scoreDifference = score(left) - score(right);
+  return scoreDifference || compareCandidates(left, right);
+}
+
+function publicBlockerCode(reason) {
+  if (/超过预算/.test(reason)) return "budget_exceeded";
+  if (/资源当前不可用/.test(reason)) return "capacity_unavailable";
+  if (/资源规格不在策略白名单|显式供应商回退/.test(reason)) return "profile_not_allowed";
+  if (/执行器/.test(reason)) return "executor_not_allowed";
+  if (/供应模式/.test(reason)) return "provisioning_mismatch";
+  if (/CPU 不足/.test(reason)) return "cpu_insufficient";
+  if (/内存不足/.test(reason)) return "memory_insufficient";
+  if (/必须使用 GPU/.test(reason)) return "gpu_required";
+  if (/仅 CPU/.test(reason)) return "cpu_only";
+  if (/禁止 CPU 回退/.test(reason)) return "cpu_fallback_disabled";
+  if (/GPU 型号/.test(reason)) return "gpu_type_incompatible";
+  if (/GPU 数量/.test(reason)) return "gpu_count_incompatible";
+  if (/显存不足/.test(reason)) return "vram_insufficient";
+  if (/超过执行上限/.test(reason)) return "timeout_exceeded";
+  if (/科研测量要求|科研测量禁止|硬件/.test(reason)) return "hardware_incompatible";
+  return "other";
+}
+
+function blockerWeight(code) {
+  if (code === "budget_exceeded") return 1;
+  if (code === "capacity_unavailable") return 3;
+  if (code === "profile_not_allowed" || code === "executor_not_allowed"
+    || code === "provisioning_mismatch") return 5;
+  return 10;
+}
+
+function finitePublicNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function uniquePublicStrings(value) {
+  return [...new Set((Array.isArray(value) ? value : []).filter(
+    (item) => typeof item === "string" && item,
+  ))];
+}
+
+function runtimeAllocation(profile, environment) {
+  const minutes = executionEnvironment(profile, environment).timeoutMinutes;
+  const cost = (rate) => Number.isFinite(rate) && rate >= 0
+    ? Math.round(rate * minutes / 60 * 1e6) / 1e6 : null;
+  return {
+    basis: "configured_execution_timeout",
+    durationMinutes: minutes,
+    computeCostUsd: cost(profile.hourlyUsd),
+    computeCostCny: cost(profile.hourlyCny),
+    scope: "One execution window at catalog compute rates; excludes startup, retries, models, storage and coordinator costs. Not a completion-time estimate or an invoice ceiling.",
+  };
+}
+
+export async function loadComputeDecision(target, contract) {
+  const decision = await readJson(target);
+  validateComputeDecision(decision, contract);
+  return decision;
+}
+
+export function validateComputeDecision(decision, contract) {
+  const issues = [];
+  if (decision?.schemaVersion !== "0.1") issues.push("decision.schemaVersion 必须是 0.1");
+  if (decision?.kind !== "citeark.compute-decision") issues.push("decision.kind 无效");
+  if (typeof decision?.selectedProfile?.id !== "string" || !decision.selectedProfile.id) issues.push("selectedProfile.id 必须是非空字符串");
+  if (typeof decision?.selectedProfile?.executor !== "string" || !decision.selectedProfile.executor) issues.push("selectedProfile.executor 必须是非空字符串");
+  if (!decision?.environment || typeof decision.environment !== "object") issues.push("environment 必须是对象");
+  else {
+    if (typeof decision.environment.image !== "string" || !decision.environment.image) issues.push("environment.image 必须是非空字符串");
+    for (const field of ["timeoutMinutes", "cpus", "memoryGb", "shmGb"]) {
+      if (typeof decision.environment[field] !== "number" || !Number.isFinite(decision.environment[field]) || decision.environment[field] <= 0) issues.push(`environment.${field} 必须大于 0`);
+    }
+    if (!new Set(["none", "all"]).has(decision.environment.gpu)) issues.push("environment.gpu 必须是 none 或 all");
+    if (decision.environment.networkAccess !== true) issues.push("当前运行器要求 environment.networkAccess=true");
+  }
+  if (decision?.selectedProfile?.accelerator === "gpu" && decision?.environment?.gpu !== "all") issues.push("GPU profile 与执行环境不一致");
+  if (decision?.selectedProfile?.accelerator === "cpu" && decision?.environment?.gpu !== "none") issues.push("CPU profile 与执行环境不一致");
+  if (contract?.contractDigest && decision?.contractDigest && decision.contractDigest !== contract.contractDigest) issues.push("compute decision 与 execution contract 未绑定");
+  if (contract?.research?.experimentVersionId && decision?.experimentVersionId && decision.experimentVersionId !== contract.research.experimentVersionId) issues.push("compute decision 与 experiment version 未绑定");
+  if (contract?.computeRequirement) {
+    if (decision?.environment?.cpus < contract.computeRequirement.cpuCores) issues.push("compute decision 的 CPU 低于契约需求");
+    if (decision?.environment?.memoryGb < contract.computeRequirement.memoryGb) issues.push("compute decision 的内存低于契约需求");
+    if (contract.computeRequirement.accelerator === "required" && decision?.environment?.gpu !== "all") issues.push("compute decision 没有满足契约的 GPU 必需条件");
+  }
+  if (
+    typeof contract?.environment?.timeoutMinutes === "number"
+    && decision?.environment?.timeoutMinutes > contract.environment.timeoutMinutes
+  ) {
+    issues.push("compute decision 的超时上限不能超过执行契约");
+  }
+  const body = { ...decision };
+  delete body.decisionDigest;
+  if (decision?.decisionDigest !== `sha256:${sha256Value(body)}`) issues.push("decisionDigest 与内容不一致");
+  if (issues.length) throw new CiteArkError(`计算决策校验失败：\n- ${issues.join("\n- ")}`);
+  return decision;
+}
+
+function evaluateProfile(profile, requirement, policy, contractEnvironment, selection) {
+  const reasons = measurementHardwareRejections(profile, selection.measurementHardware);
+  const warnings = [];
+  if (profile.available === false) reasons.push("资源当前不可用");
+  if (profile.executorConfig?.fallbackOnly === true && selection.allowFallbackProfiles !== true) {
+    reasons.push("资源仅用于显式供应商回退");
+  }
+  if (selection.requiredExecutor && profile.executor !== selection.requiredExecutor) {
+    reasons.push(`执行器不符合本次约束（需要 ${selection.requiredExecutor}）`);
+  }
+  if (
+    selection.requiredProvisioningModel
+    && profile.executorConfig?.provisioningModel !== selection.requiredProvisioningModel
+  ) {
+    reasons.push(`供应模式不符合本次约束（需要 ${selection.requiredProvisioningModel}）`);
+  }
+  if (policy.allowedExecutors && !policy.allowedExecutors.includes(profile.executor)) reasons.push("执行器不在策略白名单");
+  if (policy.allowedProfileIds && !policy.allowedProfileIds.includes(profile.id)) reasons.push("资源规格不在策略白名单");
+  if (profile.cpuCores < requirement.cpuCores) reasons.push(`CPU 不足（需要 ${requirement.cpuCores}）`);
+  if (profile.memoryGb < requirement.memoryGb) reasons.push(`内存不足（需要 ${requirement.memoryGb} GB）`);
+  if (
+    requirement.accelerator === "none"
+    && profile.accelerator !== "cpu"
+    && profile.executorConfig?.allowCpuWorkloads !== true
+  ) reasons.push("任务分类为仅 CPU，不占用 GPU 资源");
+  if (requirement.accelerator === "required" && profile.accelerator !== "gpu") reasons.push("实验必须使用 GPU");
+  if (profile.accelerator === "cpu" && requirement.accelerator === "optional" && (!requirement.cpuFallbackAllowed || policy.allowCpuFallback === false)) {
+    reasons.push("策略禁止 CPU 回退");
+  }
+  if (profile.accelerator === "gpu") {
+    if (policy.allowedGpuTypes && !policy.allowedGpuTypes.includes(profile.gpu?.type)) reasons.push("GPU 型号超出论文算力范围");
+    if (policy.maximumGpuCount && profile.gpu?.count > policy.maximumGpuCount) reasons.push("GPU 数量超出论文算力范围");
+    if ((profile.gpu?.count ?? 0) < requirement.gpuCount) reasons.push(`GPU 数量不足（需要 ${requirement.gpuCount}）`);
+    if (requirement.minVramGb && (profile.gpu?.vramGb ?? 0) < requirement.minVramGb) reasons.push(`显存不足（需要 ${requirement.minVramGb} GB）`);
+  }
+  const duration = profile.accelerator === "gpu"
+    ? requirement.estimatedDurationMinutes.gpu
+    : requirement.estimatedDurationMinutes.cpu;
+  const timeoutMinutes = executionTimeoutMinutes(profile, contractEnvironment);
+  if (duration !== null && duration > timeoutMinutes) {
+    reasons.push(`预计运行 ${duration} 分钟超过执行上限 ${timeoutMinutes} 分钟`);
+  }
+  const estimatedCostUsd = duration !== null && profile.hourlyUsd !== null && profile.hourlyUsd !== undefined
+    ? roundMoney((duration / 60) * profile.hourlyUsd)
+    : profile.hourlyUsd === 0 ? 0 : null;
+  const hourlyCny = profile.hourlyCny
+    ?? profile.executorConfig?.maxHourlyCny
+    ?? null;
+  const estimatedCostCny = duration !== null && typeof hourlyCny === "number"
+    ? roundMoney((duration / 60) * hourlyCny)
+    : hourlyCny === 0 ? 0 : null;
+  if (policy.maxEstimatedComputeUsd !== null && policy.maxEstimatedComputeUsd !== undefined && estimatedCostUsd !== null && estimatedCostUsd > policy.maxEstimatedComputeUsd) {
+    reasons.push(`预计费用 ${estimatedCostUsd} USD 超过预算`);
+  }
+  const unsafeSpot = profile.executorConfig?.provisioningModel === "SPOT"
+    && requirement.preemptionSafe !== true
+    && duration !== null
+    && policy.maxNonResumableSpotDurationMinutes !== null
+    && policy.maxNonResumableSpotDurationMinutes !== undefined
+    && duration > policy.maxNonResumableSpotDurationMinutes;
+  if (unsafeSpot) {
+    warnings.push(`预计运行 ${duration} 分钟，且科研计算未声明可从持久化检查点续算；优先使用非 Spot 资源`);
+  }
+  return {
+    profile,
+    compatible: reasons.length === 0,
+    reasons,
+    warnings,
+    unsafeSpot,
+    estimatedDurationMinutes: duration,
+    estimatedCostUsd,
+    estimatedCostCny,
+    preferredGpuType: profile.accelerator === "gpu" && requirement.preferredGpuTypes.includes(profile.gpu?.type),
+  };
+}
+
+function compareCandidates(left, right) {
+  if (left.unsafeSpot !== right.unsafeSpot) return left.unsafeSpot ? 1 : -1;
+  const leftCost = left.estimatedCostUsd;
+  const rightCost = right.estimatedCostUsd;
+  if (leftCost !== null && rightCost !== null && leftCost !== rightCost) return leftCost - rightCost;
+  if (leftCost !== null && rightCost === null) return -1;
+  if (leftCost === null && rightCost !== null) return 1;
+  const leftCny = left.estimatedCostCny;
+  const rightCny = right.estimatedCostCny;
+  if (leftCny !== null && rightCny !== null && leftCny !== rightCny) return leftCny - rightCny;
+  if (leftCny !== null && rightCny === null) return -1;
+  if (leftCny === null && rightCny !== null) return 1;
+  if (left.preferredGpuType !== right.preferredGpuType) return left.preferredGpuType ? -1 : 1;
+  if (left.profile.accelerator !== right.profile.accelerator) return left.profile.accelerator === "cpu" ? -1 : 1;
+  if (
+    left.profile.accelerator === "gpu"
+    && right.profile.accelerator === "gpu"
+    && left.profile.gpu?.vramGb !== right.profile.gpu?.vramGb
+  ) {
+    return (left.profile.gpu?.vramGb ?? Number.POSITIVE_INFINITY)
+      - (right.profile.gpu?.vramGb ?? Number.POSITIVE_INFINITY);
+  }
+  const leftHourly = left.profile.hourlyUsd ?? Number.POSITIVE_INFINITY;
+  const rightHourly = right.profile.hourlyUsd ?? Number.POSITIVE_INFINITY;
+  if (leftHourly !== rightHourly) return leftHourly - rightHourly;
+  return left.profile.id.localeCompare(right.profile.id);
+}
+
+function executionEnvironment(profile, fallback = {}) {
+  return {
+    image: profile.image ?? fallback.image ?? "citeark-agent/runtime:0.2.0",
+    timeoutMinutes: executionTimeoutMinutes(profile, fallback),
+    cpus: profile.cpuCores,
+    memoryGb: profile.memoryGb,
+    shmGb: profile.shmGb ?? fallback.shmGb ?? Math.min(8, profile.memoryGb),
+    gpu: profile.accelerator === "gpu" ? "all" : "none",
+    networkAccess: fallback.networkAccess ?? true,
+  };
+}
+
+function executionTimeoutMinutes(profile, fallback = {}) {
+  const profileTimeout = profile.timeoutMinutes
+    ?? fallback.timeoutMinutes
+    ?? LEGACY_EXECUTION_TIMEOUT_FALLBACK_MINUTES;
+  const contractTimeout = fallback.timeoutMinutes ?? profileTimeout;
+  return Math.min(profileTimeout, contractTimeout);
+}
+
+function publicProfile(profile) {
+  return {
+    id: profile.id,
+    label: profile.label ?? profile.id,
+    executor: profile.executor,
+    accelerator: profile.accelerator,
+    cpuCores: profile.cpuCores,
+    memoryGb: profile.memoryGb,
+    gpu: profile.gpu ?? null,
+    hourlyUsd: profile.hourlyUsd ?? null,
+    hourlyCny: profile.hourlyCny ?? null,
+    executorConfig: profile.executorConfig ? structuredClone(profile.executorConfig) : null,
+  };
+}
+
+function selectionReasonCodes(selected, requirement, profileOverride, selection) {
+  const codes = [profileOverride ? "manual-profile-override" : "compatible-preemption-safety-then-cost"];
+  if (selection.reason) codes.push(selection.reason);
+  if (selection.requiredExecutor) codes.push(`executor-${selection.requiredExecutor}`);
+  if (selection.requiredProvisioningModel) {
+    codes.push(`provisioning-${selection.requiredProvisioningModel.toLowerCase()}`);
+  }
+  codes.push(requirement.classification);
+  codes.push(selected.profile.accelerator === "gpu" ? "gpu-selected" : "cpu-selected");
+  if (selected.estimatedCostUsd === null && selected.estimatedCostCny === null) {
+    codes.push("pricing-incomplete");
+  }
+  if (selected.unsafeSpot) codes.push("preemption-risk-unavoidable");
+  else if (selected.profile.executorConfig?.provisioningModel !== "SPOT") codes.push("non-preemptible-profile-selected");
+  return codes;
+}
+
+function selectionRationale(selected, requirement, profileOverride, selection) {
+  const selectionPrefix = selection.requiredExecutor || selection.requiredProvisioningModel
+    ? `Applied runtime fallback constraints${selection.requiredExecutor ? ` executor=${selection.requiredExecutor}` : ""}${selection.requiredProvisioningModel ? ` provisioningModel=${selection.requiredProvisioningModel}` : ""}${selection.reason ? ` after ${selection.reason}` : ""}. `
+    : "";
+  const prefix = selectionPrefix + (profileOverride
+    ? `Profile ${selected.profile.id} was specified via entry parameters. `
+    : `Selected ${selected.profile.id} after applying ${requirement.classification}, CPU, and memory compatibility, preferring non-preemptible profiles over unsafe long-running Spot profiles, then estimated total cost. `);
+  const estimate = selected.estimatedCostUsd !== null
+    ? `Estimated compute cost is ${selected.estimatedCostUsd} USD.`
+    : selected.estimatedCostCny !== null
+      ? `Estimated compute cost is at most ${selected.estimatedCostCny} CNY using the profile price cap.`
+      : "The catalog lacks sufficient duration or pricing data, so the cost is marked unknown.";
+  const resilience = selected.unsafeSpot
+    ? " No compatible non-Spot profile was selected even though the estimated duration exceeds the non-resumable Spot threshold; interruption may require restarting scientific computation."
+    : selected.profile.executorConfig?.provisioningModel !== "SPOT"
+      ? " The selected profile avoids Spot preemption risk."
+      : "";
+  return `${prefix}${estimate}${resilience}`;
+}
+
+function normalizeSelectionConstraints(value, defaults = {}) {
+  if (value !== undefined && value !== null && (typeof value !== "object" || Array.isArray(value))) {
+    throw new CiteArkError("计算选择约束必须是对象");
+  }
+  const source = value ?? {};
+  const requiredExecutor = typeof source.requiredExecutor === "string" && source.requiredExecutor.trim()
+    ? source.requiredExecutor.trim()
+    : null;
+  const rawProvisioningModel = typeof source.requiredProvisioningModel === "string"
+    ? source.requiredProvisioningModel.trim().toUpperCase()
+    : "";
+  if (rawProvisioningModel && !new Set(["STANDARD", "SPOT", "FLEX_START"]).has(rawProvisioningModel)) {
+    throw new CiteArkError("计算选择约束的 requiredProvisioningModel 无效");
+  }
+  const reason = typeof source.reason === "string" && source.reason.trim()
+    ? source.reason.trim()
+    : null;
+  return {
+    requiredExecutor,
+    requiredProvisioningModel: rawProvisioningModel || null,
+    allowFallbackProfiles: source.allowFallbackProfiles === true
+      || defaults.allowFallbackProfiles === true,
+    reason,
+  };
+}
+
+function roundMoney(value) {
+  return Number(value.toFixed(6));
+}

package/src/compute/shared-workloads.mjs

@@ -0,0 +1,26 @@
+import { CiteArkError, sha256Value } from "../util.mjs";
+
+// Work identity is scientific, not an experiment/claim id. Keep consumers so
+// the same union drives the quote and the Agent's checkpoint reuse plan.
+export function sharedWorkloads(experiments) {
+  const work = new Map();
+  for (const experiment of experiments) for (const item of experiment.compute?.workloads ?? []) {
+    const previous = work.get(item.id);
+    if (previous && sha256Value(previous.item) !== sha256Value(item)) {
+      throw new CiteArkError(`共享计算 ${item.id} 的定义不一致，不能合并估价`);
+    }
+    if (!previous) work.set(item.id, { item, experimentIds: new Set() });
+    work.get(item.id).experimentIds.add(experiment.id);
+  }
+  return [...work.values()].map(({ item, experimentIds }) => ({
+    ...item, experimentIds: [...experimentIds].sort(),
+  }));
+}
+
+export function workloadMinutes(item, accelerator) {
+  const durations = item.estimatedDurationMinutes ?? {};
+  // CPU-only work runs on the CPU of the shared GPU machine, at that machine's
+  // rate. An explicitly unknown GPU rate must stay unknown.
+  return accelerator === "gpu" && !Object.hasOwn(durations, "gpu")
+    ? durations.cpu : durations[accelerator];
+}

package/src/compute/stage-archive.mjs

@@ -0,0 +1,79 @@
+import { captureProcess } from "../process.mjs";
+import { copyFile, mkdir, writeFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { CiteArkError } from "../util.mjs";
+
+export const REMOTE_STAGE_DIRECTORIES = Object.freeze([
+  "input",
+  "workspace",
+  "output",
+  "runtime-home",
+  "execution",
+]);
+
+// These paths are reproducible caches or repository metadata, not scientific
+// inputs. Keeping them out of every remote stage makes transfer cost depend on
+// the fixed source snapshot instead of local package-manager and Agent caches.
+export const REMOTE_STAGE_EXCLUDES = Object.freeze([
+  "runtime-home/codex/auth.json",
+  "runtime-home/.cache",
+  "runtime-home/.npm",
+  "runtime-home/.local/share/uv",
+  "runtime-home/.local/share/pnpm",
+  "runtime-home/.bun/install/cache",
+  "runtime-home/.config/opencode/node_modules",
+  "runtime-home/.local/share/opencode/log",
+  "runtime-home/.local/share/opencode/snapshot",
+  "runtime-home/.local/share/opencode/repos",
+  "workspace/repository/.git",
+  "workspace/repository/*/.git",
+  "workspace/repository/.cache",
+  "workspace/repository/*/.cache",
+  "workspace/repository/.mypy_cache",
+  "workspace/repository/*/.mypy_cache",
+  "workspace/repository/.pytest_cache",
+  "workspace/repository/*/.pytest_cache",
+  "workspace/repository/.venv",
+  "workspace/repository/*/.venv",
+  "workspace/repository/__pycache__",
+  "workspace/repository/*/__pycache__",
+  "workspace/repository/node_modules",
+  "workspace/repository/*/node_modules",
+  "workspace/repository/.env",
+  "workspace/repository/.env.*",
+  "workspace/repository/*/.env",
+  "workspace/repository/*/.env.*",
+]);
+
+export async function createRemoteStageArchive({
+  runDirectory,
+  destination,
+  label = "远程",
+  capture = captureProcess,
+  paperBudget,
+}) {
+  await mkdir(path.join(runDirectory, "input"), { recursive: true });
+  await copyFile(new URL("../../docker/claude-code/codex-pro-relay.mjs", import.meta.url),
+    path.join(runDirectory, "input/runner-provider-relay.mjs"));
+  await copyFile(new URL("./codex-account-session.mjs", import.meta.url), path.join(runDirectory, "input/runner-codex-account.mjs"));
+  await copyFile(new URL("../runtime/codex-capacity-retry.mjs", import.meta.url), path.join(runDirectory, "input/runner-codex-capacity-retry.mjs"));
+  const budgetPath = path.join(runDirectory, "input/runner-paper-budget.json");
+  if (paperBudget) await writeFile(budgetPath, JSON.stringify(paperBudget), { mode: 0o600 });
+  for (const relative of ["scripts/check-execution-feasibility.mjs", "src/contracts/execution-workload.mjs"]) {
+    const target = path.join(runDirectory, "input/runtime-tools", relative);
+    await mkdir(path.dirname(target), { recursive: true });
+    await copyFile(new URL(`../../${relative}`, import.meta.url), target);
+  }
+  let result;
+  try { result = await capture("tar", [
+    "-czf",
+    destination,
+    ...REMOTE_STAGE_EXCLUDES.map((pattern) => `--exclude=${pattern}`),
+    "-C",
+    runDirectory,
+    ...REMOTE_STAGE_DIRECTORIES,
+  ]); } finally { await rm(budgetPath, { force: true }); }
+  if (result.code !== 0) {
+    throw new CiteArkError(`创建 ${label} 暂存包失败：\n${result.stderr.trim()}`);
+  }
+}

package/src/contracts/campaign-contract.mjs

@@ -0,0 +1,52 @@
+import { mergeExecutionGraphContexts } from '../research/execution-graph-context.mjs';
+import path from "node:path";
+import { createExecutionContract, validateExecutionContract } from "./execution-contract.mjs";
+import { reproductionCampaign } from "../compute/campaign.mjs";
+import { resolveComputeRequirement } from "../compute/requirements.mjs";
+import { sharedWorkloads } from "../compute/shared-workloads.mjs";
+import { sha256Value, writeJson } from "../util.mjs";
+
+export function campaignTargetKey(target) { return `${target.experimentId}:${target.claimId}`; }
+export function campaignTargetDirectory(directory, target) {
+  return path.join(directory, "campaign-targets", sha256Value(campaignTargetKey(target)).slice(0, 24));
+}
+
+/** All individual policy commitments are created before the shared Agent starts. */
+export async function createCampaignContract({ research, researchPath, targets, directory, outputPath, tolerance }) {
+  const campaign = reproductionCampaign(research, targets);
+  const members = [];
+  for (const target of campaign.targets) {
+    const targetDirectory = campaignTargetDirectory(directory, target);
+    const { contract } = await createExecutionContract({ researchPath, claimId: target.claimId,
+      experimentId: target.experimentId, restrictToAssignedMeasurements: true, tolerance,
+      outputPath: path.join(targetDirectory, "contract.json"), policyPath: path.join(targetDirectory, "policy.json") });
+    const measurementMap = Object.fromEntries(contract.measurements.map(m =>
+      [m.measurementId, `${target.experimentId}::${m.measurementId}`]));
+    members.push({ target, contract, measurementMap });
+  }
+  const primary = members[0].contract;
+  const measurements = [...new Map(members.flatMap(member => member.contract.measurements.map(m => {
+    const measurement = { ...m, measurementId: member.measurementMap[m.measurementId] };
+    return [measurement.measurementId, measurement];
+  }))).values()];
+  const { contractDigest: ignored, ...body } = primary;
+  const researchGraph = mergeExecutionGraphContexts(members.map(member => member.contract));
+  const contractBody = { ...body, name: campaign.id,
+    ...(researchGraph ? { researchGraph } : {}),
+    research: { ...primary.research, measurementIds: measurements.map(m => m.measurementId),
+      claimMeasurementIds: measurements.map(m => m.measurementId), uncoveredMeasurementIds: [], claimCoverage: "complete",
+      ...(campaign.claimIds.length > 1 ? { executionClaimIds: campaign.claimIds } : {}) },
+    protocol: campaign.experiment.protocol, computeRequirement: resolveComputeRequirement(campaign.experiment),
+    environment: { ...primary.environment, timeoutMinutes: campaign.timeoutMinutes,
+      cpus: campaign.experiment.compute.cpuCores, memoryGb: campaign.experiment.compute.memoryGb,
+      gpu: campaign.experiment.compute.accelerator === "none" ? "none" : "all" },
+    measurements,
+    workspacePlan: { ...primary.workspacePlan, version: 2,
+      measurements: measurements.map(({ parser, ...m }) => m) },
+    campaign: { version: 1, id: campaign.id, members, workloads: sharedWorkloads(campaign.experiments) },
+  };
+  const contract = { ...contractBody, contractDigest: `sha256:${sha256Value(contractBody)}` };
+  validateExecutionContract(contract);
+  await writeJson(outputPath, contract);
+  return { contract, campaign };
+}