@citeark/agent 0.3.20

package/src/pipeline/recovery-error.mjs

@@ -0,0 +1,11 @@
+/** A deterministic recovery-state mismatch needs repair, not a new paid run. */
+export class RecoveryStateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RecoveryStateError";
+    this.failureCategory = "recovery";
+    this.failureCode = "target.recovery_state_invalid";
+    this.retryable = false;
+    this.retryStrategy = "none";
+  }
+}

package/src/pipeline/replay.mjs

@@ -0,0 +1,304 @@
+import { buildExecutionHandoff } from "../deployment/handoff.mjs";
+import { prepareExecutionRecipe } from "../deployment/recipe.mjs";
+import path from "node:path";
+import { mkdir, mkdtemp, rename } from "node:fs/promises";
+import { relocateStageValue } from "./stage-checkpoint.mjs";
+
+import {
+  loadExecutionContract,
+  loadVerificationPolicy,
+} from "../contracts/execution-contract.mjs";
+import { assemblePipelineCap } from "../cap/v2/pipeline-artifact.mjs";
+import { parseContractEvidence } from "../evidence/registry.mjs";
+import { buildRunnerAudit } from "../execution/runner-audit.mjs";
+import { loadResearchStructure } from "../research/structure.mjs";
+import { CiteArkError, readJson, pathExists, sha256File, sha256Value } from "../util.mjs";
+import { validateResultFile } from "../protocol.mjs";
+import { SCIENTIFIC_ASSESSMENT_RUBRIC_VERSION } from "../verification/ai-assessor.mjs";
+import { evaluateClaim } from "../verification/claim-evaluator.mjs";
+import { checkExecutionIntegrity } from "../verification/integrity.mjs";
+import { renderResearchCard } from "../research-card/renderer.mjs";
+import { buildVerifiedConclusion } from "../research-card/verified-conclusion.mjs";
+import { renderAgentDiagnosis } from "../diagnosis/renderer.mjs";
+import { buildOutputRegistry } from "../results/output-registry.mjs";
+import { resolveResearchPlan, planEvidencePaths } from "../reproduction/plan.mjs";
+import { buildAssessmentEvidenceContext } from "../verification/evidence-context.mjs";
+
+export async function replayRunToCap({
+  researchPath,
+  contractPath,
+  executionContractPath,
+  policyPath,
+  runDirectory,
+  capDirectory,
+  signingKeyPath,
+  sourceReproductionDigest,
+  processingBinding,
+  researchArtifactDigest,
+  getPipelineSummary,
+  scientificAssessor,
+  handoffCompletion,
+  onAssessment = async () => {},
+  onStageChange = async () => {},
+  stageCheckpoint = async (_stage, operation) => operation(),
+}) {
+  if (
+    typeof researchArtifactDigest !== "string" ||
+    !/^sha256:[0-9a-f]{64}$/.test(researchArtifactDigest)
+  ) {
+    throw new CiteArkError(
+      "CAP replay requires the verified Research Plan CAP digest",
+    );
+  }
+  const [research, originalContract, executionContract, run] = await Promise.all([
+    loadResearchStructure(researchPath),
+    loadExecutionContract(contractPath),
+    executionContractPath
+      ? loadExecutionContract(executionContractPath)
+      : Promise.resolve(null),
+    readJson(path.join(runDirectory, "run.json")),
+  ]);
+  const sourceContract = executionContract ?? originalContract;
+  const resolvedExecutionContract = await resolveResearchPlan(
+    sourceContract,
+    path.join(runDirectory, "output"),
+  );
+  const member = sourceContract.campaign?.members.find(item =>
+    item.contract.contractDigest === originalContract.contractDigest);
+  if (sourceContract.campaign && !member) throw new CiteArkError("共享执行没有在启动前绑定当前目标契约");
+  // Separate experiment views keep overlapping measurement IDs distinct in the
+  // registry while explicitly retaining the one physical execution identity.
+  const publicationRun = member ? { ...run, sharedExecutionRunId: run.runId,
+    runId: `${run.runId}-${sha256Value(originalContract.research.experimentId).slice(0, 12)}` } : run;
+  const projectedMeasurements = member ? resolvedExecutionContract.measurements.flatMap(measurement => {
+    const id = Object.keys(member.measurementMap).find(key => member.measurementMap[key] === measurement.measurementId);
+    return id ? [{ ...measurement, measurementId: id }] : [];
+  }) : null;
+  const contract = member ? {
+    ...originalContract, measurements: projectedMeasurements,
+    executionPlan: resolvedExecutionContract.executionPlan,
+  } : executionContract
+    ? {
+        ...originalContract,
+        protocol: resolvedExecutionContract.protocol,
+        measurements: resolvedExecutionContract.measurements,
+        research: {
+          ...originalContract.research,
+          measurementIds: resolvedExecutionContract.research.measurementIds,
+          claimMeasurementIds: resolvedExecutionContract.research.claimMeasurementIds,
+          uncoveredMeasurementIds:
+            resolvedExecutionContract.research.uncoveredMeasurementIds,
+          claimCoverage: resolvedExecutionContract.research.claimCoverage,
+        },
+        executionPlan: resolvedExecutionContract.executionPlan,
+      }
+    : resolvedExecutionContract;
+  const resultValidation = await validateResultFile(
+    path.join(runDirectory, "output", "result.json"),
+    sourceContract,
+    path.join(runDirectory, "output"),
+  );
+  if (resultValidation.issues.length) {
+    throw new CiteArkError(
+      `CAP replay rejected an invalid Execution Result 1.0:\n- ${resultValidation.issues.join("\n- ")}`,
+    );
+  }
+  const result = resultValidation.result;
+  if (contract.executionPlan) {
+    for (const filename of await planEvidencePaths(path.join(runDirectory, "output"))) {
+      if (!result.evidence.some((item) => item.path === filename)) result.evidence.push({
+        path: filename, description: "Agent research plan snapshot; scientific validity and execution timing require independent audit",
+      });
+    }
+  }
+  const runnerAudit = await buildRunnerAudit({
+    runDirectory,
+    runtime: run.runtime ?? contract.agent?.runtime ?? "unknown",
+    sandbox: run.sandbox ?? "unknown",
+  });
+  const claim = research.claims.find((item) => item.versionId === contract.research.claimVersionId)
+    ?? research.claims.find((item) => item.id === contract.research.claimId);
+  const evidenceContext = await buildAssessmentEvidenceContext({ runDirectory, contract, claim, runnerAudit,
+    paperDigest: processingBinding?.sourceDigest });
+  // Reuse downstream results only for the same captured inputs. A parser or
+  // evidence repair invalidates post-processing, never scientific execution.
+  const capturedPaths = [...new Set([
+    "run.json", "output/result.json", "execution/trace.jsonl",
+    "execution/workspace-before.json", "execution/workspace-after.json", "execution/workspace-changes.json",
+    ...result.evidence.map((item) => `output/${item.path}`),
+    ...(result.outputs ?? []).filter((item) => item.path).map((item) => `output/${item.path}`),
+  ])].sort();
+  const captured = await Promise.all(capturedPaths.map(async (relative) => {
+    const filename = path.join(runDirectory, relative);
+    return [relative, await pathExists(filename) ? await sha256File(filename) : null];
+  }));
+  const revision = sha256Value({ plan: contract.executionPlan?.digest ?? contract.contractDigest,
+    captured, evidenceContext: evidenceContext.digest, rubric: SCIENTIFIC_ASSESSMENT_RUBRIC_VERSION });
+  const checkpoint = (stage, operation, stageRevision = revision) => stageCheckpoint(stage, operation, stageRevision);
+  const policy = await loadVerificationPolicy(policyPath, originalContract);
+  const sharedExecution = executionContract
+    ? {
+        sourceContractDigest: sourceContract.contractDigest,
+        projectedContractDigest: originalContract.contractDigest,
+        experimentVersionId: sourceContract.research.experimentVersionId,
+        sourceMeasurementIds: sourceContract.research.measurementIds,
+        projectedMeasurementIds: originalContract.research.measurementIds,
+        ...(member ? { campaignTargetContractDigest: member.contract.contractDigest,
+          experimentVersionId: member.contract.research.experimentVersionId,
+          sourceMeasurementIds: Object.keys(member.measurementMap) } : {}),
+      }
+    : null;
+  const outputDirectory = path.join(runDirectory, "output");
+  const [metrics, outputs] = await checkpoint(
+    "evidence_parsing",
+    async () => {
+      await onStageChange({ stage: "evidence_parsing", status: "started" });
+      const parsed = await Promise.all([
+        parseContractEvidence({
+          contract,
+          outputDirectory,
+          parsedAt: run.finishedAt,
+          result,
+        }),
+        buildOutputRegistry({
+          result,
+          outputDirectory,
+          runId: run.runId,
+          contractDigest: contract.contractDigest,
+          capturedAt: run.finishedAt,
+        }),
+      ]);
+      await onStageChange({ stage: "evidence_parsing", status: "completed" });
+      return parsed;
+    },
+  );
+  const { integrity, assessment, diagnosis } = await checkpoint(
+    "verification",
+    async () => {
+      await onStageChange({ stage: "verification", status: "started" });
+      const integrity = await checkExecutionIntegrity({
+        research,
+        contract,
+        runDirectory,
+        result,
+        metrics,
+        outputs,
+        runnerAudit,
+        sharedExecution,
+      });
+      const assessment = await evaluateClaim({
+        contract,
+        policy,
+        metrics,
+        outputs,
+        integrity,
+        result,
+        claim,
+        scientificAssessor,
+        runnerAudit,
+        evidenceContext,
+        assessedAt: run.finishedAt,
+      });
+      await onAssessment(assessment);
+      const diagnosis = renderAgentDiagnosis({
+        contract,
+        result,
+        assessment,
+        integrity,
+      });
+      await onStageChange({ stage: "verification", status: "completed" });
+      return { integrity, assessment, diagnosis };
+    },
+  );
+  const { verifiedConclusion, researchCard } = await checkpoint(
+    "research_card",
+    async () => {
+      await onStageChange({ stage: "research_card", status: "started" });
+      const verifiedConclusion = buildVerifiedConclusion({
+        research,
+        verifications: [{ contract, assessment, metrics, integrity }],
+        generatedAt: assessment.assessedAt ?? run.finishedAt,
+      });
+      const researchCard = await renderResearchCard({
+        research,
+        contract,
+        run,
+        result,
+        metrics,
+        outputs,
+        integrity,
+        assessment,
+        runnerAudit,
+        verifiedConclusion,
+        computeDecision: run.computeDecision ?? null,
+      });
+      await onStageChange({ stage: "research_card", status: "completed" });
+      return { verifiedConclusion, researchCard };
+    },
+  );
+  const deploymentHandoff = await checkpoint("execution_handoff", async () => {
+    await onStageChange({ stage: "execution_handoff", status: "started" });
+    const recipe = ['succeeded', 'partial'].includes(result.execution?.status)
+      ? await prepareExecutionRecipe({ runDirectory, evidenceContext, runnerAudit, run, result,
+          contract: sourceContract, complete: handoffCompletion }) : null;
+    const handoff = await buildExecutionHandoff({ runDirectory, research,
+      contract: sourceContract, targetContract: originalContract, policy, researchArtifactDigest, run, result, recipe });
+    await onStageChange({ stage: "execution_handoff", status: handoff ? "completed" : "skipped" });
+    return handoff;
+  }, `sha256:${sha256Value({ revision, handoffVersion: 1 })}`);
+  const cap = await checkpoint("packaging", async () => {
+    await onStageChange({ stage: "packaging", status: "started" });
+    const pipelineSummary =
+      typeof getPipelineSummary === "function"
+        ? await getPipelineSummary()
+        : null;
+    await mkdir(path.dirname(capDirectory), { recursive: true });
+    const staging = await mkdtemp(`${capDirectory}.building-`);
+    const cap = await assemblePipelineCap({
+      directory: staging,
+      deploymentHandoff,
+      sourceReproductionDigest,
+      research,
+      contract,
+      policy,
+      runDirectory,
+      run: publicationRun,
+      executionContract: member ? sourceContract : undefined,
+      result,
+      metrics,
+      outputs,
+      integrity,
+      assessment,
+      verifiedConclusion,
+      pipelineSummary,
+      researchCard,
+      runnerAudit,
+      evidenceContext,
+      diagnosis,
+      signingKeyPath,
+      processingBinding,
+      researchArtifactDigest,
+    });
+    // A failed packaging attempt never poisons the next attempt with a partially
+    // populated destination. Preserve any prior package when replacing it.
+    if (await pathExists(capDirectory)) await rename(capDirectory, `${staging}.previous`);
+    await rename(staging, capDirectory);
+    await onStageChange({ stage: "packaging", status: "completed" });
+    return relocateStageValue(cap, staging, capDirectory);
+  }, sha256Value({ revision, deploymentHandoff, sourceReproductionDigest, processingBinding: processingBinding ?? null, researchArtifactDigest: researchArtifactDigest ?? null }));
+  return {
+    research,
+    contract,
+    run: publicationRun,
+    result,
+    metrics,
+    outputs,
+    integrity,
+    assessment,
+    diagnosis,
+    verifiedConclusion,
+    researchCard,
+    runnerAudit,
+    cap,
+  };
+}

package/src/pipeline/shared-execution.mjs

@@ -0,0 +1,115 @@
+import { mkdir, cp } from "node:fs/promises";
+import path from "node:path";
+
+import { capDirectoryContentDigest, packCap } from "../cap/v2/archive.mjs";
+import { createExecutionContract, loadExecutionContract, loadVerificationPolicy } from "../contracts/execution-contract.mjs";
+import { campaignTargetDirectory } from "../contracts/campaign-contract.mjs";
+import { mergeAgentUsage } from "../telemetry/usage.mjs";
+import { sha256Value } from "../util.mjs";
+import { replayRunToCap } from "./replay.mjs";
+
+/**
+ * Produce a claim-specific contract, assessment and CAP from an experiment
+ * that has already executed under the same comprehensive shared scope.
+ * Scientific commands are never started here.
+ */
+export async function projectSharedExecutionClaim({
+  sourcePipeline,
+  researchPath,
+  claimId,
+  experimentId,
+  executionClaimIds,
+  workDirectory,
+  tolerance,
+  signingKeyPath,
+  processingBinding,
+  researchArtifactDigest,
+  scientificAssessor,
+}) {
+  const root = path.resolve(workDirectory);
+  const directories = {
+    root,
+    protocol: path.join(root, "protocol"),
+    private: path.join(root, "private"),
+    cap: path.join(root, "cap"),
+  };
+  await Promise.all(Object.values(directories).map((directory) =>
+    mkdir(directory, { recursive: true })));
+  const contractPath = path.join(directories.protocol, "execution-contract.json");
+  const policyPath = path.join(directories.private, "verification-policy.json");
+  let contract, policy;
+  if (sourcePipeline.contract.campaign) {
+    const original = campaignTargetDirectory(sourcePipeline.directories.protocol, { claimId, experimentId });
+    await cp(path.join(original, "contract.json"), contractPath);
+    await cp(path.join(original, "policy.json"), policyPath);
+    contract = await loadExecutionContract(contractPath);
+    policy = await loadVerificationPolicy(policyPath, contract);
+  } else ({ contract, policy } = await createExecutionContract({
+    researchPath,
+    claimId,
+    experimentId,
+    executionClaimIds,
+    outputPath: contractPath,
+    policyPath,
+    tolerance,
+  }));
+  const executionContractPath = path.join(
+    sourcePipeline.directories.protocol,
+    "execution-contract.json",
+  );
+  let assessmentUsage = null;
+  const replay = await replayRunToCap({
+    researchPath,
+    contractPath,
+    executionContractPath,
+    policyPath,
+    runDirectory: sourcePipeline.reproduction.bundle.directories.run,
+    capDirectory: directories.cap,
+    signingKeyPath,
+    processingBinding,
+    researchArtifactDigest,
+    scientificAssessor,
+    onAssessment: async assessment => { assessmentUsage = assessment?.usage ?? null; },
+    getPipelineSummary: async () => ({
+      schemaVersion: "1.0",
+      kind: "citeark.pipeline-summary",
+      pipelineId: sourcePipeline.state.pipelineId,
+      status: "completed",
+      phase: "shared-claim-projection",
+      createdAt: sourcePipeline.state.createdAt,
+      updatedAt: new Date().toISOString(),
+      stages: structuredClone(sourcePipeline.state.stages),
+      usage: mergeAgentUsage(assessmentUsage),
+      usageScope: "claim-projection",
+      agent: structuredClone(sourcePipeline.state.agent ?? {}),
+      computeDecision: structuredClone(sourcePipeline.computeDecision ?? {}),
+      sharedExecution: {
+        sourceContractDigest: sourcePipeline.contract.contractDigest,
+        projectedContractDigest: contract.contractDigest,
+        experimentId,
+      },
+    }),
+  });
+  const contentDigest = await capDirectoryContentDigest(directories.cap);
+  const archive = await packCap({
+    directory: directories.cap,
+    outputPath: path.join(
+      root,
+      `shared-${sha256Value({ claimId, experimentId }).slice(0, 16)}-${contentDigest.slice(7)}.cap`,
+    ),
+    reuseExisting: true,
+  });
+  return {
+    ...sourcePipeline,
+    directories,
+    archive,
+    contract,
+    policy,
+    replay,
+    sharedExecution: {
+      sourceContractDigest: sourcePipeline.contract.contractDigest,
+      claimId,
+      experimentId,
+    },
+  };
+}

package/src/pipeline/stage-checkpoint.mjs

@@ -0,0 +1,86 @@
+import { RecoveryStateError } from "./recovery-error.mjs";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { pathExists, readJson, sha256Value, writeJson } from "../util.mjs";
+
+// This is coordinator-private state, never an Agent input or a public CAP.
+// A stage becomes reusable only after its output and the matching identity
+// have been durably saved. A failed upload stops downstream work.
+export function createStageCheckpoint({
+  directory,
+  identity,
+  persist = async () => {},
+  progress = () => {},
+  enabled = true,
+}) {
+  const root = path.resolve(directory);
+  const identityDigest = `sha256:${sha256Value(identity)}`;
+  return async (stage, operation, revision = null) => {
+    if (!enabled) return operation();
+    if (!/^[a-z][a-z0-9_]*$/.test(stage))
+      throw new Error("Invalid recovery stage");
+    const suffix = revision ? `-${sha256Value(revision)}` : "";
+    const filename = path.join(root, "stage-results", `${stage}${suffix}.json`);
+    if (await pathExists(filename)) {
+      const saved = await readJson(filename);
+      if (saved.identityDigest !== identityDigest || saved.stage !== stage) {
+        throw new RecoveryStateError(`Recovery input identity changed at ${stage}`);
+      }
+      progress(`复用已完成阶段：${stage}`);
+      return relocateStageValue(saved.value, saved.root, root);
+    }
+    const value = await operation();
+    const durableValue = checkpointValue(value);
+    await mkdir(path.dirname(filename), { recursive: true });
+    await writeJson(filename, {
+      schemaVersion: "1.0",
+      stage,
+      root,
+      identityDigest,
+      value: durableValue,
+    });
+    await persist({ stage, status: "completed" });
+    return value;
+  };
+}
+
+export function relocateStageValue(value, previousRoot, root) {
+  if (typeof value === "string") {
+    return value === previousRoot
+      ? root
+      : value.startsWith(`${previousRoot}/`)
+        ? root + value.slice(previousRoot.length)
+        : value;
+  }
+  if (Array.isArray(value))
+    return value.map((item) => relocateStageValue(item, previousRoot, root));
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        relocateStageValue(item, previousRoot, root),
+      ]),
+    );
+  return value;
+}
+
+function checkpointValue(value) {
+  // Runtime credentials are reconstructed by the new worker. Do not serialize
+  // a runtime/provider client or the budget capability from a bundle.
+  return JSON.parse(
+    JSON.stringify(value ?? null, (key, item) => {
+      if (
+        new Set([
+          "runtimeAgent",
+          "paperBudget",
+          "apiKey",
+          "apiToken",
+          "accessToken",
+          "signingKeyPath",
+        ]).has(key)
+      )
+        return undefined;
+      return item;
+    }),
+  );
+}

package/src/pipeline/stage-recovery.mjs

@@ -0,0 +1,101 @@
+// Deferred optional preparation is complete for recovery purposes: the final
+// reproduction Agent owns the fallback and must not be routed back into cache
+// preparation when a later stage fails.
+const TERMINAL_STAGE_STATUSES = new Set(["completed", "deferred", "skipped"]);
+
+/**
+ * Derive the smallest safe restart boundary from durable pipeline state.
+ *
+ * This contract deliberately treats the scientific reproduction Agent as one
+ * autonomous stage. It may restore that Agent's complete workspace/session, or
+ * reuse its already validated result, but never decomposes the Agent's internal
+ * reasoning loop into controller-owned micro steps.
+ */
+export function pipelineStageResumePlan(state) {
+  const stages = normalizeStages(state?.stages);
+  if (!stages.length) return null;
+
+  const failedIndex = stages.findIndex((stage) => stage.status === "failed");
+  const runningIndex = stages.findIndex((stage) => stage.status === "running");
+  const phaseIndex = stages.findIndex((stage) => stage.id === state?.phase);
+  const candidates = [
+    firstIncompleteIndex(stages),
+    failedIndex,
+    runningIndex,
+    phaseIndex,
+  ].filter((index) => index >= 0);
+  const resumeIndex = candidates.length ? Math.min(...candidates) : -1;
+  if (resumeIndex < 0) return null;
+
+  const reproductionIndex = stages.findIndex((stage) => stage.id === "reproduction");
+  const reproductionCompleted = reproductionIndex >= 0
+    && stages[reproductionIndex].status === "completed";
+  const completedStages = stages
+    .slice(0, resumeIndex)
+    .filter((stage) => TERMINAL_STAGE_STATUSES.has(stage.status))
+    .map((stage) => stage.id);
+  const resumeStage = stages[resumeIndex].id;
+  const agentResumeMode = reproductionCompleted && resumeIndex > reproductionIndex
+    ? "reuse_completed_result"
+    : resumeStage === "reproduction"
+      ? "continue_autonomous_agent"
+      : "rerun_stage";
+
+  return {
+    schemaVersion: "1.0",
+    resumeStage,
+    lastCompletedStage: completedStages.at(-1) ?? null,
+    completedStages,
+    invalidatedStages: stages.slice(resumeIndex).map((stage) => stage.id),
+    agentResumeMode,
+    autonomyBoundary: "whole-agent-workload",
+  };
+}
+
+export function createPipelineRecoveryEnvelope({ state, reproduction, checkpoint } = {}) {
+  const resume = pipelineStageResumePlan(state);
+  if (!resume) return null;
+  const cloud = reproduction?.bundle?.state?.cloudExecution;
+  const selected = checkpoint ?? latestCloudCheckpoint(cloud?.jobs);
+  if (!selected) return { ...resume, checkpoint: null };
+  const reason = selected.checkpoint?.reason ?? selected.reason ?? null;
+  return {
+    ...resume,
+    // The durable coordinator result decides the boundary. An older remote
+    // checkpoint cannot turn a publication retry back into scientific work.
+    checkpoint: {
+      bucket: cloud?.stagingBucket ?? selected.bucket,
+      checkpointPrefix: selected.checkpointPrefix,
+      checkpointStatus: selected.checkpointStatus,
+      sequence: selected.checkpoint?.sequence ?? selected.sequence,
+      kind: selected.checkpoint?.kind ?? selected.kind,
+      reason,
+      createdAt: selected.checkpoint?.createdAt ?? selected.createdAt,
+    },
+  };
+}
+
+function latestCloudCheckpoint(jobs) {
+  if (!Array.isArray(jobs)) return null;
+  return [...jobs].reverse().find((candidate) =>
+    typeof candidate?.checkpointPrefix === "string"
+    && typeof candidate?.checkpoint?.sequence === "string",
+  ) ?? null;
+}
+
+function normalizeStages(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((stage) =>
+      stage
+      && typeof stage === "object"
+      && typeof stage.id === "string"
+      && typeof stage.status === "string",
+    )
+    .map((stage) => ({ id: stage.id, status: stage.status }));
+}
+
+function firstIncompleteIndex(stages) {
+  const index = stages.findIndex((stage) => !TERMINAL_STAGE_STATUSES.has(stage.status));
+  return index >= 0 ? index : -1;
+}