owlrunkit 0.19.1 → 0.20.0

package/scripts/runkit-contract/snapshot.mjs

@@ -8,6 +8,7 @@ import {
 } from "node:fs";
 import path from "node:path";
 
+import { validateReplayableEvidence } from "./acceptance-evidence.mjs";
 import { canonicalSourceFingerprint } from "./source-fingerprint.mjs";
 import {
   assertAllowedKeys,
@@ -185,21 +186,140 @@ function validateRequest(request) {
   if (!context.valid) throw new Error(`Snapshot verification context is invalid: ${context.issues.join("; ")}`);
 }
 
-export function verifySnapshotEvidence({ workspaceRoot, runId, snapshot }) {
+function exactKeys(value, label, keys, { optional = [] } = {}) {
+  assertAllowedKeys(value, label, [...keys, ...optional]);
+  if (!isRecord(value) || keys.some(key => !Object.hasOwn(value, key))) {
+    throw new Error(`${label} is missing required fields.`);
+  }
+}
+
+function validRepositoryState(state, label) {
+  try {
+    exactKeys(state, label, [
+      "head",
+      "statusMode",
+      "statusSha256",
+      "statusByteCount",
+      "statusEntryCount",
+      "selectedFiles",
+      "manifestFingerprint",
+    ]);
+    const files = normalizedFileMap(state.selectedFiles);
+    return typeof state.head === "string"
+      && state.head.length > 0
+      && state.statusMode === STATUS_MODE
+      && /^[a-f0-9]{64}$/u.test(state.statusSha256)
+      && Number.isSafeInteger(state.statusByteCount)
+      && state.statusByteCount >= 0
+      && Number.isSafeInteger(state.statusEntryCount)
+      && state.statusEntryCount >= 0
+      && files !== null
+      && canonicalSourceFingerprint(files) === state.manifestFingerprint;
+  } catch {
+    return false;
+  }
+}
+
+function snapshotContractIssues(snapshot) {
   const issues = [];
-  if (!isRecord(snapshot) || snapshot.schemaVersion !== "OwlCodaRunKitSnapshotV1") {
-    return { valid: false, issues: ["Unsupported snapshot schemaVersion."] };
+  try {
+    exactKeys(snapshot, "Snapshot", [
+      "schemaVersion",
+      "runId",
+      "snapshotId",
+      "status",
+      "mode",
+      "targetRoot",
+      "verificationContextFingerprint",
+      "repositoryBefore",
+      "repositoryAfter",
+      "command",
+      "authorizationGranted",
+    ], { optional: ["visual"] });
+    exactKeys(snapshot.command, "Snapshot command", [
+      "startedAt",
+      "endedAt",
+      "durationMs",
+      "exitCode",
+      "stdoutPath",
+      "stdoutSha256",
+      "stdoutLineCount",
+      "stderrPath",
+      "stderrSha256",
+      "stderrLineCount",
+      "evidence",
+    ]);
+  } catch (error) {
+    return [error instanceof Error ? error.message : String(error)];
+  }
+  if (
+    snapshot.schemaVersion !== "OwlCodaRunKitSnapshotV1"
+    || typeof snapshot.runId !== "string"
+    || snapshot.runId.length === 0
+    || typeof snapshot.snapshotId !== "string"
+    || snapshot.snapshotId.length === 0
+    || !new Set(["project", "foreign_readonly"]).has(snapshot.mode)
+    || typeof snapshot.targetRoot !== "string"
+    || snapshot.targetRoot.length === 0
+    || !/^[a-f0-9]{64}$/u.test(snapshot.verificationContextFingerprint)
+    || snapshot.authorizationGranted !== false
+    || !validRepositoryState(snapshot.repositoryBefore, "repositoryBefore")
+    || !validRepositoryState(snapshot.repositoryAfter, "repositoryAfter")
+    || typeof snapshot.command.startedAt !== "string"
+    || typeof snapshot.command.endedAt !== "string"
+    || !Number.isSafeInteger(snapshot.command.durationMs)
+    || snapshot.command.durationMs < 0
+    || !Number.isInteger(snapshot.command.exitCode)
+    || typeof snapshot.command.stdoutPath !== "string"
+    || typeof snapshot.command.stderrPath !== "string"
+    || !/^[a-f0-9]{64}$/u.test(snapshot.command.stdoutSha256)
+    || !/^[a-f0-9]{64}$/u.test(snapshot.command.stderrSha256)
+    || !Number.isSafeInteger(snapshot.command.stdoutLineCount)
+    || snapshot.command.stdoutLineCount < 0
+    || !Number.isSafeInteger(snapshot.command.stderrLineCount)
+    || snapshot.command.stderrLineCount < 0
+  ) {
+    issues.push("Snapshot contract is invalid.");
   }
+  const evidence = validateReplayableEvidence(snapshot.command.evidence);
+  if (!evidence.valid) issues.push(...evidence.issues);
+  const stable = stableTarget(snapshot.repositoryBefore, snapshot.repositoryAfter);
+  const expectedStatus = !stable
+    ? "invalidated_by_target_write"
+    : snapshot.command.exitCode === 0
+      ? "snapshot_passed"
+      : "snapshot_failed";
+  if (snapshot.status !== expectedStatus) {
+    issues.push("Snapshot status does not match its command and repository state.");
+  }
+  return issues;
+}
+
+export function verifySnapshotEvidence({
+  workspaceRoot,
+  runId,
+  snapshot,
+  requirePassed = true,
+}) {
+  const issues = [];
+  issues.push(...snapshotContractIssues(snapshot));
+  if (issues.length > 0) return { valid: false, issues };
   if (snapshot.runId !== runId) issues.push("Snapshot runId does not match the execution.");
-  if (snapshot.status !== "snapshot_passed") issues.push("Snapshot did not pass.");
+  if (requirePassed && snapshot.status !== "snapshot_passed") {
+    issues.push("Snapshot did not pass.");
+  }
   for (const [label, relativePath, expected] of [
     ["stdout", snapshot.command?.stdoutPath, snapshot.command?.stdoutSha256],
     ["stderr", snapshot.command?.stderrPath, snapshot.command?.stderrSha256],
   ]) {
     try {
       const absolutePath = resolveWithinRoot(workspaceRoot, relativePath, `${label} evidence path`);
-      const actual = sha256(readFileSync(absolutePath));
+      const bytes = readFileSync(absolutePath);
+      const actual = sha256(bytes);
       if (actual !== expected) issues.push(`${label} evidence hash mismatch.`);
+      if (lineCount(bytes) !== snapshot.command[`${label}LineCount`]) {
+        issues.push(`${label} evidence line count mismatch.`);
+      }
     } catch (error) {
       issues.push(error instanceof Error ? error.message : String(error));
     }

package/scripts/runkit-contract/source-candidate.mjs

@@ -28,10 +28,15 @@ import {
   relativeToWorkspace,
   resolveExistingArtifact,
   safeIdentifier,
+  safeRelativePath,
   sha256,
   writeJsonAtomically,
   writeJsonExclusiveAtomically,
 } from "./provenance-common.mjs";
+
+export const SOURCE_CANDIDATE_V2_MAX_BYTES = 64 * 1024 * 1024;
+export const SOURCE_CANDIDATE_V2_MAX_NODES = 2_000_000;
+import { readWorkspaceJsonBounded } from "./onboarding-doctor.mjs";
 import { verifyDeliveryPacket } from "./source-fingerprint.mjs";
 
 function canonicalJson(value) {
@@ -51,6 +56,18 @@ function candidateHash(value) {
   return `sha256:${sha256(canonicalJson(value))}`;
 }
 
+function hasExactKeys(value, keys) {
+  return Boolean(value)
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && canonicalJson(Object.keys(value).sort()) === canonicalJson([...keys].sort());
+}
+
+function validIdentifier(value) {
+  return typeof value === "string"
+    && /^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value);
+}
+
 function repositoryActionsFalse() {
   return {
     worktreeCreated: false,
@@ -281,15 +298,56 @@ function sourceManifestV2({ workspaceRoot, ownedPaths }) {
   };
 }
 
-function freezePayloadV1({
+function sourceCandidateNodeCount(value) {
+  let count = 0;
+  const pending = [value];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    count += 1;
+    if (Array.isArray(current)) {
+      pending.push(...current);
+    } else if (current !== null && typeof current === "object") {
+      pending.push(...Object.values(current));
+    }
+  }
+  return count;
+}
+
+export function validateSourceCandidateDocumentBoundsV2(value, {
+  maxBytes = SOURCE_CANDIDATE_V2_MAX_BYTES,
+  maxNodes = SOURCE_CANDIDATE_V2_MAX_NODES,
+} = {}) {
+  const bytes = Buffer.byteLength(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+  const nodes = sourceCandidateNodeCount(value);
+  return {
+    valid: bytes <= maxBytes && nodes <= maxNodes,
+    bytes,
+    nodes,
+    maxBytes,
+    maxNodes,
+  };
+}
+
+function assertSourceCandidateDocumentBoundsV2(value) {
+  const result = validateSourceCandidateDocumentBoundsV2(value);
+  if (!result.valid) {
+    throw new Error(
+      "SourceCandidateV2 exceeds its supported serialized size or JSON node limit.",
+    );
+  }
+  return result;
+}
+
+function planPayloadV1({
   workspaceRoot,
   candidateRoot,
   candidateId,
   manifest,
 }) {
   const payloadRoot = path.join(candidateRoot, `${candidateId}.payload`);
-  mkdirSync(payloadRoot);
-  mkdirSync(path.join(payloadRoot, "sha256"));
+  if (existsSync(payloadRoot)) {
+    throw new Error(`source candidate payload already exists: ${candidateId}`);
+  }
   const payloadRootRelative = relativeToWorkspace(workspaceRoot, payloadRoot);
   const entries = [];
   const blobs = new Map();
@@ -308,13 +366,10 @@ function freezePayloadV1({
     }
     const payloadPath = path.join(payloadRoot, "sha256", digest);
     if (!blobs.has(digest)) {
-      writeFileSync(payloadPath, bytes, { flag: "wx", mode: 0o600 });
-      blobs.set(digest, bytes.length);
-    } else if (
-      lstatSync(payloadPath).isSymbolicLink()
-      || sha256(readFileSync(payloadPath)) !== digest
-    ) {
-      throw new Error(`Source payload blob drifted during freeze: ${digest}`);
+      blobs.set(digest, {
+        sourcePath,
+        sizeBytes: bytes.length,
+      });
     }
     entries.push({
       path: manifestEntry.path,
@@ -329,15 +384,46 @@ function freezePayloadV1({
     storage: "create_only_content_addressed_sha256",
     root: payloadRootRelative,
     blobCount: blobs.size,
-    totalBytes: [...blobs.values()].reduce((total, size) => total + size, 0),
+    totalBytes: [...blobs.values()]
+      .reduce((total, row) => total + row.sizeBytes, 0),
     entries,
   };
   return {
-    ...body,
-    sha256: candidateHash(body),
+    payload: {
+      ...body,
+      sha256: candidateHash(body),
+    },
+    blobs,
+    payloadRoot,
   };
 }
 
+function persistPayloadPlanV1({ candidateRoot, plan }) {
+  if (!existsSync(candidateRoot)) mkdirSync(candidateRoot);
+  const candidateRootStat = lstatSync(candidateRoot);
+  if (
+    candidateRootStat.isSymbolicLink()
+    || !candidateRootStat.isDirectory()
+    || realpathSync(candidateRoot) !== path.resolve(candidateRoot)
+  ) {
+    throw new Error("Source candidate directory must be a regular directory.");
+  }
+  mkdirSync(plan.payloadRoot);
+  const blobRoot = path.join(plan.payloadRoot, "sha256");
+  mkdirSync(blobRoot);
+  for (const [digest, row] of plan.blobs) {
+    const bytes = readFileSync(row.sourcePath);
+    if (bytes.length !== row.sizeBytes || sha256(bytes) !== digest) {
+      throw new Error(`Source changed while persisting payload: ${digest}`);
+    }
+    writeFileSync(path.join(blobRoot, digest), bytes, {
+      flag: "wx",
+      mode: 0o600,
+    });
+  }
+  return plan.payload;
+}
+
 function payloadContractIssues({
   workspaceRoot,
   candidatePath,
@@ -354,7 +440,16 @@ function payloadContractIssues({
     (entry) => entry.operation !== "deleted",
   );
   if (
-    payload?.schemaVersion !== "OwlCodaRunKitSourcePayloadV1"
+    !hasExactKeys(payload, [
+      "schemaVersion",
+      "storage",
+      "root",
+      "blobCount",
+      "totalBytes",
+      "entries",
+      "sha256",
+    ])
+    || payload?.schemaVersion !== "OwlCodaRunKitSourcePayloadV1"
     || payload.storage !== "create_only_content_addressed_sha256"
     || payload.root !== expectedRoot
     || !Number.isInteger(payload.blobCount)
@@ -376,7 +471,14 @@ function payloadContractIssues({
   for (const entry of payload.entries) {
     const manifestEntry = expectedByPath.get(entry?.path);
     if (
-      !manifestEntry
+      !hasExactKeys(entry, [
+        "path",
+        "payloadPath",
+        "sha256",
+        "sizeBytes",
+        "mode",
+      ])
+      || !manifestEntry
       || seenPaths.has(entry.path)
       || entry.sha256 !== manifestEntry.sha256
       || !Number.isInteger(entry.sizeBytes)
@@ -438,7 +540,14 @@ function activeLease({ workspaceRoot, executionRoot, workItemId }) {
 
 function manifestContractValid(manifest) {
   if (
-    manifest?.schemaVersion !== "OwlCodaRunKitDirtySourceManifestV2"
+    !hasExactKeys(manifest, [
+      "schemaVersion",
+      "statusMode",
+      "ownedPaths",
+      "entries",
+      "sha256",
+    ])
+    || manifest?.schemaVersion !== "OwlCodaRunKitDirtySourceManifestV2"
     || manifest.statusMode !== "porcelain-v1-z-untracked-all-runkit-excluded"
     || !Array.isArray(manifest.ownedPaths)
     || manifest.ownedPaths.length === 0
@@ -450,8 +559,14 @@ function manifestContractValid(manifest) {
     return false;
   }
   for (const entry of manifest.entries) {
+    const expectedEntryKeys = entry?.operation === "renamed"
+      ? ["operation", "status", "path", "previousPath", "sha256"]
+      : entry?.operation === "deleted"
+        ? ["operation", "status", "path"]
+        : ["operation", "status", "path", "sha256"];
     if (
       !entry
+      || !hasExactKeys(entry, expectedEntryKeys)
       || !["added", "deleted", "modified", "renamed"].includes(entry.operation)
       || typeof entry.status !== "string"
       || entry.status.length !== 2
@@ -513,18 +628,39 @@ function repositoryActionsAreFalse(actions) {
 function candidateV2ContractIssues(candidate) {
   const { candidateSha256, ...body } = candidate ?? {};
   if (
-    candidate?.schemaVersion !== "OwlCodaRunKitSourceCandidateV2"
+    !hasExactKeys(candidate, [
+      "schemaVersion",
+      "runId",
+      "candidateId",
+      "status",
+      "sourceMode",
+      "baseline",
+      "sourceManifest",
+      "sourceFingerprint",
+      "payload",
+      "discovery",
+      "repositoryActions",
+      "authorizationGranted",
+      "candidateSha256",
+    ])
+    || candidate?.schemaVersion !== "OwlCodaRunKitSourceCandidateV2"
     || candidate.status !== "frozen"
     || candidate.sourceMode !== "dirty_worktree_exact_manifest_v2"
     || candidate.authorizationGranted !== false
-    || typeof candidateSha256 !== "string"
+    || !/^sha256:[a-f0-9]{64}$/u.test(candidateSha256)
     || candidateSha256 !== candidateHash(body)
-    || typeof candidate.runId !== "string"
-    || typeof candidate.candidateId !== "string"
-    || typeof candidate.baseline?.branch !== "string"
-    || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(candidate.baseline?.head)
-    || typeof candidate.discovery?.fromLease !== "string"
-    || typeof candidate.discovery?.leasePath !== "string"
+    || !validIdentifier(candidate.runId)
+    || !validIdentifier(candidate.candidateId)
+    || !hasExactKeys(candidate.baseline, ["branch", "head"])
+    || typeof candidate.baseline.branch !== "string"
+    || candidate.baseline.branch.length === 0
+    || !/^[a-f0-9]{40}$/u.test(candidate.baseline.head)
+    || !hasExactKeys(candidate.sourceFingerprint, ["sha256"])
+    || !/^[a-f0-9]{64}$/u.test(candidate.sourceFingerprint.sha256)
+    || !hasExactKeys(candidate.discovery, ["fromLease", "leasePath"])
+    || !validIdentifier(candidate.discovery.fromLease)
+    || typeof candidate.discovery.leasePath !== "string"
+    || candidate.discovery.leasePath.length === 0
     || !repositoryActionsAreFalse(candidate.repositoryActions)
     || !manifestContractValid(candidate.sourceManifest)
     || candidate.sourceFingerprint?.sha256
@@ -643,13 +779,14 @@ export function freezeSourceCandidateWithinControlTransactionV2({
   const { executionRoot, pinGate } = loadActiveExecution(root, runId);
   if (pinGate.status !== "valid") return { ...pinGate, authorizationGranted: false };
   const candidateRoot = path.join(executionRoot, "source-candidates");
-  if (!existsSync(candidateRoot)) mkdirSync(candidateRoot);
-  const candidateRootStat = lstatSync(candidateRoot);
-  if (candidateRootStat.isSymbolicLink() || !candidateRootStat.isDirectory()) {
-    throw new Error("Source candidate directory must be a regular directory.");
-  }
-  if (!within(realpathSync(executionRoot), realpathSync(candidateRoot))) {
-    throw new Error("Source candidate directory escapes its execution root.");
+  if (existsSync(candidateRoot)) {
+    const candidateRootStat = lstatSync(candidateRoot);
+    if (candidateRootStat.isSymbolicLink() || !candidateRootStat.isDirectory()) {
+      throw new Error("Source candidate directory must be a regular directory.");
+    }
+    if (!within(realpathSync(executionRoot), realpathSync(candidateRoot))) {
+      throw new Error("Source candidate directory escapes its execution root.");
+    }
   }
   const candidatePath = path.join(candidateRoot, `${candidateId}.json`);
   if (existsSync(candidatePath)) {
@@ -665,12 +802,43 @@ export function freezeSourceCandidateWithinControlTransactionV2({
     workspaceRoot: root,
     ownedPaths: lease.ownedPaths,
   });
-  const payload = freezePayloadV1({
+  const payloadPlan = planPayloadV1({
     workspaceRoot: root,
     candidateRoot,
     candidateId,
     manifest: statusBefore,
   });
+  const buildCandidate = ({ baseline, sourceManifest, payload }) => {
+    const body = {
+      schemaVersion: "OwlCodaRunKitSourceCandidateV2",
+      runId,
+      candidateId,
+      status: "frozen",
+      sourceMode: "dirty_worktree_exact_manifest_v2",
+      baseline,
+      sourceManifest,
+      sourceFingerprint: {
+        sha256: sourceManifest.sha256.slice("sha256:".length),
+      },
+      payload,
+      discovery: {
+        fromLease: workItemId,
+        leasePath: lease.leaseRelativePath,
+      },
+      repositoryActions: repositoryActionsFalse(),
+      authorizationGranted: false,
+    };
+    return {
+      ...body,
+      candidateSha256: candidateHash(body),
+    };
+  };
+  assertSourceCandidateDocumentBoundsV2(buildCandidate({
+    baseline: baselineBefore,
+    sourceManifest: statusBefore,
+    payload: payloadPlan.payload,
+  }));
+  const payload = persistPayloadPlanV1({ candidateRoot, plan: payloadPlan });
   const statusAfter = sourceManifestV2({
     workspaceRoot: root,
     ownedPaths: lease.ownedPaths,
@@ -682,29 +850,12 @@ export function freezeSourceCandidateWithinControlTransactionV2({
   ) {
     throw new Error("Owned workspace source changed during candidate freeze.");
   }
-  const body = {
-    schemaVersion: "OwlCodaRunKitSourceCandidateV2",
-    runId,
-    candidateId,
-    status: "frozen",
-    sourceMode: "dirty_worktree_exact_manifest_v2",
+  const candidate = buildCandidate({
     baseline: baselineAfter,
     sourceManifest: statusAfter,
-    sourceFingerprint: {
-      sha256: statusAfter.sha256.slice("sha256:".length),
-    },
     payload,
-    discovery: {
-      fromLease: workItemId,
-      leasePath: lease.leaseRelativePath,
-    },
-    repositoryActions: repositoryActionsFalse(),
-    authorizationGranted: false,
-  };
-  const candidate = {
-    ...body,
-    candidateSha256: candidateHash(body),
-  };
+  });
+  assertSourceCandidateDocumentBoundsV2(candidate);
   writeJsonExclusiveAtomically(candidatePath, candidate);
   return {
     status: "source_candidate_frozen",
@@ -721,6 +872,49 @@ export function freezeSourceCandidateWithinControlTransactionV2({
   };
 }
 
+export function previewSourceCandidateWithinControlTransactionV2({
+  workspaceRoot,
+  runId,
+  workItemId,
+}) {
+  const root = realpathSync(workspaceRoot);
+  const { executionRoot, pinGate } = loadActiveExecution(root, runId);
+  if (pinGate.status !== "valid") {
+    return { ...pinGate, authorizationGranted: false };
+  }
+  const lease = activeLease({
+    workspaceRoot: root,
+    executionRoot,
+    workItemId,
+  });
+  const baselineBefore = currentBaseline(root);
+  const manifestBefore = sourceManifestV2({
+    workspaceRoot: root,
+    ownedPaths: lease.ownedPaths,
+  });
+  const manifestAfter = sourceManifestV2({
+    workspaceRoot: root,
+    ownedPaths: lease.ownedPaths,
+  });
+  const baselineAfter = currentBaseline(root);
+  if (
+    manifestBefore.sha256 !== manifestAfter.sha256
+    || canonicalJson(baselineBefore) !== canonicalJson(baselineAfter)
+  ) {
+    throw new Error("Owned workspace source changed during candidate preview.");
+  }
+  return {
+    status: "source_candidate_previewed",
+    exitCode: 0,
+    runId,
+    workItemId,
+    baseline: baselineAfter,
+    sourceManifest: manifestAfter,
+    sourceFingerprint: manifestAfter.sha256.slice("sha256:".length),
+    authorizationGranted: false,
+  };
+}
+
 export function freezeSourceCandidateV2(options) {
   const workspaceRoot = realpathSync(options.workspaceRoot);
   return withControlTransaction(
@@ -732,31 +926,31 @@ export function freezeSourceCandidateV2(options) {
   );
 }
 
-export function verifySourceCandidateV2({
+export function verifySourceCandidateDetailsV2({
   workspaceRoot,
   candidatePath,
+  requireCurrentWorkspace = true,
 }) {
   const root = realpathSync(workspaceRoot);
   const issueCodes = [];
   let absoluteCandidatePath;
   let candidate;
   try {
-    absoluteCandidatePath = resolveExistingArtifact(
-      root,
-      candidatePath,
-      "candidatePath",
-    );
-    const stat = lstatSync(absoluteCandidatePath);
-    if (stat.isSymbolicLink() || !stat.isFile()) {
-      throw new Error("candidate is not a regular file");
-    }
-    candidate = readJson(absoluteCandidatePath);
+    const relativeCandidatePath = safeRelativePath(candidatePath, "candidatePath");
+    candidate = readWorkspaceJsonBounded(root, relativeCandidatePath, {
+      maxBytes: SOURCE_CANDIDATE_V2_MAX_BYTES,
+      maxNodes: SOURCE_CANDIDATE_V2_MAX_NODES,
+    });
+    absoluteCandidatePath = path.join(root, relativeCandidatePath);
   } catch {
     return {
-      status: "invalid",
-      exitCode: 2,
-      issueCodes: ["source_candidate_unreadable"],
-      authorizationGranted: false,
+      gate: {
+        status: "invalid",
+        exitCode: 2,
+        issueCodes: ["source_candidate_unreadable"],
+        authorizationGranted: false,
+      },
+      candidateDocument: null,
     };
   }
   const candidateSha256 = candidate.candidateSha256;
@@ -792,7 +986,7 @@ export function verifySourceCandidateV2({
       issueCodes.push("source_candidate_lease_unreadable");
     }
   }
-  if (issueCodes.length === 0) {
+  if (issueCodes.length === 0 && requireCurrentWorkspace) {
     try {
       const currentManifest = sourceManifestV2({
         workspaceRoot: root,
@@ -812,7 +1006,7 @@ export function verifySourceCandidateV2({
       issueCodes.push("source_candidate_baseline_drift");
     }
   }
-  return {
+  const gate = {
     status: issueCodes.length === 0 ? "valid" : "invalid",
     exitCode: issueCodes.length === 0 ? 0 : 2,
     candidatePath: relativeToWorkspace(root, absoluteCandidatePath),
@@ -821,6 +1015,14 @@ export function verifySourceCandidateV2({
     issueCodes: [...new Set(issueCodes)].sort(),
     authorizationGranted: false,
   };
+  return {
+    gate,
+    candidateDocument: gate.status === "valid" ? candidate : null,
+  };
+}
+
+export function verifySourceCandidateV2(options) {
+  return verifySourceCandidateDetailsV2(options).gate;
 }
 
 class SimulatedMaterializationInterruption extends Error {