@riddledc/riddle-proof 0.8.77 → 0.8.79

package/dist/pr-comment.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var pr_comment_exports = {};
 __export(pr_comment_exports, {
   RIDDLE_PROOF_PR_COMMENT_MARKER: () => RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofHandoffPrCommentMarkdown: () => buildRiddleProofHandoffPrCommentMarkdown,
   buildRiddleProofPrCommentMarkdown: () => buildRiddleProofPrCommentMarkdown,
   summarizeRiddleProofPrComment: () => summarizeRiddleProofPrComment
 });
@@ -202,6 +203,313 @@ function summarizeRiddleProofPublicState(input) {
   };
 }
 
+// src/profile.ts
+var RIDDLE_PROOF_PROFILE_STATUSES = [
+  "passed",
+  "product_regression",
+  "proof_insufficient",
+  "environment_blocked",
+  "configuration_error",
+  "needs_human_review"
+];
+
+// src/receipts.ts
+var RIDDLE_PREVIEW_RECEIPT_VERSION = "riddle.preview-receipt.v1";
+var RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION = "riddle-proof.observation-receipt.v1";
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function requiredString(record, key, context) {
+  const value = record[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${context}.${key} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+function normalizedSourceIdentity(value) {
+  if (!isRecord(value)) return {};
+  return {
+    git_revision: typeof value.git_revision === "string" && value.git_revision.trim() ? value.git_revision.trim() : void 0,
+    repository: typeof value.repository === "string" && value.repository.trim() ? value.repository.trim() : void 0,
+    dirty: typeof value.dirty === "boolean" ? value.dirty : void 0,
+    label: typeof value.label === "string" && value.label.trim() ? value.label.trim() : void 0
+  };
+}
+function parseRiddlePreviewReceipt(value) {
+  if (!isRecord(value)) throw new Error("Preview receipt must be an object.");
+  if (value.version !== RIDDLE_PREVIEW_RECEIPT_VERSION) {
+    throw new Error(`Unsupported Preview receipt version ${String(value.version || "missing")}.`);
+  }
+  if (!isRecord(value.source)) throw new Error("Preview receipt source must be an object.");
+  const expiresAt = requiredString(value, "expires_at", "preview receipt");
+  const publishedAt = requiredString(value, "published_at", "preview receipt");
+  const contentDigest = requiredString(value, "content_digest", "preview receipt");
+  if (!contentDigest.startsWith("sha256:") || contentDigest.length <= "sha256:".length) {
+    throw new Error("preview receipt.content_digest must be a sha256 digest.");
+  }
+  if (!Number.isFinite(Date.parse(expiresAt)) || !Number.isFinite(Date.parse(publishedAt))) {
+    throw new Error("Preview receipt timestamps must be valid ISO date strings.");
+  }
+  return {
+    version: RIDDLE_PREVIEW_RECEIPT_VERSION,
+    preview_id: requiredString(value, "preview_id", "preview receipt"),
+    url: requiredString(value, "url", "preview receipt"),
+    expires_at: expiresAt,
+    content_digest: contentDigest,
+    source: normalizedSourceIdentity(value.source),
+    published_at: publishedAt
+  };
+}
+function parseRiddleProofObservationReceipt(value) {
+  if (!isRecord(value)) throw new Error("Observation receipt must be an object.");
+  if (value.version !== RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION) {
+    throw new Error(`Unsupported Observation receipt version ${String(value.version || "missing")}.`);
+  }
+  if (!isRecord(value.executor)) throw new Error("Observation receipt executor must be an object.");
+  if (!isRecord(value.target)) throw new Error("Observation receipt target must be an object.");
+  if (!isRecord(value.source)) throw new Error("Observation receipt source must be an object.");
+  requiredString(value, "observation_id", "observation receipt");
+  requiredString(value, "captured_at", "observation receipt");
+  const executorKind = requiredString(value.executor, "kind", "observation receipt executor");
+  if (!"local_playwright,riddle_hosted,browser_api,other".split(",").includes(executorKind)) {
+    throw new Error(`Unsupported observation executor kind ${executorKind}.`);
+  }
+  if (value.executor.runner !== void 0) {
+    requiredString(value.executor, "runner", "observation receipt executor");
+  }
+  const role = requiredString(value, "comparison_role", "observation receipt");
+  if (!["before", "after", "standalone"].includes(role)) {
+    throw new Error(`Unsupported observation comparison role ${role}.`);
+  }
+  const targetKind = requiredString(value.target, "kind", "observation receipt target");
+  if (targetKind !== "url" && targetKind !== "preview") {
+    throw new Error(`Unsupported observation target kind ${targetKind}.`);
+  }
+  requiredString(value.target, "url", "observation receipt target");
+  if (targetKind === "preview") {
+    if (value.target.preview === void 0) {
+      throw new Error("Preview Observation target must include its Preview receipt.");
+    }
+    parseRiddlePreviewReceipt(value.target.preview);
+  }
+  if (!Array.isArray(value.artifacts)) throw new Error("Observation receipt artifacts must be an array.");
+  const artifactRoles = /* @__PURE__ */ new Set(["canonical_screenshot", "setup_screenshot", "data", "diagnostic", "artifact"]);
+  const artifacts = value.artifacts.map((artifact, index) => {
+    if (!isRecord(artifact)) throw new Error(`Observation receipt artifact ${index} must be an object.`);
+    requiredString(artifact, "name", `observation receipt artifact ${index}`);
+    const artifactRole = requiredString(artifact, "role", `observation receipt artifact ${index}`);
+    if (!artifactRoles.has(artifactRole)) {
+      throw new Error(`Unsupported observation artifact role ${artifactRole}.`);
+    }
+    return artifact;
+  });
+  if (value.canonical_screenshot !== void 0) {
+    if (!isRecord(value.canonical_screenshot) || value.canonical_screenshot.role !== "canonical_screenshot") {
+      throw new Error("Observation canonical_screenshot must have the canonical_screenshot role.");
+    }
+    const canonical = value.canonical_screenshot;
+    const included = artifacts.some((artifact) => artifact.role === "canonical_screenshot" && artifact.name === canonical.name && artifact.url === canonical.url && artifact.path === canonical.path);
+    if (!included) {
+      throw new Error("Observation canonical_screenshot must reference an artifact in the receipt.");
+    }
+  }
+  return value;
+}
+
+// src/change-proof.ts
+var RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION = "riddle-proof.change-receipt.v1";
+var RIDDLE_PROOF_CHANGE_RECEIPT_VERSION = "riddle-proof.change-receipt.v2";
+var RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION = "riddle-proof.handoff-receipt.v1";
+var DEFAULT_BEFORE_STATUSES = ["passed", "product_regression"];
+var DEFAULT_AFTER_STATUSES = ["passed"];
+function changeReceiptVerdict(status) {
+  if (status === "passed") return "mergeable";
+  if (status === "environment_blocked") return "environment_blocked";
+  if (status === "configuration_error") return "configuration_error";
+  if (status === "needs_human_review") return "needs_human_review";
+  if (status === "proof_insufficient") return "proof_insufficient";
+  return "not_mergeable";
+}
+function changeRecommendation(verdict) {
+  if (verdict === "mergeable") {
+    return {
+      merge_recommended: true,
+      verdict,
+      label: "Merge recommended",
+      reason: "The declared before/after delta contract passed with sufficient bound evidence."
+    };
+  }
+  const reason = verdict === "not_mergeable" ? "The declared change delta did not pass." : verdict === "environment_blocked" ? "The environment blocked reliable evidence collection." : verdict === "needs_human_review" ? "The evidence requires human review." : verdict === "configuration_error" ? "The change contract is invalid." : "The change proof did not produce sufficient bound evidence.";
+  return { merge_recommended: false, verdict, label: "Merge not recommended", reason };
+}
+function noShippingAuthorization() {
+  return { status: "not_granted", authorized: false, source: "none" };
+}
+function recommendationMatches(actual, expected) {
+  return actual?.merge_recommended === expected.merge_recommended && actual.verdict === expected.verdict && actual.label === expected.label && actual.reason === expected.reason;
+}
+function assertShippingAuthorizationConsistent(authorization, receiptName) {
+  if (!authorization) throw new Error(`${receiptName} shipping authorization is required.`);
+  if (authorization.status !== "not_granted" && authorization.status !== "granted") {
+    throw new Error(`${receiptName} shipping authorization status is invalid.`);
+  }
+  if (authorization.source !== "none" && authorization.source !== "human" && authorization.source !== "automation") {
+    throw new Error(`${receiptName} shipping authorization source is invalid.`);
+  }
+  const granted = authorization.status === "granted";
+  if (authorization.authorized !== granted) {
+    throw new Error(`${receiptName} shipping authorization status and authorized flag must agree.`);
+  }
+  if (authorization.source === "none" === granted) {
+    throw new Error(`${receiptName} shipping authorization source must identify an authorizer only when granted.`);
+  }
+}
+function observationArtifactMatches(actual, expected) {
+  if (!actual || !expected) return actual === expected;
+  return actual.name === expected.name && actual.role === expected.role && actual.url === expected.url && actual.path === expected.path && actual.kind === expected.kind && actual.content_type === expected.content_type && actual.source === expected.source;
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function migratedObservationFromLegacySide(side, legacy) {
+  const legacyArtifacts = legacy.artifacts.map((artifact) => ({
+    name: artifact.name,
+    url: artifact.url,
+    path: artifact.path,
+    source: artifact.source,
+    kind: artifact.kind,
+    role: legacy.screenshots[0] && artifactTarget(artifact) === artifactTarget(legacy.screenshots[0]) ? "canonical_screenshot" : artifact.kind === "image" ? "diagnostic" : artifact.kind === "data" ? "data" : "artifact"
+  }));
+  const canonicalScreenshot = legacyArtifacts.find((artifact) => artifact.role === "canonical_screenshot");
+  return {
+    version: "riddle-proof.observation-receipt.v1",
+    observation_id: `obs_${side}_migrated`,
+    comparison_role: side,
+    executor: { kind: "other", runner: "legacy-change-receipt" },
+    target: { kind: "url", url: legacy.source },
+    source: {},
+    captured_at: legacy.captured_at || (/* @__PURE__ */ new Date(0)).toISOString(),
+    artifacts: legacyArtifacts,
+    canonical_screenshot: canonicalScreenshot,
+    profile_summary: {
+      profile_name: legacy.profile_name,
+      status: legacy.status,
+      summary: legacy.summary,
+      route: legacy.route,
+      checks: legacy.checks
+    },
+    metadata: { migrated_from: RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION }
+  };
+}
+function migrateRiddleProofChangeReceipt(legacy) {
+  const recommendation = changeRecommendation(legacy.verdict);
+  return {
+    version: RIDDLE_PROOF_CHANGE_RECEIPT_VERSION,
+    contract_name: legacy.contract_name,
+    profile_name: legacy.profile_name,
+    status: legacy.status,
+    verdict: legacy.verdict,
+    summary: legacy.summary,
+    before: migratedObservationFromLegacySide("before", legacy.before),
+    after: migratedObservationFromLegacySide("after", legacy.after),
+    groups: {
+      before: {
+        side: "before",
+        label: "before",
+        ok: legacy.before.status === "passed" || legacy.before.status === "product_regression",
+        profile_name: legacy.before.profile_name,
+        status: legacy.before.status,
+        required_status: DEFAULT_BEFORE_STATUSES,
+        summary: legacy.before.summary
+      },
+      after: {
+        side: "after",
+        label: "after",
+        ok: legacy.after.status === "passed",
+        profile_name: legacy.after.profile_name,
+        status: legacy.after.status,
+        required_status: DEFAULT_AFTER_STATUSES,
+        summary: legacy.after.summary
+      }
+    },
+    source_bindings: {
+      before: { side: "before", required: false, ok: true, status: "not_required" },
+      after: { side: "after", required: false, ok: true, status: "not_required" }
+    },
+    deltas: legacy.deltas,
+    recommendation,
+    shipping_authorization: noShippingAuthorization(),
+    proves: legacy.proves,
+    does_not_prove: legacy.does_not_prove,
+    metadata: legacy.metadata
+  };
+}
+function parseRiddleProofChangeReceipt(value) {
+  if (!isRecord2(value)) throw new Error("Change receipt must be an object.");
+  if (value.version === RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION) {
+    return migrateRiddleProofChangeReceipt(value);
+  }
+  if (value.version !== RIDDLE_PROOF_CHANGE_RECEIPT_VERSION) {
+    throw new Error(`Unsupported Change receipt version ${String(value.version || "missing")}.`);
+  }
+  const receipt = value;
+  if (!RIDDLE_PROOF_PROFILE_STATUSES.includes(receipt.status)) {
+    throw new Error(`Unsupported Change receipt status ${String(receipt.status || "missing")}.`);
+  }
+  parseRiddleProofObservationReceipt(receipt.before);
+  parseRiddleProofObservationReceipt(receipt.after);
+  if (receipt.before.comparison_role !== "before" || receipt.after.comparison_role !== "after") {
+    throw new Error("Change receipt observations must preserve their before and after comparison roles.");
+  }
+  const expectedVerdict = changeReceiptVerdict(receipt.status);
+  if (receipt.verdict !== expectedVerdict) {
+    throw new Error("Change receipt verdict must match its evaluated status.");
+  }
+  if (!recommendationMatches(receipt.recommendation, changeRecommendation(expectedVerdict))) {
+    throw new Error("Change receipt recommendation must be derived from the Change receipt verdict.");
+  }
+  assertShippingAuthorizationConsistent(receipt.shipping_authorization, "Change receipt");
+  return receipt;
+}
+function createRiddleProofHandoffReceipt(changeReceipt, options = {}) {
+  const change = parseRiddleProofChangeReceipt(changeReceipt);
+  const authorization = options.shipping_authorization || change.shipping_authorization;
+  assertShippingAuthorizationConsistent(authorization, "Handoff receipt");
+  return {
+    version: RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION,
+    change,
+    verdict: change.verdict,
+    recommendation: change.recommendation,
+    shipping_authorization: authorization,
+    canonical_pair: {
+      before: change.before.canonical_screenshot,
+      after: change.after.canonical_screenshot
+    },
+    created_at: options.created_at || (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function parseRiddleProofHandoffReceipt(value) {
+  if (!isRecord2(value) || value.version !== RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION) {
+    throw new Error(`Unsupported Handoff receipt version ${String(isRecord2(value) ? value.version || "missing" : "missing")}.`);
+  }
+  const receipt = value;
+  if (!Number.isFinite(Date.parse(receipt.created_at))) {
+    throw new Error("Handoff receipt created_at must be a valid timestamp.");
+  }
+  const change = parseRiddleProofChangeReceipt(receipt.change);
+  if (receipt.verdict !== change.verdict || !recommendationMatches(receipt.recommendation, change.recommendation)) {
+    throw new Error("Handoff receipt must preserve the Change receipt verdict and recommendation.");
+  }
+  if (!observationArtifactMatches(receipt.canonical_pair?.before, change.before.canonical_screenshot) || !observationArtifactMatches(receipt.canonical_pair?.after, change.after.canonical_screenshot)) {
+    throw new Error("Handoff receipt canonical pair must project the Change receipt observations.");
+  }
+  assertShippingAuthorizationConsistent(receipt.shipping_authorization, "Handoff receipt");
+  return receipt;
+}
+function artifactTarget(artifact) {
+  return artifact.url || artifact.path;
+}
+
 // src/pr-comment.ts
 var RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
 function asRecord2(value) {
@@ -282,9 +590,10 @@ function collectChangeReceiptArtifacts(result) {
   const seen = /* @__PURE__ */ new Set();
   const collectSide = (sideName, side) => {
     const candidates = [
+      side.canonical_screenshot,
       ...asArray(side.screenshots),
       ...asArray(side.artifacts)
-    ];
+    ].filter(Boolean);
     for (const [index, item] of candidates.entries()) {
       const artifact = asRecord2(item);
       const url = stringValue2(artifact.url) || stringValue2(artifact.path);
@@ -376,9 +685,10 @@ function changeReceiptPageSummaries(result) {
   for (const sideName of ["before", "after"]) {
     const side = asRecord2(result[sideName]);
     if (!Object.keys(side).length) continue;
-    const checks = asRecord2(side.checks);
+    const profileSummary = asRecord2(side.profile_summary);
+    const checks = Object.keys(asRecord2(side.checks)).length ? asRecord2(side.checks) : asRecord2(profileSummary.checks);
     pages.push({
-      route: firstStringValue2(side.source, side.profile_name) || sideName,
+      route: firstStringValue2(asRecord2(side.target).url, side.source, profileSummary.profile_name, side.profile_name) || sideName,
       passed: numberValue2(checks.passed) ?? 0,
       failed: numberValue2(checks.failed) ?? 0
     });
@@ -441,7 +751,11 @@ function isProfileResult(result) {
   return version === "riddle-proof.profile-result.v1" || version === "riddle-proof.profile-compact-result.v1";
 }
 function isChangeReceiptResult(result) {
-  return stringValue2(result.version) === "riddle-proof.change-receipt.v1";
+  const version = stringValue2(result.version);
+  return version === RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION || version === RIDDLE_PROOF_CHANGE_RECEIPT_VERSION;
+}
+function isHandoffReceiptResult(result) {
+  return stringValue2(result.version) === RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION;
 }
 function isChangeResult(result) {
   const version = stringValue2(result.version);
@@ -449,10 +763,13 @@ function isChangeResult(result) {
 }
 function summarizeRiddleProofPrComment(input) {
   const runResponse = asRecord2(input.runResponse);
-  const result = asRecord2(input.result);
+  const inputResult = asRecord2(input.result);
+  const handoffReceipt = isHandoffReceiptResult(inputResult) ? parseRiddleProofHandoffReceipt(inputResult) : void 0;
+  const parsedChangeReceipt = handoffReceipt?.change || (isChangeReceiptResult(inputResult) ? parseRiddleProofChangeReceipt(inputResult) : void 0);
+  const result = parsedChangeReceipt ? asRecord2(parsedChangeReceipt) : inputResult;
   const proofResult = asRecord2(runResponse.proofResult);
   const profileResult = isProfileResult(result);
-  const changeReceiptResult = isChangeReceiptResult(result);
+  const changeReceiptResult = Boolean(parsedChangeReceipt);
   const changeResult = changeReceiptResult || isChangeResult(result);
   const profileRiddle = asRecord2(result.riddle);
   const preview = asRecord2(runResponse.preview);
@@ -473,7 +790,7 @@ function summarizeRiddleProofPrComment(input) {
   delete checkSource.ok;
   const nestedChecks = summarizeExplicitChecks(checkSource);
   const resultStatus = firstStringValue2(result.status, stopCondition.status);
-  const ok = changeResult ? resultStatus === "passed" : booleanValue2(result.ok) ?? booleanValue2(runResponse.ok) ?? null;
+  const ok = changeReceiptResult ? parsedChangeReceipt?.recommendation.merge_recommended ?? false : changeResult ? resultStatus === "passed" : booleanValue2(result.ok) ?? booleanValue2(runResponse.ok) ?? null;
   const checkpointSummary = checkpointSummaryFrom2(
     result.checkpoint_summary,
     stopCondition.checkpoint_summary,
@@ -481,19 +798,19 @@ function summarizeRiddleProofPrComment(input) {
     rawDetails.checkpoint_summary,
     proofResult.checkpoint_summary
   );
-  const publicState = summarizeRiddleProofPublicState({
+  const publicState = changeReceiptResult ? void 0 : summarizeRiddleProofPublicState({
     ...result,
     status: resultStatus,
     checkpoint_summary: checkpointSummary || result.checkpoint_summary
   });
-  const mergeRecommendation = riddleProofPublicStateMergeRecommendation(
+  const mergeRecommendation = publicState ? riddleProofPublicStateMergeRecommendation(
     publicState,
     firstStringValue2(result.merge_recommendation, stopCondition.merge_recommendation, resultRaw.merge_recommendation)
-  );
+  ) : void 0;
   return {
     ok,
     status: firstStringValue2(proofResult.status, profileRiddle.status),
-    result_status: changeResult ? resultStatus : publicState.status,
+    result_status: changeResult ? resultStatus : publicState?.status,
     job_id: firstStringValue2(proofResult.job_id, profileRiddle.job_id),
     duration_ms: numberValue2(proofResult.duration_ms) ?? numberValue2(profileRiddle.elapsed_ms),
     proof_url: stringValue2(runResponse.proofUrl),
@@ -501,13 +818,13 @@ function summarizeRiddleProofPrComment(input) {
     preview_url: stringValue2(preview.preview_url) || stringValue2(preview.url),
     preview_publish_recovered: booleanValue2(preview.publish_recovered),
     preview_publish_error: stringValue2(preview.publish_error),
-    ship_held: publicState.ship_held,
-    shipping_disabled: publicState.shipping_disabled,
-    ship_authorized: publicState.ship_authorized,
-    merge_ready: publicState.merge_ready,
-    sync_allowed: publicState.sync_allowed,
+    ship_held: publicState?.ship_held,
+    shipping_disabled: publicState?.shipping_disabled,
+    ship_authorized: changeReceiptResult ? parsedChangeReceipt?.shipping_authorization.authorized : publicState?.ship_authorized,
+    merge_ready: publicState?.merge_ready,
+    sync_allowed: publicState?.sync_allowed,
     proof_decision: firstStringValue2(result.proof_decision, stopCondition.proof_decision, resultRaw.proof_decision),
-    merge_recommendation: changeReceiptResult && resultStatus ? stringValue2(result.verdict) : mergeRecommendation,
+    merge_recommendation: changeReceiptResult ? parsedChangeReceipt?.recommendation.label : mergeRecommendation,
     checkpoint_summary: checkpointSummary,
     public_state: publicState,
     passed_checks: changeChecks?.passed ?? profileChecks?.passed ?? nestedChecks.passed,
@@ -575,7 +892,88 @@ function checkpointSummaryLine(summary) {
     summary.latest_decision ? `latest decision \`${summary.latest_decision}\`` : ""
   ].filter(Boolean).join("; ");
 }
+function markdownTableValue(value) {
+  return String(value ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function observationArtifactTarget(artifact) {
+  return artifact?.url || artifact?.path;
+}
+function canonicalScreenshotCell(artifact, fallback) {
+  const target = observationArtifactTarget(artifact);
+  if (!artifact || !target) return fallback;
+  if (artifact.url) return `![${artifact.name.replace(/\]/g, "\\]")}](${artifact.url})`;
+  return markdownTableValue(artifact.path || artifact.name);
+}
+function shortRevision(value) {
+  return value ? value.slice(0, 12) : "not recorded";
+}
+function buildRiddleProofHandoffPrCommentMarkdown(handoff, input = {}) {
+  const receipt = parseRiddleProofHandoffReceipt(handoff);
+  const change = receipt.change;
+  const beforeStatus = change.before.profile_summary?.status || "not recorded";
+  const afterStatus = change.after.profile_summary?.status || "not recorded";
+  const beforeBaseline = change.groups.before.ok ? "matched baseline" : "baseline mismatch";
+  const lines = [
+    RIDDLE_PROOF_PR_COMMENT_MARKER,
+    `## ${input.title?.trim() || "Riddle Change Proof"}`,
+    "",
+    `**Result:** ${receipt.recommendation.label}`,
+    `**Evidence verdict:** \`${receipt.verdict}\``,
+    `**Shipping authorization:** ${receipt.shipping_authorization.status}`,
+    `**Contract:** ${change.contract_name}`
+  ];
+  if (input.goal?.trim()) lines.push(`**Goal:** ${input.goal.trim()}`);
+  if (input.successCriteria?.trim()) lines.push(`**Success criteria:** ${input.successCriteria.trim()}`);
+  lines.push("", change.summary, "", "### Canonical Before / After", "");
+  lines.push("| Before | After |");
+  lines.push("| --- | --- |");
+  lines.push(`| ${beforeBaseline}: \`${markdownTableValue(beforeStatus)}\` | \`${markdownTableValue(afterStatus)}\` |`);
+  lines.push(`| ${canonicalScreenshotCell(receipt.canonical_pair.before, "No canonical before screenshot")} | ${canonicalScreenshotCell(receipt.canonical_pair.after, "No canonical after screenshot")} |`);
+  lines.push("", "### Source Binding", "");
+  lines.push("| Side | Target | Git revision | Binding | Preview | Digest |");
+  lines.push("| --- | --- | --- | --- | --- | --- |");
+  for (const side of ["before", "after"]) {
+    const observation = change[side];
+    const binding = change.source_bindings[side];
+    lines.push(`| ${side} | ${markdownTableValue(observation.target.url)} | \`${shortRevision(binding.observed_git_revision || observation.source.git_revision)}\` | ${binding.status} | ${markdownTableValue(binding.preview_id || observation.target.preview?.preview_id || "not required")} | \`${markdownTableValue(binding.content_digest || observation.target.preview?.content_digest || "not required")}\` |`);
+  }
+  lines.push("", "### Declared Delta", "");
+  lines.push("| Measurement | Status | Before | After |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const delta of change.deltas) {
+    lines.push(`| ${markdownTableValue(delta.label)} | ${delta.status} | ${markdownTableValue(delta.before_observed)} | ${markdownTableValue(delta.after_observed)} |`);
+  }
+  if (change.proves.length) {
+    lines.push("", "### What This Proves", "");
+    for (const claim of change.proves) lines.push(`- ${claim}`);
+  }
+  if (change.does_not_prove.length) {
+    lines.push("", "### Limits", "");
+    for (const claim of change.does_not_prove) lines.push(`- ${claim}`);
+  }
+  const linkedArtifacts = [
+    ...change.before.artifacts.map((artifact) => ({ side: "before", artifact })),
+    ...change.after.artifacts.map((artifact) => ({ side: "after", artifact }))
+  ].filter(({ artifact }) => Boolean(artifact.url));
+  if (linkedArtifacts.length) {
+    lines.push("", "### Artifacts", "");
+    for (const { side, artifact } of linkedArtifacts.slice(0, 24)) {
+      lines.push(`- ${side}: ${markdownLink(artifact.name, artifact.url || "")}`);
+    }
+  }
+  lines.push("", input.source?.trim() ? `_Source: ${input.source.trim()}_` : "_Rendered from the Handoff receipt without recomputing its verdict._");
+  return `${lines.join("\n").trim()}
+`;
+}
 function buildRiddleProofPrCommentMarkdown(input) {
+  const result = asRecord2(input.result);
+  if (isHandoffReceiptResult(result)) {
+    return buildRiddleProofHandoffPrCommentMarkdown(parseRiddleProofHandoffReceipt(result), input);
+  }
+  if (isChangeReceiptResult(result)) {
+    const handoff = createRiddleProofHandoffReceipt(parseRiddleProofChangeReceipt(result));
+    return buildRiddleProofHandoffPrCommentMarkdown(handoff, input);
+  }
   const summary = summarizeRiddleProofPrComment(input);
   const title = input.title?.trim() || "Riddle Proof Evidence";
   const lines = [
@@ -645,6 +1043,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofHandoffPrCommentMarkdown,
   buildRiddleProofPrCommentMarkdown,
   summarizeRiddleProofPrComment
 });

package/dist/pr-comment.d.cts

@@ -1,4 +1,8 @@
 import { RiddleProofPublicStateSummary } from './public-state.cjs';
+import { RiddleProofHandoffReceipt } from './change-proof.cjs';
+import './profile.cjs';
+import './types.cjs';
+import './receipts.cjs';
 
 declare const RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
 type RiddleProofPrCommentArtifactKind = "image" | "data" | "artifact";
@@ -58,6 +62,7 @@ interface RiddleProofPrCommentInput {
     source?: string;
 }
 declare function summarizeRiddleProofPrComment(input: RiddleProofPrCommentInput): RiddleProofPrCommentSummary;
+declare function buildRiddleProofHandoffPrCommentMarkdown(handoff: RiddleProofHandoffReceipt, input?: Omit<RiddleProofPrCommentInput, "result">): string;
 declare function buildRiddleProofPrCommentMarkdown(input: RiddleProofPrCommentInput): string;
 
-export { RIDDLE_PROOF_PR_COMMENT_MARKER, type RiddleProofPrCommentArtifact, type RiddleProofPrCommentArtifactKind, type RiddleProofPrCommentCheckpointSummary, type RiddleProofPrCommentInput, type RiddleProofPrCommentPageSummary, type RiddleProofPrCommentSummary, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment };
+export { RIDDLE_PROOF_PR_COMMENT_MARKER, type RiddleProofPrCommentArtifact, type RiddleProofPrCommentArtifactKind, type RiddleProofPrCommentCheckpointSummary, type RiddleProofPrCommentInput, type RiddleProofPrCommentPageSummary, type RiddleProofPrCommentSummary, buildRiddleProofHandoffPrCommentMarkdown, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment };

package/dist/pr-comment.d.ts

@@ -1,4 +1,8 @@
 import { RiddleProofPublicStateSummary } from './public-state.js';
+import { RiddleProofHandoffReceipt } from './change-proof.js';
+import './profile.js';
+import './types.js';
+import './receipts.js';
 
 declare const RIDDLE_PROOF_PR_COMMENT_MARKER = "<!-- riddle-proof:pr-comment:v1 -->";
 type RiddleProofPrCommentArtifactKind = "image" | "data" | "artifact";
@@ -58,6 +62,7 @@ interface RiddleProofPrCommentInput {
     source?: string;
 }
 declare function summarizeRiddleProofPrComment(input: RiddleProofPrCommentInput): RiddleProofPrCommentSummary;
+declare function buildRiddleProofHandoffPrCommentMarkdown(handoff: RiddleProofHandoffReceipt, input?: Omit<RiddleProofPrCommentInput, "result">): string;
 declare function buildRiddleProofPrCommentMarkdown(input: RiddleProofPrCommentInput): string;
 
-export { RIDDLE_PROOF_PR_COMMENT_MARKER, type RiddleProofPrCommentArtifact, type RiddleProofPrCommentArtifactKind, type RiddleProofPrCommentCheckpointSummary, type RiddleProofPrCommentInput, type RiddleProofPrCommentPageSummary, type RiddleProofPrCommentSummary, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment };
+export { RIDDLE_PROOF_PR_COMMENT_MARKER, type RiddleProofPrCommentArtifact, type RiddleProofPrCommentArtifactKind, type RiddleProofPrCommentCheckpointSummary, type RiddleProofPrCommentInput, type RiddleProofPrCommentPageSummary, type RiddleProofPrCommentSummary, buildRiddleProofHandoffPrCommentMarkdown, buildRiddleProofPrCommentMarkdown, summarizeRiddleProofPrComment };

package/dist/pr-comment.js

@@ -1,12 +1,17 @@
 import {
   RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofHandoffPrCommentMarkdown,
   buildRiddleProofPrCommentMarkdown,
   summarizeRiddleProofPrComment
-} from "./chunk-IY4W6STC.js";
+} from "./chunk-7N6X54WG.js";
+import "./chunk-6VFS2JFR.js";
+import "./chunk-MEVVL4TI.js";
+import "./chunk-FCSJZBC5.js";
 import "./chunk-ZAR7BWMN.js";
 import "./chunk-MLKGABMK.js";
 export {
   RIDDLE_PROOF_PR_COMMENT_MARKER,
+  buildRiddleProofHandoffPrCommentMarkdown,
   buildRiddleProofPrCommentMarkdown,
   summarizeRiddleProofPrComment
 };

package/dist/profile/index.cjs

@@ -834,6 +834,12 @@ function profileScreenshotLabels(viewports) {
   }
   return labels;
 }
+function profileFinalScreenshotLabels(viewports) {
+  return (viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => typeof label === "string" && Boolean(label.trim()));
+}
+function profileAllSetupScreenshotLabels(viewports) {
+  return (viewports || []).flatMap((viewport) => profileSetupScreenshotLabels(viewport.setup_action_results || []));
+}
 function profileSetupSummary(viewports, actionCount, expectedActionCountByViewport, finalScreenshotFullPage) {
   const normalizedFinalScreenshotFullPage = finalScreenshotFullPage === void 0 ? void 0 : finalScreenshotFullPage !== false;
   const finalScreenshotCount = viewports.filter((viewport) => typeof viewport.screenshot_label === "string" && viewport.screenshot_label.trim()).length;
@@ -3684,6 +3690,8 @@ function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
   const status = profileStatusFromEvidence(profile, evidence, checks);
   const firstViewport = evidence?.viewports?.[0];
   const screenshots = profileScreenshotLabels(evidence?.viewports);
+  const canonicalScreenshots = profileFinalScreenshotLabels(evidence?.viewports);
+  const setupScreenshots = profileAllSetupScreenshotLabels(evidence?.viewports);
   const result = {
     version: RIDDLE_PROOF_PROFILE_RESULT_VERSION,
     profile_name: profile.name,
@@ -3693,6 +3701,8 @@ function assessRiddleProofProfileEvidence(profile, evidence, options = {}) {
     route: routeForViewport(firstViewport, evidence?.target_url),
     artifacts: {
       screenshots,
+      canonical_screenshots: canonicalScreenshots,
+      setup_screenshots: setupScreenshots,
       console: "console.json",
       proof_json: "proof.json",
       dom_summary: "dom-summary.json",
@@ -5011,6 +5021,12 @@ function profileScreenshotLabels(viewports) {
   }
   return labels;
 }
+function profileFinalScreenshotLabels(viewports) {
+  return (viewports || []).map((viewport) => viewport && viewport.screenshot_label).filter(Boolean);
+}
+function profileAllSetupScreenshotLabels(viewports) {
+  return (viewports || []).flatMap((viewport) => profileSetupScreenshotLabels(viewport && viewport.setup_action_results || []));
+}
 function profileSetupSummary(viewports, actionCount, expectedActionCountsByViewport, finalScreenshotFullPage) {
   const normalizedFinalScreenshotFullPage = finalScreenshotFullPage === undefined
     ? undefined
@@ -5879,6 +5895,8 @@ function assessProfile(profile, evidence) {
   else if (checks.some((check) => check.status === "needs_human_review")) status = "needs_human_review";
   else if (checks.some((check) => check.status === "failed")) status = "product_regression";
   const screenshotLabels = profileScreenshotLabels(viewports);
+  const canonicalScreenshotLabels = profileFinalScreenshotLabels(viewports);
+  const setupScreenshotLabels = profileAllSetupScreenshotLabels(viewports);
   const route = viewports[0] && viewports[0].route ? viewports[0].route : { requested: evidence.target_url, observed: "", matched: false, error: "missing viewport evidence" };
   const passedChecks = checks.filter((check) => check.status === "passed").length;
   const failedChecks = checks.filter((check) => check.status === "failed").length;
@@ -5895,7 +5913,14 @@ function assessProfile(profile, evidence) {
     status,
     baseline_policy: profile.baseline_policy || "invariant_only",
     route,
-    artifacts: { screenshots: screenshotLabels, console: "console.json", proof_json: "proof.json", dom_summary: "dom-summary.json" },
+    artifacts: {
+      screenshots: screenshotLabels,
+      canonical_screenshots: canonicalScreenshotLabels,
+      setup_screenshots: setupScreenshotLabels,
+      console: "console.json",
+      proof_json: "proof.json",
+      dom_summary: "dom-summary.json"
+    },
     checks,
     summary,
     captured_at: evidence.captured_at,

package/dist/profile/index.js

@@ -27,7 +27,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "../chunk-GG2D3MFZ.js";
+} from "../chunk-FCSJZBC5.js";
 import "../chunk-MLKGABMK.js";
 export {
   RIDDLE_PROOF_HOSTED_PROFILE_ARTIFACTS,