@citeark/agent 0.3.20

package/src/research/compiler.mjs

@@ -0,0 +1,853 @@
+import { saveRunRecovery, restoreRunRecovery } from '../compute/coordinator-recovery.mjs';
+import { stageReferenceMaterials } from "../research/reference-materials.mjs";
+import { mergeInventoryPreparation } from "./inventory-handoff.mjs";
+import { continuationRepairTargets } from "./continuation-selection.mjs";
+import { preparePaperMarkdown } from "./paper-markdown.mjs";
+import { createHash } from "node:crypto";
+import { cp, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+
+import {
+  captureFinalWorkspace,
+  copyPaper,
+  prepareRepository,
+  snapshotDigest,
+  snapshotDirectory,
+  updateRunState,
+} from "../job.mjs";
+import { previewEgressProxy, startEgressProxy } from "../network/egress-proxy.mjs";
+import { previewProviderSession, startProviderSession } from "../provider/relay.mjs";
+import { resolveAgentRuntime, publicAgentRuntime } from "../runtime/config.mjs";
+import { buildAgentInvocation } from "../runtime/index.mjs";
+import { assertLocalRunStopped, buildDockerRun, inspectDockerImage, requireRuntimeCredentials, runDockerInvocation, writeInvocation } from "../sandbox/docker.mjs";
+import { readAgentUsage } from "../telemetry/usage.mjs";
+import { CiteArkError, createRunId, createSessionId, isRecord, pathExists, readJson, sha256File, sha256Value, writeJson } from "../util.mjs";
+import { listEvidenceParsers } from "../evidence/registry.mjs";
+import { assetSourceGroundingIssues } from "../assets/source-grounding.mjs";
+import { RECONSTRUCTION_REPOSITORY } from "../repository-origin.mjs";
+import {
+  blockingCompilerReconstructionIssues,
+  compilerReconstructionRetryIssues,
+  normalizeCompilerResearchDraft,
+  normalizeResearchStructure,
+} from "./structure.mjs";
+import { reviewCompilerCoverage } from "./compiler-coverage.mjs";
+import { reviewCompilerSources } from "./source-review.mjs";
+import { scientificPlanningPolicy } from "./planning-policy.mjs";
+import { sharedWorkloads, workloadMinutes } from "../compute/shared-workloads.mjs";
+import { researchCompilationFailure } from "./compiler-failure.mjs";
+
+const SOURCE_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(SOURCE_ROOT, "../..");
+
+export async function runResearchCompiler({ taskPath, runsDirectory, runId = createRunId(), dryRun = false, imageOverride, agentRuntime, sourceReviewer = reviewCompilerSources, validateResearch = async () => [] }) {
+  const absoluteTaskPath = path.resolve(taskPath);
+  const taskDirectory = path.dirname(absoluteTaskPath);
+  const task = normalizeCompilationTask(await readJson(absoluteTaskPath));
+  const runtimeAgent = resolveAgentRuntime({
+    taskAgent: task.agent,
+    ...agentRuntime,
+    requireApi: !dryRun,
+  });
+  if (imageOverride) task.environment.image = imageOverride;
+  const bundle = await restoreRunRecovery({ runsDirectory, runId }) ?? await prepareCompilationBundle({ task, taskDirectory, runsDirectory, runId });
+  if (sha256Value(bundle.task) !== sha256Value(task)) throw Error('The saved research input changed. Start a new workspace.');
+  bundle.runtimeAgent = runtimeAgent;
+  await updateRunState(bundle, {
+    runtime: runtimeAgent.runtime,
+    agent: publicAgentRuntime(runtimeAgent),
+  });
+  const invocations = [];
+  const promptsDirectory = path.join(bundle.directories.execution, "prompts");
+  await mkdir(promptsDirectory, { recursive: true });
+  let validationIssues = ["research.json 尚未生成"];
+  let blockingFailure = null;
+  let normalizedResearch = null;
+  let normalizationWarnings = [];
+  const maxAttempts = 1 + runtimeAgent.validationRetries;
+  const firstAttempt = bundle.restored && bundle.state.status !== "prepared" ? Math.max(1, ...bundle.attempts.map(a => a.attempt)) + 1 : 1;
+  if (!dryRun) { await assertLocalRunStopped(bundle); requireRuntimeCredentials(runtimeAgent); }
+  const providerSession = dryRun
+    ? previewProviderSession(runtimeAgent)
+    : await startProviderSession(runtimeAgent, {
+        correlation: { runId: bundle.runId, workload: "research_compilation" },
+      });
+  let egressSession = previewEgressProxy();
+
+  try {
+  if (!dryRun) egressSession = await startEgressProxy();
+  const instructions = await readFileText(
+    path.join(bundle.directories.input, "agent-instructions.md"),
+  );
+  const retainedDraft = path.join(bundle.directories.output, 'research.json');
+  if (bundle.restored && !dryRun && await pathExists(retainedDraft)) {
+    try {
+      const accepted = await acceptCompilerDraft({ bundle, draft: await readJson(retainedDraft), validateResearch, sourceReviewer });
+      normalizedResearch = accepted.research; normalizationWarnings = accepted.normalizationWarnings; validationIssues = [];
+    } catch (error) {
+      if (error.failureCode === 'compiler.source_review_unavailable') throw error;
+      validationIssues = [error.message];
+    }
+  }
+  for (let attempt = firstAttempt; !normalizedResearch && attempt < firstAttempt + maxAttempts; attempt += 1) {
+    const runtime = await buildAgentInvocation({
+      bundle,
+      attempt,
+      prompt: compilerPrompt(attempt, validationIssues, {
+        continuation: bundle.runtimeTask?.continuation,
+        repairBaseline: bundle.repairBaselineResearch,
+      }),
+      instructions,
+      providerSession,
+    });
+    const docker = {
+      ...buildDockerRun({
+        bundle,
+        runtimeCommand: runtime.command,
+        runtimeArgs: runtime.args,
+        attempt,
+        providerSession,
+        egressSession,
+      }),
+      attempt,
+    };
+    invocations.push(docker);
+    await writeInvocation(bundle, invocations);
+    await writeFile(path.join(promptsDirectory, `attempt-${attempt}.txt`), `${runtime.prompt}\n`, "utf8");
+    if (dryRun) {
+      await updateRunState(bundle, { status: "prepared" });
+      return { bundle, invocation: docker, dryRun: true };
+    }
+    if (attempt === firstAttempt) {
+      await updateRunState(bundle, { status: "running", startedAt: new Date().toISOString() });
+    }
+    const processResult = await runDockerInvocation(docker, {
+      bundle,
+      attempt,
+      timeoutMs: task.environment.timeoutMinutes * 60_000,
+    });
+    bundle.attempts.push({
+      attempt,
+      startedAt: bundle.state.startedAt,
+      finishedAt: new Date().toISOString(),
+      exitCode: processResult.code,
+      signal: processResult.signal,
+      timedOut: processResult.timedOut,
+    });
+    const researchPath = path.join(bundle.directories.output, "research.json");
+    try {
+      if (processResult.code !== 0 || processResult.timedOut) throw new CiteArkError("Compiler process did not finish successfully; retained JSON is a draft");
+      if (!(await pathExists(researchPath))) throw new CiteArkError("缺少 /job/output/research.json");
+      const accepted = await acceptCompilerDraft({ bundle, draft: await readJson(researchPath), validateResearch, sourceReviewer });
+      normalizationWarnings = accepted.normalizationWarnings;
+      normalizedResearch = accepted.research;
+      validationIssues = [];
+      break;
+    } catch (error) {
+      validationIssues = [error.message];
+      if (error.failureCode === "compiler.source_review_unavailable") { blockingFailure = { code: error.failureCode, retryable: false }; break; }
+    }
+  }
+
+  bundle.sandboxImageIdentity = await inspectDockerImage(task.environment.image);
+  await captureFinalWorkspace(bundle);
+  const usage = await readAgentUsage(path.join(bundle.directories.execution, "trace.jsonl"), {
+    runtimeHome: bundle.directories.runtimeHome,
+    model: bundle.runtimeAgent.model,
+  });
+  const status = validationIssues.length ? "invalid_result" : "completed";
+  await updateRunState(bundle, {
+    status,
+    finishedAt: new Date().toISOString(),
+    attempts: bundle.attempts,
+    validationIssues,
+    normalizationWarnings,
+    output: normalizedResearch ? "output/research.normalized.json" : null,
+    sandboxImageIdentity: bundle.sandboxImageIdentity,
+    usage,
+  });
+  if (validationIssues.length) throw researchCompilationFailure(validationIssues, blockingFailure);
+  return {
+    bundle,
+    research: normalizedResearch,
+    normalizationWarnings,
+    dryRun: false,
+  };
+  } finally {
+    await saveRunRecovery(bundle, async () => {});
+    await Promise.all([providerSession.close(), egressSession.close()]);
+  }
+}
+
+/**
+ * Inventory acceptance checks source coverage and structure only. Reproduction
+ * preparation applies scheduling and complete execution dispositions later;
+ * runtime still owns concrete commands, assets and evidence. Legacy fixed
+ * entrypoints retain their operational gate.
+ */
+export async function reviewCompilerCandidate({
+  candidate,
+  draftContext,
+  reconstructionIssues = [],
+  structureIssues = [],
+  validateResearch = async () => [],
+  datasetRegistry,
+  previousCoverageInventory = [],
+}) {
+  const coverage = reviewCompilerCoverage(candidate, draftContext, previousCoverageInventory);
+  const experiments = Array.isArray(candidate?.experiments) ? candidate.experiments : [];
+  const agentPlanned = experiments.every((experiment) =>
+    experiment?.protocol?.executionMode === "agent_planned",
+  );
+  const reconstructionBlocking = blockingCompilerReconstructionIssues(
+    reconstructionIssues,
+    { agentPlanned },
+  );
+  const blockingSet = new Set(reconstructionBlocking);
+  const schedulingIssues = candidate.compilationStage === "inventory" ? [] : await validateResearch(candidate);
+  const assetGroundingIssues = candidate.compilationStage === "inventory" ? [] : await assetSourceGroundingIssues(candidate, {
+    ...draftContext,
+    datasetRegistry,
+  });
+  const sharedWorkIssues = [];
+  if (draftContext?.compilationStage === "execution_plan") {
+    // New plans must expose work identity and a usable quote. A bounded repair
+    // cannot rewrite unrelated historical experiment objects.
+    const repairTargets = continuationRepairTargets(draftContext.continuation);
+    const required = draftContext.sharedWorkloadsRequired === false ? [] : draftContext.repairBaselineResearch
+      ? experiments.filter(e => repairTargets.some(t => t.experimentId === e.id)) : experiments;
+    for (const experiment of required) {
+      const workloads = experiment.compute?.workloads;
+      if (!workloads?.length) {
+        sharedWorkIssues.push(`Shared-work planning retry: ${experiment.id} must declare compute.workloads, including reusable training/setup and separate incremental evaluations. Reuse identical IDs across consumers and give every item a finite positive duration estimate. Do not change scientific scope.`);
+        continue;
+      }
+      const compute = experiment.compute ?? {};
+      const accelerators = compute.accelerator === "none" ? ["cpu"]
+        : compute.accelerator === "required" || compute.cpuFallbackAllowed === false
+          ? ["gpu"] : ["cpu", "gpu"];
+      for (const workload of workloads) for (const accelerator of accelerators) {
+        const minutes = workloadMinutes(workload, accelerator);
+        if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes <= 0) {
+          sharedWorkIssues.push(`Shared-work estimate retry: ${experiment.id}/${workload?.id ?? "unnamed-workload"} must provide a finite positive ${accelerator} duration. Use an explicit conservative rate assumption when no benchmark exists; null or omission is not a quote.`);
+        }
+      }
+    }
+    try { sharedWorkloads(experiments); } catch (error) { sharedWorkIssues.push(error.message); }
+  }
+  return {
+    agentPlanned,
+    coverage,
+    blockingIssues: [
+      ...reconstructionBlocking,
+      ...structureIssues.filter((issue) => !blockingSet.has(issue)),
+      ...schedulingIssues,
+      ...sharedWorkIssues,
+      ...(agentPlanned ? [] : assetGroundingIssues),
+    ],
+    advisoryIssues: [
+      ...coverage.issues.map((issue) =>
+        `Initial catalog coverage remains partial: ${issue} Preserve the visible gap for user review; this warning does not establish scientific support or authorize extra resources.`),
+      ...reconstructionIssues.filter((issue) => !blockingSet.has(issue)
+        && !/^(?:Scientific coverage|Direct-evidence) retry:/.test(issue)),
+      ...(agentPlanned ? assetGroundingIssues : []),
+    ],
+  };
+}
+
+/** All transports and completed-output recovery use this acceptance boundary.
+ * Executors own transport/retries only; none may downgrade scientific scope.
+ */
+export async function acceptCompilerDraft({ bundle, draft, validateResearch = async () => [], sourceReviewer = reviewCompilerSources }) {
+  const draftContext = compilerDraftContext(bundle);
+  const preparedDraft = bundle.sourceInventory ? mergeInventoryPreparation(bundle.sourceInventory, draft) : draft;
+  const normalized = normalizeCompilerResearchDraft(preparedDraft, draftContext, { collectIssues: true });
+  const candidateResearch = applyCompilationLicensePolicy(
+    pinResearchRepository(normalized.research, bundle.repositoryIdentity), bundle.task.licensePolicy,
+  );
+  if (candidateResearch.compilationStage === "inventory") candidateResearch.provenance.sourceIdentity = {
+    paperDigest: bundle.runtimeTask?.paper?.digest,
+    repository: structuredClone(bundle.repositoryIdentity),
+  };
+  const repair = applyContinuationRepairBoundary(candidateResearch, draftContext);
+  const candidate = repair.research;
+  const coveragePath = path.join(bundle.directories.execution, "compiler-coverage.json");
+  const previousCoverage = await pathExists(coveragePath) ? await readJson(coveragePath) : null;
+  const review = await reviewCompilerCandidate({
+    candidate, draftContext,
+    reconstructionIssues: [...repair.issues, ...compilerReconstructionRetryIssues(candidate, draftContext)],
+    structureIssues: normalized.structureIssues,
+    previousCoverageInventory: previousCoverage?.inventory ?? [],
+    validateResearch,
+    datasetRegistry: await readJson(path.join(bundle.directories.input, "dataset-source-registry.json")),
+  });
+  await writeJson(coveragePath, review.coverage);
+  if (review.blockingIssues.length) throw new CiteArkError(review.blockingIssues.join("\n"));
+  const normalizationWarnings = attachCompilerAdvisories(candidate, normalized.warnings, review.advisoryIssues);
+  if (candidate.provenance) delete candidate.provenance.compilerSourceReview;
+  if (bundle.sourceInventory) {
+    candidate.provenance.reproductionPreparation = { sourceInventoryDigest: candidate.sourceInventory.digest,
+      status: "prepared", sourceContent: candidate.sourceInventory.revisions?.length ? "revised_with_sources" : "preserved", scientificSupport: "not_assessed" };
+  } else if (candidate.compilationStage === "inventory") {
+    candidate.provenance.compilerSourceReview = {
+      accepted: false, status: "deferred", mode: "agentic_reading",
+      reason: "Initial reading is a visible, revisable catalog rather than a release gate. Reproduction may reread and correct it; independent assessment judges source fidelity and observed evidence.",
+    };
+  } else {
+    const sourceReview = await sourceReviewer({ bundle, candidate, paperPath: draftContext.paperPath }).catch((error) => {
+      // Provider failures cannot be repaired by regenerating the scientific plan.
+      // Use the existing terminal review boundary in every compiler transport.
+      if (error.failureCategory === "provider") throw new CiteArkError(error.message, {
+        cause: error, failureCode: "compiler.source_review_unavailable", retryable: false,
+        failureCategory: "provider", recoveryAction: error.recoveryAction,
+      });
+      throw error;
+    });
+    if (sourceReview?.accepted !== true) throw new CiteArkError("Independent source review did not accept candidate", { failureCode: "compiler.source_review_unavailable", retryable: false });
+    candidate.provenance = { ...(candidate.provenance ?? {}), compilerSourceReview: sourceReview };
+  }
+  await writeJson(path.join(bundle.directories.output, "research.normalized.json"), candidate);
+  return { research: candidate, normalizationWarnings, coverage: review.coverage };
+}
+
+export function attachCompilerAdvisories(research, existingWarnings, advisoryIssues) {
+  const warnings = [...new Set([
+    ...(Array.isArray(existingWarnings) ? existingWarnings : []),
+    ...(Array.isArray(advisoryIssues) ? advisoryIssues : [])
+      .filter((issue) => typeof issue === "string" && issue.trim())
+      .map((issue) => `Execution-agent advisory: ${issue.trim()}`),
+  ])];
+  const bounded = warnings.length > 100
+    ? [
+        ...warnings.slice(0, 99),
+        `${warnings.length - 99} additional compiler advisories were omitted from this record.`,
+      ]
+    : warnings;
+  research.provenance = {
+    ...(research.provenance ?? {}),
+    ...(bounded.length ? { normalizationWarnings: bounded } : {}),
+  };
+  return bounded;
+}
+
+export function compilerDraftContext(bundle) {
+  const paper = bundle.runtimeTask?.paper ?? {};
+  return {
+    taskName: bundle.task?.name,
+    compilationStage: bundle.task?.compilationStage,
+    // Completed/ongoing legacy checkpoints must remain recoverable without
+    // paying to recompile their already-fixed scientific plan.
+    sharedWorkloadsRequired: !bundle.restored,
+    reproductionScope: bundle.runtimeTask?.reproductionScope ?? bundle.task?.reproductionScope,
+    computeContext: bundle.runtimeTask?.computeContext ?? bundle.task?.computeContext,
+    paperTitle: paper.title,
+    paperUri: paper.sourceUrl ?? paper.resolvedUrl,
+    paperDigest: paper.digest,
+    paperPath: compilerPaperPath(bundle, paper.path),
+    repositoryRoot: bundle.directories.repository,
+    repositoryIdentity: bundle.repositoryIdentity,
+    repositoryFiles: (bundle.beforeSnapshot?.entries ?? [])
+      .filter((entry) => entry?.type === "file" && typeof entry.path === "string")
+      .map((entry) => entry.path),
+    licensePolicy: bundle.task?.licensePolicy,
+    continuation: bundle.runtimeTask?.continuation ?? null,
+    repairBaselineResearch: bundle.repairBaselineResearch ?? null,
+  };
+}
+
+function compilerPaperPath(bundle, runtimePath) {
+  const prefix = "/job/input/";
+  if (typeof runtimePath !== "string" || !runtimePath.startsWith(prefix)) return undefined;
+  const relative = runtimePath.slice(prefix.length);
+  if (!relative || relative.split("/").includes("..")) return undefined;
+  return path.join(bundle.directories.input, ...relative.split("/"));
+}
+
+export function normalizeCompilationTask(input) {
+  const issues = [];
+  if (!isRecord(input)) throw new CiteArkError("编译任务必须是对象");
+  if (input.schemaVersion !== "0.1") issues.push("schemaVersion 必须是 0.1");
+  required(input.name, "name", issues);
+  validateSource(input.paper, "paper", issues);
+  if (input.repository !== undefined) {
+    validateSource(input.repository, "repository", issues);
+  }
+  if (input.repairBaseline !== undefined) {
+    if (!isRecord(input.repairBaseline)) {
+      issues.push("repairBaseline 必须是对象");
+    } else if (typeof input.repairBaseline.path !== "string" || !input.repairBaseline.path.trim()) {
+      issues.push("repairBaseline.path 必须是非空字符串");
+    }
+  }
+  if (
+    input.agent?.runtime != null &&
+    !new Set(["claude-code", "codex", "opencode"]).has(input.agent.runtime)
+  ) {
+    issues.push("agent.runtime 无效");
+  }
+  if (
+    input.agent?.reasoningMode !== undefined &&
+    !new Set(["standard", "pro"]).has(input.agent.reasoningMode)
+  ) {
+    issues.push("agent.reasoningMode 无效");
+  }
+  if (input.agent?.reasoningMode === "pro" && input.agent?.runtime === "claude-code") {
+    issues.push("agent.reasoningMode=pro 仅支持 Codex 和 OpenCode");
+  }
+  if (input.reproductionScope !== undefined && !["low", "medium", "high"].includes(input.reproductionScope)) issues.push("reproductionScope 无效");
+  if (input.compilationStage !== undefined && !["inventory", "execution_plan"].includes(input.compilationStage)) issues.push("compilationStage 无效");
+  if (input.sourceReviewMode !== undefined && !["deferred", "required"].includes(input.sourceReviewMode)) issues.push("sourceReviewMode 无效");
+  if (input.researchGoal !== undefined && (typeof input.researchGoal !== 'string' || input.researchGoal.length > 32768)) issues.push('researchGoal 必须是最多 32768 字符的文本');
+  if (input.reproductionGuide !== undefined && (typeof input.reproductionGuide !== "string" || input.reproductionGuide.length > 262_144)) issues.push("reproductionGuide 必须是最多 262144 字符的文本");
+  if (issues.length) throw new CiteArkError(`研究编译任务校验失败：\n- ${issues.join("\n- ")}`);
+  return {
+    ...input,
+    compilationStage: input.compilationStage ?? (input.repairBaseline ? "execution_plan" : "inventory"),
+    agent: {
+      runtime: input.agent?.runtime ?? null,
+      model: input.agent?.model ?? null,
+      subagentModel: input.agent?.subagentModel ?? null,
+      autoCompactWindow: input.agent?.autoCompactWindow ?? 786432,
+      effort: input.agent?.effort ?? "high",
+      reasoningMode: input.agent?.reasoningMode ?? "standard",
+      maxTurns: input.agent?.maxTurns ?? 100,
+      maxBudgetUsd: input.agent?.maxBudgetUsd ?? 5,
+      validationRetries: input.agent?.validationRetries ?? 1,
+      capacityRetryDelaySeconds: input.agent?.capacityRetryDelaySeconds ?? 10,
+      capacityMaxRetries: input.agent?.capacityMaxRetries ?? 30,
+    },
+    environment: {
+      image: input.environment?.image ?? "citeark-agent/runtime:0.2.0",
+      timeoutMinutes: input.environment?.timeoutMinutes ?? 45,
+      cpus: input.environment?.cpus ?? 4,
+      memoryGb: input.environment?.memoryGb ?? 8,
+      shmGb: input.environment?.shmGb ?? 1,
+      gpu: input.environment?.gpu ?? "none",
+      networkAccess: true,
+    },
+  };
+}
+
+export async function prepareCompilationBundle({ task, taskDirectory, runsDirectory, runId, prepareMarkdown = preparePaperMarkdown }) {
+  const runDirectory = path.resolve(runsDirectory, runId);
+  if (await pathExists(runDirectory)) throw new CiteArkError(`运行目录已经存在：${runDirectory}`);
+  const directories = {
+    run: runDirectory,
+    input: path.join(runDirectory, "input"),
+    workspace: path.join(runDirectory, "workspace"),
+    repository: path.join(runDirectory, "workspace", "repository"),
+    repositorySnapshot: path.join(runDirectory, "snapshot", "repository"),
+    output: path.join(runDirectory, "output"),
+    runtimeHome: path.join(runDirectory, "runtime-home"),
+    execution: path.join(runDirectory, "execution"),
+    artifact: path.join(runDirectory, "artifact"),
+  };
+  await Promise.all(
+    Object.values(directories)
+      .filter(
+        (item) =>
+          item !== directories.run &&
+          item !== directories.repository &&
+          item !== directories.repositorySnapshot,
+      )
+      .map((item) => mkdir(item, { recursive: true })),
+  );
+  await stageReferenceMaterials(task.referenceMaterialsPath, directories.input);
+  const sourceInventory = task.sourceInventory?.path
+    ? normalizeResearchStructure(await readJson(path.resolve(taskDirectory, task.sourceInventory.path))) : null;
+  if (sourceInventory && (task.compilationStage !== "execution_plan" || sourceInventory.compilationStage !== "inventory"
+    || task.sourceInventory.digest !== `sha256:${sha256Value(sourceInventory)}`))
+    throw new CiteArkError("Reproduction preparation requires the original inventory digest");
+  const runtimeTask = structuredClone(task);
+  if (task.referenceMaterialsPath) runtimeTask.referenceMaterialsPath = "/job/input/reference-materials.json";
+  if (sourceInventory) {
+    await writeJson(path.join(directories.input, "source-inventory.json"), sourceInventory);
+    runtimeTask.sourceInventory = { ...task.sourceInventory, path: "/job/input/source-inventory.json" };
+  }
+  await writeJson(path.join(directories.input, "submitted-compile-task.json"), task);
+  const repairBaselineDraft = task.repairBaseline?.path
+    ? normalizeResearchStructure(
+        await readJson(path.resolve(taskDirectory, task.repairBaseline.path)),
+      )
+    : null;
+  await copyPaper(runtimeTask, taskDirectory, directories.input);
+  await snapshotRemotePaper(runtimeTask, directories.input);
+  const fixedPaperPath = compilerPaperPath({ directories }, runtimeTask.paper?.path);
+  if (fixedPaperPath) {
+    const paperDigest = `sha256:${await sha256File(fixedPaperPath)}`;
+    if (runtimeTask.paper.digest && runtimeTask.paper.digest !== paperDigest) throw new CiteArkError("Fixed paper digest changed before preparation");
+    if (sourceInventory && sourceInventory.provenance.sourceIdentity?.paperDigest !== paperDigest) throw new CiteArkError("Reproduction paper differs from the reviewed inventory");
+    runtimeTask.paper.digest = paperDigest;
+    const stagedReading = { ...task.paper.preparedReading };
+    delete stagedReading.directory;
+    const reading = runtimeTask.paper.markdownPath && stagedReading.status === "ready" ? stagedReading : await prepareMarkdown({ paperPath: fixedPaperPath,
+      outputDirectory: path.join(directories.input, "paper-reading"),
+      cacheDirectory: process.env.CITEARK_PAPER_MARKDOWN_CACHE ?? path.join(path.resolve(runsDirectory), ".paper-markdown-cache") });
+    runtimeTask.paper.reading = reading;
+    if (reading.status === "ready") {
+      runtimeTask.paper.markdownPath = "/job/input/paper-reading/paper.md";
+      runtimeTask.paper.sourceMapPath = "/job/input/paper-reading/source-map.json";
+    }
+  }
+  const repositoryProvenance = task.repository
+    ? await prepareRepository(runtimeTask, taskDirectory, directories.repository)
+    : await prepareMissingRepository(directories.repository);
+  const beforeSnapshot = await snapshotDirectory(directories.repository);
+  const repositorySnapshotDigest = snapshotDigest(beforeSnapshot);
+  let repositoryIdentity = task.repository
+    ? {
+        available: true,
+        url:
+          repositoryProvenance.sourceType === "url"
+            ? task.repository.url
+            : `citeark://snapshot/sha256/${repositorySnapshotDigest.slice("sha256:".length)}`,
+        commit:
+          repositoryProvenance.sourceType === "url"
+            ? repositoryProvenance.commit
+            : repositorySnapshotDigest,
+        snapshotDigest: repositorySnapshotDigest,
+      }
+    : {
+        available: false,
+        reason: "The fixed paper did not declare a unique verified code repository.",
+      };
+  if (sourceInventory) {
+    const originalIdentity = sourceInventory.provenance.sourceIdentity?.repository;
+    if (!originalIdentity || originalIdentity.available !== repositoryIdentity.available
+      || (originalIdentity.available && originalIdentity.snapshotDigest !== repositoryIdentity.snapshotDigest))
+      throw new CiteArkError("Reproduction repository differs from the reviewed inventory");
+    repositoryIdentity = structuredClone(originalIdentity);
+  }
+  if (task.repository && !repositoryIdentity.commit) {
+    throw new CiteArkError("Research Compiler 无法固定仓库版本");
+  }
+  const repairBaselineResearch = repairBaselineDraft
+    ? applyCompilationLicensePolicy(
+        pinResearchRepository(repairBaselineDraft, repositoryIdentity),
+        task.licensePolicy,
+      )
+    : null;
+  await mkdir(path.dirname(directories.repositorySnapshot), { recursive: true });
+  await cp(directories.repository, directories.repositorySnapshot, {
+    recursive: true,
+    force: true,
+    verbatimSymlinks: true,
+  });
+  runtimeTask.run = { id: runId, outputPath: "/job/output", repositoryPath: "/job/workspace/repository" };
+  runtimeTask.repository = task.repository
+    ? { path: "/job/workspace/repository", commit: repositoryProvenance.commit }
+    : {
+        available: false,
+        path: "/job/workspace/repository",
+        reason: repositoryIdentity.reason,
+      };
+  if (repairBaselineResearch) {
+    await writeJson(
+      path.join(directories.input, "repair-baseline.json"),
+      repairBaselineResearch,
+    );
+    await writeJson(
+      path.join(directories.output, "research.json"),
+      repairBaselineResearch,
+    );
+    runtimeTask.repairBaseline = {
+      ...task.repairBaseline,
+      path: "/job/input/repair-baseline.json",
+    };
+  }
+  runtimeTask.scientificPlanningPolicy = scientificPlanningPolicy(runtimeTask.reproductionScope, task.compilationStage);
+  await writeJson(path.join(directories.input, "compile-task.json"), runtimeTask);
+  await writeJson(
+    path.join(directories.input, "repository-identity.json"),
+    repositoryIdentity,
+  );
+  await writeJson(path.join(directories.input, "parser-catalog.json"), listEvidenceParsers());
+  if (sourceInventory) {
+    const schema = await readJson(path.join(PACKAGE_ROOT, "schemas/research.schema.json"));
+    await writeJson(path.join(directories.input, "research.schema.json"), {
+      $schema: schema.$schema,
+      title: "Reproduction preparation draft from an accepted inventory",
+      type: "object", additionalProperties: false, required: ["experiments", "dispositions"],
+      properties: {
+        inventoryRevisions: { type: "array", items: { type: "object", additionalProperties: false,
+          required: ["claimId", "claim", "reason", "sources"], properties: {
+            claimId: { type: "string", minLength: 1 }, claim: schema.properties.claims.items,
+            reason: { type: "string", minLength: 1 },
+            sources: { type: "array", minItems: 1, items: { type: "object", required: ["sourceId", "locator"],
+              properties: { sourceId: { type: "string" }, locator: { type: "string", minLength: 1 } } } },
+          } } },
+        researchObjects: schema.properties.researchObjects,
+        experiments: schema.properties.experiments,
+        experimentSelection: schema.properties.experimentSelection,
+        dispositions: { type: "array", items: { type: "object", additionalProperties: false,
+          required: ["claimId", "reproduction"], properties: {
+            claimId: { type: "string", minLength: 1 },
+            reproduction: schema.properties.claims.items.properties.reproduction,
+          } } },
+      },
+      $defs: schema.$defs,
+    });
+  } else {
+    await cp(path.join(PACKAGE_ROOT, "schemas", task.compilationStage === "inventory" ? "research-inventory-draft.schema.json" : "research.schema.json"), path.join(directories.input, "research.schema.json"));
+  }
+  await cp(
+    path.join(
+      PACKAGE_ROOT,
+      "prompts",
+      repairBaselineResearch ? "repair-research.md" : task.compilationStage === "execution_plan" ? "prepare-reproduction.md" : "compile-research.md",
+    ),
+    path.join(directories.input, "agent-instructions.md"),
+  );
+  await cp(
+    path.join(PACKAGE_ROOT, "data", "dataset-source-registry.v1.json"),
+    path.join(directories.input, "dataset-source-registry.json"),
+  );
+  await writeJson(path.join(directories.execution, "workspace-before.json"), beforeSnapshot);
+  const sessionId = createSessionId();
+  const state = {
+    schemaVersion: "0.1",
+    runId,
+    sessionId,
+    phase: "research_compilation",
+    status: "prepared",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    taskName: task.name,
+    runtime: task.agent.runtime,
+    sandbox: "docker",
+    image: task.environment.image,
+    repository: { ...repositoryProvenance, identity: repositoryIdentity },
+  };
+  await writeJson(path.join(directories.run, "run.json"), state);
+  const bundle = {
+    runId,
+    sessionId,
+    task,
+    runtimeTask,
+    directories,
+    repositoryProvenance,
+    repositoryIdentity,
+    repairBaselineResearch,
+    sourceInventory,
+    beforeSnapshot,
+    state,
+    attempts: [],
+  };
+  await saveRunRecovery(bundle, async () => {});
+  return bundle;
+}
+
+export function compilerPrompt(attempt, validationIssues, options = {}) {
+  const failedTargets = continuationRepairTargets(options.continuation);
+  if (options.repairBaseline && failedTargets.length) {
+    const targetList = failedTargets
+      .map((target) => `${target.claimId}/${target.experimentId}`)
+      .join(", ");
+    if (attempt === 1) {
+      return `Repair the staged Research Plan in /job/output/research.json for only these failed continuation targets: ${targetList}. The immutable baseline is also available at /job/input/repair-baseline.json. Read the requestedTargets re-execution reasons or failedTargets diagnoses in /job/input/compile-task.json, inspect the fixed repository, and make the smallest executable correction to those experiment objects. Claims, reported values, unselected completed targets, unrelated experiments, experiment ids, claim bindings, and reportedMeasurementId bindings are locked by the host and cannot be changed. Do not redesign the whole plan. Only write /job/output/research.json; do not create a new official helper file that is absent from the fixed repository snapshot.`;
+    }
+    return `The bounded continuation repair still failed authoritative validation:\n${validationIssues.map((issue) => `- ${issue}`).join("\n")}\nInspect the current /job/output/research.json and repair only these failed targets: ${targetList}. Preserve every part that is already valid. Claims, reported values, unselected completed targets, unrelated experiments, ids, claim bindings, and reportedMeasurementId bindings are host-locked. Make the minimum grounded change, parse the complete JSON, and stop after writing /job/output/research.json. Do not replace the plan, rename targets, remove measurements, or create an official helper file outside the fixed repository snapshot.`;
+  }
+  if (attempt === 1) return "Read /job/input/agent-instructions.md and /job/input/compile-task.json. Follow the task's compilationStage: inventory records the fixed paper faithfully; execution_plan prepares reproduction from /job/input/source-inventory.json. Write the completed submission to /job/output/research.json and stop. Do not perform experiments during either preparation stage.";
+  return `The draft has these authoritative defects:\n${validationIssues.map((issue) => `- ${issue}`).join("\n")}\nRead the existing research.json and correct these defects while preserving grounded content. Keep the original claim scope and reported values. Do not delete discovered measurements or relabel empirical scope as context to pass validation. Preserve measurement ids when regrouping independent results into separate claims. Operational commands, parser refinements and dependency work belong in the execution workspace. Produce readable JSON, parse it, and stop.`;
+}
+
+/**
+ * Treat a continuation repair as a transaction over an immutable Research
+ * Plan. The model may propose a complete document, but only failed experiment
+ * objects can be committed. This prevents a later retry from regressing
+ * completed targets or rewriting paper claims and reported values.
+ */
+export function applyContinuationRepairBoundary(candidate, context = {}) {
+  const baseline = context.repairBaselineResearch;
+  const failedTargets = continuationRepairTargets(context.continuation);
+  if (!baseline || !failedTargets.length) {
+    return { research: candidate, issues: [] };
+  }
+
+  const issues = [];
+  const merged = structuredClone(baseline);
+  const baselineExperiments = Array.isArray(merged.experiments) ? merged.experiments : [];
+  const candidateExperiments = Array.isArray(candidate?.experiments) ? candidate.experiments : [];
+  const baselineById = new Map(baselineExperiments.map((experiment) => [experiment?.id, experiment]));
+  const candidateById = new Map(candidateExperiments.map((experiment) => [experiment?.id, experiment]));
+  const failedByExperiment = new Map();
+  for (const target of failedTargets) {
+    const targets = failedByExperiment.get(target.experimentId) ?? [];
+    targets.push(target);
+    failedByExperiment.set(target.experimentId, targets);
+  }
+
+  for (const [experimentId, targets] of failedByExperiment) {
+    const baselineExperiment = baselineById.get(experimentId);
+    const candidateExperiment = candidateById.get(experimentId);
+    if (!baselineExperiment || !candidateExperiment) {
+      issues.push(
+        `Continuation-repair boundary retry: failed target ${experimentId} must remain present under its original experiment id.`,
+      );
+      continue;
+    }
+    const baselineClaimIds = sortedStrings(baselineExperiment.claimIds);
+    const candidateClaimIds = sortedStrings(candidateExperiment.claimIds);
+    const requiredClaimIds = sortedStrings(targets.map((target) => target.claimId));
+    if (
+      !isDeepStrictEqual(candidateClaimIds, baselineClaimIds)
+      || requiredClaimIds.some((claimId) => !candidateClaimIds.includes(claimId))
+    ) {
+      issues.push(
+        `Continuation-repair boundary retry: ${experimentId} changed its immutable claim binding; preserve ${baselineClaimIds.join(", ")}.`,
+      );
+      continue;
+    }
+    const baselineMeasurementIds = reportedMeasurementBindings(baselineExperiment);
+    const candidateMeasurementIds = reportedMeasurementBindings(candidateExperiment);
+    if (!isDeepStrictEqual(candidateMeasurementIds, baselineMeasurementIds)) {
+      issues.push(
+        `Continuation-repair boundary retry: ${experimentId} changed its immutable reportedMeasurementId binding; preserve ${baselineMeasurementIds.join(", ")}.`,
+      );
+      continue;
+    }
+    const index = baselineExperiments.findIndex((experiment) => experiment?.id === experimentId);
+    baselineExperiments[index] = structuredClone(candidateExperiment);
+  }
+
+  return {
+    research: normalizeResearchStructure(merged),
+    issues,
+  };
+}
+
+
+function reportedMeasurementBindings(experiment) {
+  return sortedStrings(
+    (Array.isArray(experiment?.measurements) ? experiment.measurements : [])
+      .map((measurement) => measurement?.reportedMeasurementId),
+  );
+}
+
+function sortedStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .filter((value) => typeof value === "string" && value.trim())
+    .map((value) => value.trim()))]
+    .sort();
+}
+
+async function snapshotRemotePaper(runtimeTask, inputDirectory) {
+  if (!runtimeTask.paper?.url) return;
+  const sourceUrl = new URL(runtimeTask.paper.url);
+  if (!new Set(["http:", "https:"]).has(sourceUrl.protocol)) {
+    throw new CiteArkError(`论文 URL 只支持 HTTP(S)：${runtimeTask.paper.url}`);
+  }
+  let response;
+  try {
+    response = await fetch(sourceUrl, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(60_000),
+      headers: { "user-agent": "CiteArk-Agent/0.2 (+https://citeark.com)" },
+    });
+  } catch (error) {
+    throw new CiteArkError(`无法固定论文快照：${sourceUrl}`, { cause: error });
+  }
+  if (!response.ok) {
+    throw new CiteArkError(`无法固定论文快照：${sourceUrl} 返回 HTTP ${response.status}`);
+  }
+  const body = Buffer.from(await response.arrayBuffer());
+  const maximumBytes = 10 * 1024 * 1024;
+  if (!body.length || body.length > maximumBytes) {
+    throw new CiteArkError(`论文快照大小无效：${body.length} bytes（上限 ${maximumBytes}）`);
+  }
+  const contentType = response.headers.get("content-type")?.split(";")[0].trim().toLowerCase();
+  const extension = contentType === "application/pdf" ? ".pdf" : contentType === "text/plain" ? ".txt" : ".html";
+  const paperDirectory = path.join(inputDirectory, "paper");
+  const filename = `paper${extension}`;
+  await mkdir(paperDirectory, { recursive: true });
+  await writeFile(path.join(paperDirectory, filename), body);
+  runtimeTask.paper = {
+    title: runtimeTask.paper.title,
+    path: `/job/input/paper/${filename}`,
+    sourceUrl: sourceUrl.toString(),
+    resolvedUrl: response.url,
+    digest: `sha256:${createHash("sha256").update(body).digest("hex")}`,
+    mediaType: contentType ?? "application/octet-stream",
+    size: body.length,
+  };
+}
+
+async function readFileText(target) {
+  const { readFile } = await import("node:fs/promises");
+  return readFile(target, "utf8");
+}
+
+export function pinResearchRepository(research, repositoryIdentity) {
+  const pinned = structuredClone(research);
+  if (
+    !repositoryIdentity?.available ||
+    !repositoryIdentity.url ||
+    !repositoryIdentity.commit
+  ) {
+    pinned.sources = pinned.sources.filter((source) => source.kind !== "repository");
+    pinned.experiments = pinned.experiments
+      .filter((experiment) => experiment.implementationOrigin === "citeark_reconstruction")
+      .map((experiment) => ({
+        ...experiment,
+        implementationOrigin: "citeark_reconstruction",
+        repository: { ...RECONSTRUCTION_REPOSITORY },
+      }));
+    return normalizeResearchStructure(pinned);
+  }
+  for (const source of pinned.sources) {
+    if (source.kind !== "repository") continue;
+    source.uri = repositoryIdentity.url;
+    source.version = repositoryIdentity.commit;
+    source.digest = repositoryIdentity.snapshotDigest;
+  }
+  for (const experiment of pinned.experiments) {
+    if (experiment.implementationOrigin === "citeark_reconstruction") {
+      experiment.repository = { ...RECONSTRUCTION_REPOSITORY };
+    } else {
+      experiment.implementationOrigin = "official";
+      experiment.repository = {
+        implementationOrigin: "official",
+        url: repositoryIdentity.url,
+        commit: repositoryIdentity.commit,
+      };
+    }
+  }
+  return normalizeResearchStructure(pinned);
+}
+
+async function prepareMissingRepository(destination) {
+  await mkdir(destination, { recursive: true });
+  return {
+    sourceType: "none",
+    submittedSource: null,
+    commit: null,
+    dirty: null,
+  };
+}
+
+export function applyCompilationLicensePolicy(research, licensePolicy) {
+  const normalized = structuredClone(research);
+  normalized.license = {
+    ...normalized.license,
+    executionAllowed: licensePolicy?.executable !== false,
+    redistribution:
+      normalized.license.redistribution ??
+      (licensePolicy?.redistributable
+        ? "Source redistribution permitted by the recorded license assessment"
+        : "Source materials remain link-only; the Artifact contains derived execution records"),
+  };
+  return normalizeResearchStructure(normalized);
+}
+
+function validateSource(value, label, issues) {
+  if (!isRecord(value)) return issues.push(`${label} 必须是对象`);
+  const count = Number(Boolean(value.path)) + Number(Boolean(value.url));
+  if (count !== 1) issues.push(`${label} 必须且只能提供 path 或 url`);
+}
+
+function required(value, label, issues) {
+  if (typeof value !== "string" || !value.trim()) issues.push(`${label} 必须是非空字符串`);
+}