@citeark/agent 0.3.20

package/src/verification/integrity.mjs

@@ -0,0 +1,570 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+import { executionContractMeasurements } from "../contracts/execution-contract.mjs";
+import { agentPlansExecution } from "../contracts/execution-mode.mjs";
+import { loadAndVerifyRunnerAudit } from "../execution/runner-audit.mjs";
+import { pathExists, readJson, sha256File, sha256Value } from "../util.mjs";
+
+export async function checkExecutionIntegrity({
+  research,
+  contract,
+  runDirectory,
+  result,
+  metrics,
+  outputs,
+  sharedExecution = null,
+}) {
+  const checks = [];
+  const runPath = path.join(runDirectory, "run.json");
+  const run = (await pathExists(runPath)) ? await readJson(runPath) : null;
+  check(checks, "run_record_present", Boolean(run), "Out-of-sandbox run record exists");
+  const experiment = research.experiments.find((item) => item.versionId === contract.research.experimentVersionId);
+  const claim = research.claims.find((item) => item.versionId === contract.research.claimVersionId);
+  const executionStatus = result?.execution?.status ?? "unknown";
+  const scientificExecutionSucceeded = executionStatus === "succeeded";
+  const agentPlanned = agentPlansExecution(contract?.protocol);
+  check(checks, "claim_binding", Boolean(claim), "contract claimVersionId exists in research.json");
+  check(checks, "experiment_binding", Boolean(experiment), "contract experimentVersionId exists in research.json");
+  if (sharedExecution) {
+    if (sharedExecution.campaignTargetContractDigest) check(checks, "campaign_target_commitment",
+      sharedExecution.campaignTargetContractDigest === contract.contractDigest,
+      "The original shared execution committed to this target contract before execution");
+    const sourceMeasurementIds = new Set(sharedExecution.sourceMeasurementIds ?? []);
+    check(
+      checks,
+      "shared_execution_experiment_binding",
+      sharedExecution.experimentVersionId === contract.research.experimentVersionId,
+      "Shared execution and claim projection reference the same immutable experiment version",
+      sharedExecution,
+    );
+    check(
+      checks,
+      "shared_execution_measurement_scope",
+      (sharedExecution.projectedMeasurementIds ?? []).every((id) =>
+        sourceMeasurementIds.has(id)),
+      "Every projected claim measurement was assigned to the original shared execution",
+      sharedExecution,
+    );
+  }
+  check(checks, "contract_digest", metrics.contractDigest === contract.contractDigest, "metrics are bound to the contract digest");
+  check(checks, "output_registry_contract", outputs?.contractDigest === contract.contractDigest, "typed outputs are bound to the contract digest");
+  check(checks, "output_registry_run", outputs?.runId === run?.runId, "typed outputs are bound to the execution run");
+  check(checks, "execution_status_recognized", new Set(["succeeded", "failed", "partial"]).has(executionStatus), "Execution report uses a recognized status", { observed: executionStatus });
+  check(checks, "scientific_execution_succeeded", scientificExecutionSucceeded, "The scientific execution produced a successful outcome", { observed: executionStatus }, false);
+
+  const runnerAudit = await loadAndVerifyRunnerAudit(runDirectory);
+  const isolatedCapture = new Set([
+    "host-runner-outside-agent-mounts",
+    "gcp-batch-supervisor-separate-uid",
+    "autodl-pro-supervisor-separate-uid",
+  ]).has(runnerAudit.audit?.captureBoundary);
+  check(checks, "runner_audit_present", Boolean(runnerAudit.audit), "Runner-owned execution audit exists outside the Agent result envelope");
+  check(checks, "runner_audit_integrity", runnerAudit.issues.length === 0, "Runner audit digest and companion file hashes verify", { issues: runnerAudit.issues });
+  check(checks, "runner_capture_isolated", isolatedCapture, "The Agent could not write the runner audit directory while commands were captured", { captureBoundary: runnerAudit.audit?.captureBoundary ?? null });
+  check(checks, "runner_raw_stream_digest", Boolean(runnerAudit.audit?.rawStreams?.stdout?.sha256), "The runner retained the raw runtime stdout digest", { rawStreams: runnerAudit.audit?.rawStreams ?? null });
+  check(checks, "runner_command_records", runnerAudit.commandRecords.length > 0, "Runner-captured runtime tool-command records exist", { count: runnerAudit.commandRecords.length }, scientificExecutionSucceeded);
+  if (contract.executionPlan) {
+    check(checks, "research_plan_binding", metrics.executionPlanDigest === contract.executionPlan.digest,
+      "Parsed evidence identifies the exact research plan revision");
+    const captured = runnerAudit.commandRecords.some((record) =>
+      (record.stdout?.text ?? "").split("\n").some((line) => {
+        try {
+          const event = JSON.parse(line);
+          return event.event === "research_plan_execution"
+            && event.planDigest === contract.executionPlan.digest
+            && `sha256:${sha256Value(event.plan)}` === contract.executionPlan.digest;
+        } catch { return false; }
+      }));
+    check(checks, "research_plan_captured", captured,
+      "The runner captured the final plan bytes; the assessor must still verify their relationship to actual computation", {}, scientificExecutionSucceeded);
+  }
+
+  const contractMeasurements = executionContractMeasurements(contract);
+  const parsedMeasurements = Array.isArray(metrics.measurements)
+    ? metrics.measurements
+    : [{ ...metrics, measurementId: contractMeasurements[0]?.measurementId }];
+  for (const [index, binding] of contractMeasurements.entries()) {
+    const parsed = parsedMeasurements.find((item) => item.measurementId === binding.measurementId);
+    const label = `${index + 1}:${binding.measurementId}`;
+    check(checks, `measurement_record:${label}`, Boolean(parsed), "A parsed measurement record exists for every contract measurement");
+    if (!parsed) continue;
+    if (parsed.sourceEvidence) {
+      const evidencePath = path.join(runDirectory, "output", parsed.sourceEvidence.path);
+      const evidenceDigest = (await pathExists(evidencePath)) ? await sha256File(evidencePath) : null;
+      check(checks, `evidence_digest:${label}`, evidenceDigest === parsed.sourceEvidence.sha256, "Raw evidence hash matches metrics.json", { observed: evidenceDigest, expected: parsed.sourceEvidence.sha256 });
+    } else {
+      check(checks, `metric_source_absence_explained:${label}`, !scientificExecutionSucceeded && parsed.availability?.status === "unavailable", "A missing metric source is allowed only for an explicitly unsuccessful execution", { availability: parsed.availability ?? null });
+    }
+    if (parsed.primary) {
+      check(checks, `metric_binding:${label}`, parsed.primary.metric === binding.metric && parsed.primary.unit === binding.unit, "Parsed metric matches the contract");
+    } else {
+      check(checks, `metric_absence_explained:${label}`, !scientificExecutionSucceeded && parsed.availability?.status === "unavailable", "A missing primary metric is allowed only for an explicitly unsuccessful execution", { availability: parsed.availability ?? null });
+    }
+  }
+
+  for (const [index, output] of (outputs?.outputs ?? []).entries()) {
+    const label = `${index + 1}:${output.id}`;
+    const outputPath = path.join(runDirectory, "output", output.sourcePath);
+    const present = await pathExists(outputPath);
+    check(checks, `output_present:${label}`, present, "Declared scientific output exists as a regular runner file");
+    if (!present) continue;
+    const observedDigest = `sha256:${await sha256File(outputPath)}`;
+    check(checks, `output_digest:${label}`, observedDigest === output.digest, "Scientific output hash matches results/outputs.json", {
+      observed: observedDigest,
+      expected: output.digest,
+      mediaType: output.mediaType,
+      outputKind: output.kind,
+    });
+  }
+
+  const observedCommit = run?.repository?.commit ?? null;
+  check(checks, "repository_commit", observedCommit === contract.repository.commit, "Observed repository commit matches the contract-pinned value", { observed: observedCommit, expected: contract.repository.commit });
+  const scientificChangePolicy = evaluateScientificChangePolicy({ contract, experiment, result });
+  check(
+    checks,
+    "scientific_change_policy",
+    scientificChangePolicy.passed,
+    "Scientific-semantic changes are absent or limited to paths pre-declared by a CiteArk reconstruction contract",
+    scientificChangePolicy,
+  );
+
+  const patchPath = path.join(runDirectory, "execution", "repository.patch");
+  const patchPresent = await pathExists(patchPath);
+  const patch = patchPresent ? await readFile(patchPath, "utf8") : "";
+  const nonGitSnapshot = run?.repository?.sourceType === "pipeline-snapshot";
+  const changedTrackedPaths = [...patch.matchAll(/^diff --git a\/(.+?) b\//gm)].map((match) => match[1]);
+  const workspaceMutationPolicy = evaluateWorkspaceMutationPolicy({
+    experiment,
+    result,
+    allowScientificChanges: Boolean(contract.executionPlan),
+    changedPaths: changedTrackedPaths,
+  });
+  check(
+    checks,
+    "source_patch_accounted",
+    (patchPresent || nonGitSnapshot) &&
+      (patch.trim() === "" || workspaceMutationPolicy.passed),
+    "Git source patch collected; non-Git snapshots are covered by before/after file-tree records; source repairs must be declared by the Agent or pre-authorized by the contract",
+    {
+      patchSha256: patch ? `sha256:${sha256Value(patch)}` : null,
+      nonGitSnapshot,
+      changedTrackedPaths,
+      ...workspaceMutationPolicy,
+    },
+  );
+  for (const filename of ["invocation.json", "workspace-before.json", "workspace-after.json", "workspace-changes.json"]) {
+    check(checks, `execution_record:${filename}`, await pathExists(path.join(runDirectory, "execution", filename)), `Out-of-sandbox record exists: ${filename}`);
+  }
+  const changesPath = path.join(runDirectory, "execution", "workspace-changes.json");
+  let workspaceChanges = null;
+  if (await pathExists(changesPath)) {
+    workspaceChanges = await readJson(changesPath);
+    const changedPaths = [...(workspaceChanges.modified ?? []), ...(workspaceChanges.deleted ?? [])]
+      .map((item) => item.path);
+    const mutationPolicy = evaluateWorkspaceMutationPolicy({ experiment, result, changedPaths,
+      allowScientificChanges: Boolean(contract.executionPlan) });
+    check(
+      checks,
+      "workspace_mutations_allowed",
+      mutationPolicy.passed,
+      "Source modifications and deletions are declared as execution/environment repairs or pre-authorized by the scientific contract",
+      mutationPolicy,
+    );
+  }
+
+  const commands = runnerAudit.commandRecords
+    .map((record) => record?.command?.text)
+    .filter((command) => typeof command === "string" && command.length > 0);
+  const pinnedEntrypoint = await inspectPinnedEntrypointEvidence({
+    runDirectory,
+    entrypoint: experiment?.protocol?.entrypoint,
+    commandRecords: runnerAudit.commandRecords,
+    observedCommit,
+    expectedCommit: contract.repository.commit,
+    workspaceChanges,
+    scientificExecutionSucceeded,
+  });
+  for (const fragment of contract.protocol?.requiredCommandFragments ?? []) {
+    const evidence = protocolFragmentEvidence({
+      commands,
+      fragment,
+      pinnedEntrypoint: agentPlanned ? null : pinnedEntrypoint,
+    });
+    check(
+      checks,
+      `protocol_fragment:${fragment}`,
+      evidence.passed,
+      `Command anchor ${fragment} is a lexical review hint, not proof of scientific execution`,
+      { ...evidence.detail, evidentiaryRole: "advisory-only; assessor must trace actual computation" },
+      false,
+    );
+  }
+  for (const [index, measurement] of contractMeasurements.entries()) {
+    const evidenceDeclared = Array.isArray(result?.evidence) && result.evidence.some((item) => item?.path === measurement.parser.evidencePath);
+    check(checks, `parser_evidence_declared:${index + 1}:${measurement.measurementId}`, evidenceDeclared, "Agent result declares the raw evidence used by the parser", {}, scientificExecutionSucceeded);
+  }
+
+  const requiredChecks = checks.filter((item) => item.required !== false);
+  const status = requiredChecks.every((item) => item.status === "passed") ? "passed" : "failed";
+  const agentStatus = normalizeAgentStatus(run?.status);
+  const packagingRecovered = await pathExists(path.join(runDirectory, "output", "packaging-recovery.txt"));
+  return {
+    schemaVersion: "0.1",
+    contractDigest: contract.contractDigest,
+    status,
+    checks,
+    states: {
+      experimentStatus: result?.execution?.status ?? "unknown",
+      agentStatus,
+      packagingStatus: packagingRecovered ? "recovered" : result ? "completed" : "missing",
+      verificationStatus: "pending",
+      publicationStatus: "draft",
+      commandProvenance: runnerAudit.audit?.status === "complete" && isolatedCapture
+        ? "runner-captured"
+        : "degraded",
+    },
+    executionAudit: runnerAudit.audit ? {
+      auditDigest: runnerAudit.audit.auditDigest,
+      captureBoundary: runnerAudit.audit.captureBoundary,
+      commandRecordCount: runnerAudit.audit.commandRecordCount,
+    } : null,
+    ...(sharedExecution ? { sharedExecution } : {}),
+    checkedAt: run?.finishedAt ?? new Date().toISOString(),
+  };
+}
+
+export async function inspectPinnedEntrypointEvidence({
+  runDirectory,
+  entrypoint,
+  commandRecords,
+  observedCommit,
+  expectedCommit,
+  workspaceChanges,
+  scientificExecutionSucceeded,
+}) {
+  const normalizedEntrypoint = extractEntrypointPath(entrypoint);
+  const detail = {
+    eligible: false,
+    entrypoint: normalizedEntrypoint,
+    entrypointSha256: null,
+    invocationRecordIds: [],
+    reason: null,
+  };
+  if (!scientificExecutionSucceeded) return { ...detail, reason: "scientific execution did not succeed", sourceText: null };
+  if (!normalizedEntrypoint) return { ...detail, reason: "entrypoint is not a safe relative path", sourceText: null };
+  if (!observedCommit || observedCommit !== expectedCommit) {
+    return { ...detail, reason: "observed repository commit does not match the contract", sourceText: null };
+  }
+
+  const successfulInvocations = (Array.isArray(commandRecords) ? commandRecords : []).filter(
+    (record) => commandRecordSuccessfullyInvokesEntrypoint(record, normalizedEntrypoint),
+  );
+  detail.invocationRecordIds = successfulInvocations.map((record) => record.recordId).filter(Boolean);
+  if (!successfulInvocations.length) {
+    return { ...detail, reason: "runner did not capture a successful entrypoint invocation", sourceText: null };
+  }
+
+  const changedEntrypoint = [...(workspaceChanges?.modified ?? []), ...(workspaceChanges?.deleted ?? [])]
+    .some((item) => item?.path === normalizedEntrypoint);
+  if (changedEntrypoint) {
+    return { ...detail, reason: "entrypoint was modified or deleted during execution", sourceText: null };
+  }
+
+  const repositoryRoot = path.join(runDirectory, "workspace", "repository");
+  const entrypointPath = path.resolve(repositoryRoot, normalizedEntrypoint);
+  const rootPrefix = `${path.resolve(repositoryRoot)}${path.sep}`;
+  if (!entrypointPath.startsWith(rootPrefix)) {
+    return { ...detail, reason: "entrypoint resolves outside the repository", sourceText: null };
+  }
+  const [resolvedRoot, resolvedEntrypoint] = await Promise.all([
+    realpath(repositoryRoot).catch(() => null),
+    realpath(entrypointPath).catch(() => null),
+  ]);
+  if (!resolvedRoot || !resolvedEntrypoint || !resolvedEntrypoint.startsWith(`${resolvedRoot}${path.sep}`)) {
+    return { ...detail, reason: "entrypoint source is missing or escapes the repository", sourceText: null };
+  }
+  const stat = await lstat(resolvedEntrypoint).catch(() => null);
+  if (!stat?.isFile() || stat.size > 8 * 1024 * 1024) {
+    return { ...detail, reason: "entrypoint source is not a bounded regular file", sourceText: null };
+  }
+
+  const beforePath = path.join(runDirectory, "execution", "workspace-before.json");
+  const before = (await pathExists(beforePath)) ? await readJson(beforePath) : null;
+  const beforeEntry = before?.entries?.find((item) => item?.path === normalizedEntrypoint && item?.type === "file");
+  const entrypointSha256 = await sha256File(resolvedEntrypoint);
+  detail.entrypointSha256 = entrypointSha256;
+  if (!beforeEntry || beforeEntry.sha256 !== entrypointSha256) {
+    return { ...detail, reason: "entrypoint source does not match the runner-owned pre-execution snapshot", sourceText: null };
+  }
+
+  return {
+    ...detail,
+    eligible: true,
+    reason: null,
+    sourceText: await readFile(resolvedEntrypoint, "utf8"),
+  };
+}
+
+export function protocolFragmentEvidence({ commands, fragment, pinnedEntrypoint }) {
+  if (commandMatchesFragment(commands, fragment)) {
+    return {
+      passed: true,
+      detail: { provenance: "runner-captured-runtime-json-stream" },
+    };
+  }
+  if (pinnedEntrypoint?.eligible && pinnedEntrypoint.sourceText?.includes(fragment)) {
+    return {
+      passed: true,
+      detail: {
+        provenance: "pinned-entrypoint-source-plus-runner-invocation",
+        entrypoint: pinnedEntrypoint.entrypoint,
+        entrypointSha256: pinnedEntrypoint.entrypointSha256,
+        invocationRecordIds: pinnedEntrypoint.invocationRecordIds,
+      },
+    };
+  }
+  return {
+    passed: false,
+    detail: {
+      provenance: "unverified",
+      entrypoint: pinnedEntrypoint?.entrypoint ?? null,
+      entrypointSha256: pinnedEntrypoint?.entrypointSha256 ?? null,
+      entrypointEvidenceReason: pinnedEntrypoint?.reason ?? "no pinned entrypoint evidence is available",
+    },
+  };
+}
+
+export function evaluateScientificChangePolicy({ contract, experiment, result }) {
+  const scientificChanges = (Array.isArray(result?.codeChanges) ? result.codeChanges : [])
+    .filter((change) => change?.classification === "scientific");
+  const scientificChangePaths = [...new Set(scientificChanges
+    .map((change) => normalizeRelativePath(change?.path))
+    .filter(Boolean))];
+  const invalidScientificChangePaths = scientificChanges
+    .filter((change) => !normalizeRelativePath(change?.path))
+    .map((change) => typeof change?.path === "string" ? change.path : null);
+  const reconstructionAuthorized = contract?.repository?.implementationOrigin === "citeark_reconstruction"
+    && new Set(["exact", "faithful", "approximate", "proxy"]).has(contract?.reconstructionFidelity);
+  const entrypoint = extractEntrypointPath(experiment?.protocol?.entrypoint);
+  const allowedChangePaths = [...new Set(
+    (experiment?.protocol?.allowedChangePaths ?? []).map(normalizeRelativePath).filter(Boolean),
+  )];
+  const allowedScientificChangePaths = [...new Set([entrypoint, ...allowedChangePaths].filter(Boolean))];
+  const unauthorizedScientificChangePaths = contract.executionPlan ? [] : scientificChangePaths.filter(
+    (changedPath) => !reconstructionAuthorized
+      || !(
+        changePathMatchesEntrypoint(changedPath, entrypoint)
+        || allowedChangePaths.some((allowedPath) => pathAllowed(changedPath, allowedPath))
+      ),
+  );
+  return {
+    passed: invalidScientificChangePaths.length === 0 && unauthorizedScientificChangePaths.length === 0,
+    reconstructionAuthorized,
+    scientificChangePaths,
+    invalidScientificChangePaths,
+    allowedScientificChangePaths,
+    unauthorizedScientificChangePaths,
+  };
+}
+
+export function evaluateWorkspaceMutationPolicy({ experiment, result, changedPaths, allowScientificChanges = false }) {
+  const observedChangePaths = [...new Set(
+    (Array.isArray(changedPaths) ? changedPaths : [])
+      .map(normalizeWorkspaceChangePath)
+      .filter(Boolean),
+  )];
+  const invalidObservedChangePaths = (Array.isArray(changedPaths) ? changedPaths : [])
+    .filter((changedPath) => !normalizeWorkspaceChangePath(changedPath));
+  const allowedChangePaths = [...new Set(
+    (experiment?.protocol?.allowedChangePaths ?? [])
+      .map(normalizeWorkspaceChangePath)
+      .filter(Boolean),
+  )];
+  const declaredRepairPaths = [...new Set(
+    (Array.isArray(result?.codeChanges) ? result.codeChanges : [])
+      .filter((change) => new Set(allowScientificChanges ? ["environment", "execution", "scientific"] : ["environment", "execution"]).has(change?.classification))
+      .map((change) => normalizeWorkspaceChangePath(change?.path))
+      .filter(Boolean),
+  )];
+  const unaccountedChangePaths = observedChangePaths.filter((changedPath) =>
+    !declaredRepairPaths.includes(changedPath)
+    && !allowedChangePaths.some((allowedPath) => pathAllowed(changedPath, allowedPath)),
+  );
+  return {
+    passed: invalidObservedChangePaths.length === 0 && unaccountedChangePaths.length === 0,
+    observedChangePaths,
+    invalidObservedChangePaths,
+    declaredRepairPaths,
+    allowedChangePaths,
+    unaccountedChangePaths,
+  };
+}
+
+function changePathMatchesEntrypoint(changedPath, entrypoint) {
+  if (!changedPath || !entrypoint) return false;
+  return changedPath === entrypoint
+    || changedPath === `output/${entrypoint}`
+    || changedPath === `repository/${entrypoint}`;
+}
+
+/**
+ * Research plans historically used protocol.entrypoint for either a path or a
+ * full invocation. Integrity policy is path-based, so never compare a changed
+ * file with the entire command string.
+ */
+export function extractEntrypointPath(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const trimmed = value.trim();
+  if (!/[\s;&|<>]/.test(trimmed)) return normalizeEntrypointLogicalPath(stripShellQuotes(trimmed));
+  const script = shellWords(trimmed).find((token) =>
+    !token.startsWith("-")
+    && /\.(?:py|sh|js|mjs|cjs|rb|pl|jl|r)$/i.test(token),
+  );
+  return normalizeEntrypointLogicalPath(script);
+}
+
+export function commandMatchesFragment(commands, fragment) {
+  if (!Array.isArray(commands) || typeof fragment !== "string" || fragment.length === 0) return false;
+  const requiredTokens = anchorWords(fragment);
+  if (requiredTokens.length && commands.some((command) => {
+    if (typeof command !== "string") return false;
+    const tokens = anchorWords(command);
+    return tokens.some((_, index) => requiredTokens.every((token, offset) => tokens[index + offset] === token));
+  })) return true;
+
+  const required = fragment.match(/^bash\s+([^\s;&|]+)$/);
+  if (!required) return false;
+  const requiredScript = path.posix.normalize(required[1]);
+  const requiredDirectory = path.posix.dirname(requiredScript);
+  const requiredBasename = path.posix.basename(requiredScript);
+
+  return commands.some((command) => {
+    if (typeof command !== "string") return false;
+    let workingDirectory = null;
+    for (const segment of command.split(/&&|;/).map((item) => item.trim())) {
+      const cd = segment.match(/^cd\s+([^\s]+)$/);
+      if (cd) {
+        workingDirectory = stripShellQuotes(cd[1]);
+        continue;
+      }
+      const bash = segment.match(/^bash\s+([^\s]+)(?:\s|$)/);
+      if (!bash || !workingDirectory) continue;
+      const invokedScript = stripShellQuotes(bash[1]);
+      if (path.posix.basename(invokedScript) !== requiredBasename) continue;
+      const resolvedDirectory = path.posix.dirname(path.posix.resolve(workingDirectory, invokedScript));
+      if (resolvedDirectory === requiredDirectory || resolvedDirectory.endsWith(`/${requiredDirectory}`)) return true;
+    }
+    return false;
+  });
+}
+
+// Used only for advisory matching, never to authenticate execution.
+function anchorWords(value) {
+  const words = [];
+  let word = "", quote = null;
+  const flush = () => {
+    if (word) words.push(...(word.startsWith("--") && word.includes("=")
+      ? [word.slice(0, word.indexOf("=")), word.slice(word.indexOf("=") + 1)] : [word]));
+    word = "";
+  };
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index];
+    if (quote) {
+      if (char === quote) quote = null;
+      else word += char;
+    } else if (char === "#" && !word) {
+      while (index < value.length && value[index] !== "\n") index++;
+      flush();
+    } else if (char === "'" || char === '"') quote = char;
+    else if (/\s/.test(char)) flush();
+    else word += char;
+  }
+  flush();
+  return words;
+}
+
+export function commandInvokesEntrypoint(command, entrypoint) {
+  const normalizedEntrypoint = normalizeRelativePath(entrypoint);
+  if (typeof command !== "string" || !normalizedEntrypoint) return false;
+  const interpreters = new Set(["bash", "sh", "dash", "zsh", "python", "python3", "perl", "ruby", "node"]);
+  for (const segment of command.split(/&&|\|\||;|\|/).map((item) => item.trim()).filter(Boolean)) {
+    const tokens = shellWords(segment);
+    while (tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0])) tokens.shift();
+    if (!tokens.length) continue;
+    if (tokenMatchesEntrypoint(tokens[0], normalizedEntrypoint)) return true;
+    const executable = path.posix.basename(tokens[0]);
+    if (!interpreters.has(executable)) continue;
+    const script = tokens.slice(1).find((token) => !token.startsWith("-"));
+    if (script && tokenMatchesEntrypoint(script, normalizedEntrypoint)) return true;
+  }
+  return false;
+}
+
+function commandRecordSuccessfullyInvokesEntrypoint(record, entrypoint) {
+  const command = record?.command?.text;
+  const completed = record?.exitCode === 0 && Boolean(record?.finishedAt);
+  return completed && commandInvokesEntrypoint(command, entrypoint);
+}
+
+function shellWords(value) {
+  const words = [];
+  for (const match of value.matchAll(/"([^"]*)"|'([^']*)'|([^\s<>]+)/g)) {
+    words.push(match[1] ?? match[2] ?? match[3]);
+  }
+  return words;
+}
+
+function tokenMatchesEntrypoint(token, entrypoint) {
+  const normalizedToken = path.posix.normalize(stripShellQuotes(token).replaceAll("\\", "/"));
+  if (normalizedToken === entrypoint || normalizedToken === `./${entrypoint}`) return true;
+  return normalizedToken.startsWith("/") && (
+    normalizedToken.endsWith(`/repository/${entrypoint}`)
+    || normalizedToken === `/job/output/${entrypoint}`
+  );
+}
+
+function stripShellQuotes(value) {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) return value.slice(1, -1);
+  return value;
+}
+
+function normalizeRelativePath(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const normalized = path.posix.normalize(value.trim().replaceAll("\\", "/"));
+  if (normalized === "." || normalized.startsWith("/") || normalized === ".." || normalized.startsWith("../")) return null;
+  return normalized;
+}
+
+function normalizeWorkspaceChangePath(value) {
+  const normalized = normalizeRelativePath(value);
+  if (!normalized) return null;
+  for (const prefix of ["workspace/repository/", "repository/"]) {
+    if (normalized.startsWith(prefix)) return normalizeRelativePath(normalized.slice(prefix.length));
+  }
+  return normalized;
+}
+
+function normalizeEntrypointLogicalPath(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const normalized = path.posix.normalize(value.trim().replaceAll("\\", "/"));
+  for (const prefix of ["/job/workspace/repository/", "/job/output/"]) {
+    if (normalized.startsWith(prefix)) return normalizeRelativePath(normalized.slice(prefix.length));
+  }
+  return normalizeRelativePath(normalized);
+}
+
+function pathAllowed(changedPath, allowedPath) {
+  return changedPath === allowedPath || changedPath.startsWith(`${allowedPath}/`);
+}
+
+function check(output, name, passed, description, detail = {}, required = true) {
+  output.push({ name, status: passed ? "passed" : "failed", required, description, ...detail });
+}
+
+function normalizeAgentStatus(status) {
+  if (status === "timed_out") return "timed_out";
+  if (status === "completed") return "completed";
+  if (status === "invalid_result") return "failed";
+  return status ?? "unknown";
+}

package/src/verification/tolerance.mjs

@@ -0,0 +1,32 @@
+import { CiteArkError } from "../util.mjs";
+
+const UNIT_DEFAULTS = new Map([
+  ["percentage_points", 0.2],
+  ["fraction", 0.002],
+]);
+
+export function resolveVerificationTolerance({ unit, tolerance }) {
+  if (tolerance !== undefined && tolerance !== null && String(tolerance).trim() !== "") {
+    const numeric = Number(tolerance);
+    if (!Number.isFinite(numeric) || numeric < 0) throw new CiteArkError("tolerance 必须是非负数");
+    return {
+      value: numeric,
+      source: { kind: "explicit", unit },
+    };
+  }
+  const unitDefault = UNIT_DEFAULTS.get(unit);
+  if (unitDefault === undefined) {
+    return {
+      value: 0,
+      source: {
+        kind: "unconfigured",
+        unit,
+        reason: `No safe default tolerance exists for unit ${unit}`,
+      },
+    };
+  }
+  return {
+    value: unitDefault,
+    source: { kind: "unit-default", unit },
+  };
+}

package/src/workloads/cpu-research-preparation.mjs

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { readAgentInstructions, updateRunState } from "../job.mjs";
+import { resolveResearchPlan } from "../reproduction/plan.mjs";
+import { readAgentUsage } from "../telemetry/usage.mjs";
+import { CiteArkError, readJson } from "../util.mjs";
+import { createAutonomousReproductionWorkload } from "./reproduction.mjs";
+import { defineAgentWorkload } from "./definition.mjs";
+
+const prompt = `Continue the same research workspace on CPU before requesting the allocated GPU. Read the fixed paper (Markdown first when available), the initial inventory, current research-plan.json, progress and any CPU handoff in output/result.json. input/compute-decision.json describes this phase's actual CPU allocation; the input task retains the scientific resource ceiling. The initial interpretation is provisional: reread sources and correct the plan as needed. Obtain the actual public inputs, resume downloads, install task-local dependencies and prepare the executable scripts. Use CPU import/loading checks where useful; a CUDA-only check belongs on GPU and need not block this handoff. Do not run the expensive scientific workload here. Do not treat a stale compiler asset checklist as exhaustive or authoritative.
+Save the current plan and progress under /job/output and working code under /job/workspace/repository. Put downloaded model weights and datasets under /job/assets, package/download caches under /job/runtime-cache, and dependencies under /job/runtime-venv. These directories survive machine transitions. Repository changes are transferred through a bounded patch: untracked files larger than 8 MiB are excluded, so repository/artifacts is NOT a durable location for weights or datasets. If existing inputs are there, move or copy the verified bytes into /job/assets and update the loader to use that location before declaring ready. Verify the actual file and its source identity at the retained location; a manifest or successful probe against a file that will be excluded does not establish a ready handoff. Retain source-grounded reasons, asset identities, unresolved GPU-specific checks and the concrete next command. No repeated inventory extraction or detailed manifest is required. Write /job/output/cpu-preparation.json as {"schemaVersion":"1.0","status":"ready","summary":"What is prepared and what the GPU must check next"}. If no justified GPU experiment remains possible within the authorized scope and resources, use status "blocked" and explain the observed constraint. This declaration is a handoff, not proof of feasibility or scientific support. Cumulative time and monetary budgets continue across machines; never reset them.`;
+
+/** One research actor moves machines with its complete workspace and session. */
+export function createCpuResearchPreparationWorkload({ runtimeBudgetMinutes } = {}) {
+  const actor = createAutonomousReproductionWorkload();
+  return defineAgentWorkload({
+    ...actor,
+    workload: "research-preparation",
+    runtimeBudgetMinutes,
+    validateScientificComputeDecision: false,
+    completionRelativePath: "output/cpu-preparation.json",
+    completionHasEvidence: false,
+    completionSuccessJq: '.schemaVersion == "1.0" and (.status == "ready" or .status == "blocked")',
+    preserveRebuildableCache: true,
+    finalCheckpointKind: "full",
+    finalCheckpointReason: "research-preparation",
+    recoverFinalMessage: false,
+    recover: undefined,
+    instructions: (bundle) => readAgentInstructions(bundle.runtimeTask),
+    prompt: () => prompt,
+    resumePrompt: () => `Resume existing CPU preparation. Inspect saved processes, outputs and progress before doing anything again.\n${prompt}`,
+    async validate({ bundle, completionPath }) {
+      try {
+        const result = await readJson(completionPath);
+        const issues = [];
+        if (result.schemaVersion !== "1.0" || !["ready", "blocked"].includes(result.status)
+          || typeof result.summary !== "string" || !result.summary.trim()) issues.push("CPU preparation needs a status and concrete handoff summary");
+        await resolveResearchPlan(bundle.runtimeTask, bundle.directories.output);
+        return { result, issues, protocolVerification: null };
+      } catch (error) { return { result: null, issues: [error.message], protocolVerification: null }; }
+    },
+    isSucceeded: (result, issues) => issues.length === 0 && ["ready", "blocked"].includes(result?.status),
+    async finalize({ bundle, validation, attempts, timedOut, cloudExecution, checkpoint }) {
+      const usage = await readAgentUsage(path.join(bundle.directories.execution, "trace.jsonl"), {
+        runtimeHome: bundle.directories.runtimeHome, model: bundle.runtimeAgent.model,
+      });
+      await updateRunState(bundle, { status: validation.issues.length || timedOut ? "invalid_result" : "completed",
+        finishedAt: new Date().toISOString(), usage, attempts, cloudExecution, preparation: validation.result });
+      if (validation.issues.length || timedOut || checkpoint?.kind !== "full") {
+        throw new CiteArkError(`CPU 研究准备尚无完整交接：${validation.issues.join("；") || "缺少完整检查点或时间已耗尽"}`, {
+          failureCode: "research_preparation.handoff_incomplete", retryable: false,
+        });
+      }
+      return { bundle, checkpoint, preparation: validation.result, preparationMode: "research-workspace", cacheHit: false };
+    },
+  });
+}