@riddledc/riddle-proof 0.8.77 → 0.8.78

package/dist/index.cjs

@@ -3414,16 +3414,20 @@ __export(index_exports, {
   DEFAULT_DIAGNOSTIC_STRING_LIMIT: () => DEFAULT_DIAGNOSTIC_STRING_LIMIT,
   DEFAULT_RIDDLE_API_BASE_URL: () => DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE: () => DEFAULT_RIDDLE_API_KEY_FILE,
+  RIDDLE_PREVIEW_RECEIPT_VERSION: () => RIDDLE_PREVIEW_RECEIPT_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION: () => RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION: () => RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHANGE_CONTRACT_VERSION: () => RIDDLE_PROOF_CHANGE_CONTRACT_VERSION,
+  RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION: () => RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION,
   RIDDLE_PROOF_CHANGE_RECEIPT_VERSION: () => RIDDLE_PROOF_CHANGE_RECEIPT_VERSION,
   RIDDLE_PROOF_CHANGE_RESULT_VERSION: () => RIDDLE_PROOF_CHANGE_RESULT_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION: () => RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION: () => RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
+  RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION: () => RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION,
   RIDDLE_PROOF_HOSTED_PROFILE_ARTIFACTS: () => RIDDLE_PROOF_HOSTED_PROFILE_ARTIFACTS,
+  RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION: () => RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION: () => RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_VERSION: () => RIDDLE_PROOF_PLAYABILITY_VERSION,
   RIDDLE_PROOF_PROFILE_CHECK_TYPES: () => RIDDLE_PROOF_PROFILE_CHECK_TYPES,
@@ -3462,6 +3466,7 @@ __export(index_exports, {
   buildAuthorCheckpointPacket: () => buildAuthorCheckpointPacket,
   buildCheckpointPacketForEngineResult: () => buildCheckpointPacketForEngineResult,
   buildProofAssessmentCheckpointPacket: () => buildProofAssessmentCheckpointPacket,
+  buildRiddleProofHandoffPrCommentMarkdown: () => buildRiddleProofHandoffPrCommentMarkdown,
   buildRiddleProofPrCommentMarkdown: () => buildRiddleProofPrCommentMarkdown,
   buildRiddleProofProfileScript: () => buildRiddleProofProfileScript,
   buildStageCheckpointPacket: () => buildStageCheckpointPacket,
@@ -3486,6 +3491,8 @@ __export(index_exports, {
   createLocalAgentJsonRunner: () => createCodexExecJsonRunner,
   createRiddleApiClient: () => createRiddleApiClient,
   createRiddleProofChangeReceipt: () => createRiddleProofChangeReceipt,
+  createRiddleProofHandoffReceipt: () => createRiddleProofHandoffReceipt,
+  createRiddleProofObservationReceipt: () => createRiddleProofObservationReceipt,
   createRiddleProofProfileConfigurationError: () => createRiddleProofProfileConfigurationError,
   createRiddleProofProfileEnvironmentBlockedResult: () => createRiddleProofProfileEnvironmentBlockedResult,
   createRiddleProofProfileInsufficientResult: () => createRiddleProofProfileInsufficientResult,
@@ -3496,6 +3503,7 @@ __export(index_exports, {
   deployRiddlePreview: () => deployRiddlePreview,
   deployRiddleStaticPreview: () => deployRiddleStaticPreview,
   deriveRiddleProofArtifactBodyAssertions: () => deriveRiddleProofArtifactBodyAssertions,
+  detectRiddlePreviewSource: () => detectRiddlePreviewSource,
   extractBasicGameplayEvidence: () => extractBasicGameplayEvidence,
   extractPlayabilityEvidence: () => extractPlayabilityEvidence,
   extractRiddleProofProfileResult: () => extractRiddleProofProfileResult,
@@ -3506,6 +3514,7 @@ __export(index_exports, {
   isSuccessfulStatus: () => isSuccessfulStatus,
   isTerminalRiddleJobStatus: () => isTerminalRiddleJobStatus,
   isTerminalStatus: () => isTerminalStatus,
+  migrateRiddleProofChangeReceipt: () => migrateRiddleProofChangeReceipt,
   nonEmptyString: () => nonEmptyString,
   normalizeCheckpointResponse: () => normalizeCheckpointResponse,
   normalizeIntegrationContext: () => normalizeIntegrationContext,
@@ -3513,6 +3522,10 @@ __export(index_exports, {
   normalizeRiddleProofProfile: () => normalizeRiddleProofProfile,
   normalizeRunParams: () => normalizeRunParams,
   normalizeTerminalMetadata: () => normalizeTerminalMetadata,
+  parseRiddlePreviewReceipt: () => parseRiddlePreviewReceipt,
+  parseRiddleProofChangeReceipt: () => parseRiddleProofChangeReceipt,
+  parseRiddleProofHandoffReceipt: () => parseRiddleProofHandoffReceipt,
+  parseRiddleProofObservationReceipt: () => parseRiddleProofObservationReceipt,
   parseRiddleViewport: () => parseRiddleViewport,
   parseVisualProofSession: () => parseVisualProofSession,
   pollRiddleJob: () => pollRiddleJob,
@@ -10947,6 +10960,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;
@@ -13797,6 +13816,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,
@@ -13806,6 +13827,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",
@@ -15124,6 +15147,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
@@ -15992,6 +16021,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;
@@ -16008,7 +16039,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,
@@ -19936,10 +19974,263 @@ function suggestRiddleProofProfileChecks(input) {
   };
 }
 
+// src/receipts.ts
+var RIDDLE_PREVIEW_RECEIPT_VERSION = "riddle.preview-receipt.v1";
+var RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION = "riddle-proof.observation-receipt.v1";
+function isRecord3(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 (!isRecord3(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 (!isRecord3(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 (!isRecord3(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 comparableArtifactName(value) {
+  return (value || "").split(/[/?#]/).pop()?.toLowerCase().replace(/\.(png|jpe?g|gif|webp|avif|svg)$/u, "").replace(/[^a-z0-9_-]+/gu, "-").replace(/^-+|-+$/g, "") || "";
+}
+function artifactMatchesLabel(artifact, label) {
+  const expected = comparableArtifactName(label);
+  if (!expected) return false;
+  return [artifact.name, artifact.url, artifact.path].map(comparableArtifactName).some((name) => name === expected || name.endsWith(`-${expected}`));
+}
+function artifactLooksLikeScreenshot(ref) {
+  const text = [ref.name, ref.url, ref.path, ref.kind, ref.content_type].filter(Boolean).join(" ").toLowerCase();
+  return /screenshot|\bimage\b/.test(text) || /\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/.test(text);
+}
+function finalScreenshotLabels(result) {
+  const explicit = result.artifacts.canonical_screenshots || [];
+  if (explicit.length) return explicit;
+  const fromEvidence = (result.evidence?.viewports || []).map((viewport) => viewport.screenshot_label).filter((label) => typeof label === "string" && Boolean(label.trim()));
+  if (fromEvidence.length) return fromEvidence;
+  return (result.artifacts.screenshots || []).slice(0, 1);
+}
+function setupScreenshotLabels(result) {
+  const explicit = result.artifacts.setup_screenshots || [];
+  if (explicit.length) return explicit;
+  return (result.evidence?.viewports || []).flatMap(
+    (viewport) => (viewport.setup_action_results || []).filter((action) => action.action === "screenshot" && action.ok !== false && typeof action.screenshot_label === "string").map((action) => String(action.screenshot_label))
+  );
+}
+function observationArtifactFromRef(ref, canonicalLabels, setupLabels) {
+  const base = {
+    name: ref.name,
+    role: ref.role || "artifact",
+    url: ref.url,
+    path: ref.path,
+    kind: ref.kind,
+    content_type: ref.content_type,
+    source: ref.source
+  };
+  if (!artifactLooksLikeScreenshot(ref)) return base;
+  if (canonicalLabels.some((label) => artifactMatchesLabel(base, label))) {
+    return { ...base, role: "canonical_screenshot" };
+  }
+  if (setupLabels.some((label) => artifactMatchesLabel(base, label))) {
+    return { ...base, role: "setup_screenshot" };
+  }
+  return { ...base, role: "diagnostic" };
+}
+function profileObservationArtifacts(result) {
+  const canonicalLabels = finalScreenshotLabels(result);
+  const setupLabels = setupScreenshotLabels(result);
+  const artifacts = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (artifact) => {
+    const key = artifact.url || artifact.path || `${artifact.role}:${artifact.name}`;
+    if (!artifact.name || seen.has(key)) return;
+    seen.add(key);
+    artifacts.push(artifact);
+  };
+  for (const ref of result.artifacts.riddle_artifacts || []) {
+    add(observationArtifactFromRef(ref, canonicalLabels, setupLabels));
+  }
+  for (const label of canonicalLabels) {
+    if (!artifacts.some((artifact) => artifactMatchesLabel(artifact, label))) {
+      add({ name: label, path: label, role: "canonical_screenshot", kind: "image" });
+    }
+  }
+  for (const label of setupLabels) {
+    if (!artifacts.some((artifact) => artifactMatchesLabel(artifact, label))) {
+      add({ name: label, path: label, role: "setup_screenshot", kind: "image" });
+    }
+  }
+  for (const label of result.artifacts.screenshots || []) {
+    if (!artifacts.some((artifact) => artifactMatchesLabel(artifact, label))) {
+      add({ name: label, path: label, role: "diagnostic", kind: "image" });
+    }
+  }
+  return artifacts;
+}
+function mergeObservationArtifacts(profileArtifacts, suppliedArtifacts) {
+  const artifacts = [...profileArtifacts];
+  for (const supplied of suppliedArtifacts) {
+    const suppliedNames = [supplied.name, supplied.url, supplied.path].map(comparableArtifactName).filter(Boolean);
+    const existingIndex = artifacts.findIndex((artifact) => {
+      if (supplied.url && artifact.url === supplied.url) return true;
+      if (supplied.path && artifact.path === supplied.path) return true;
+      return [artifact.name, artifact.url, artifact.path].map(comparableArtifactName).some((name) => name && suppliedNames.includes(name));
+    });
+    if (existingIndex < 0) {
+      artifacts.push(supplied);
+      continue;
+    }
+    const existing = artifacts[existingIndex];
+    const role = supplied.role === "canonical_screenshot" || supplied.role === "setup_screenshot" ? supplied.role : existing.role === "canonical_screenshot" || existing.role === "setup_screenshot" ? existing.role : supplied.role === "artifact" ? existing.role : supplied.role;
+    artifacts[existingIndex] = {
+      ...existing,
+      ...supplied,
+      role
+    };
+  }
+  return artifacts;
+}
+function defaultObservationId(role, capturedAt) {
+  return `obs_${role}_${capturedAt.replace(/[^0-9]/g, "").slice(0, 17) || "unknown"}`;
+}
+function profileCheckCounts(result) {
+  const counts = { total: result.checks.length, passed: 0, failed: 0, skipped: 0, needs_human_review: 0 };
+  for (const check of result.checks) {
+    if (check.status === "passed") counts.passed += 1;
+    if (check.status === "failed") counts.failed += 1;
+    if (check.status === "skipped") counts.skipped += 1;
+    if (check.status === "needs_human_review") counts.needs_human_review += 1;
+  }
+  return counts;
+}
+function createRiddleProofObservationReceipt(input) {
+  const capturedAt = input.captured_at || input.profile_result?.captured_at || (/* @__PURE__ */ new Date()).toISOString();
+  const profileArtifacts = input.profile_result ? profileObservationArtifacts(input.profile_result) : [];
+  const requestedCanonical = input.canonical_screenshot ? { ...input.canonical_screenshot, role: "canonical_screenshot" } : void 0;
+  const artifacts = mergeObservationArtifacts(
+    profileArtifacts,
+    [...input.artifacts || [], ...requestedCanonical ? [requestedCanonical] : []]
+  );
+  const canonicalScreenshot = requestedCanonical ? artifacts.find((artifact) => artifact.role === "canonical_screenshot" && artifactMatchesLabel(artifact, requestedCanonical.name)) || requestedCanonical : artifacts.find((artifact) => artifact.role === "canonical_screenshot");
+  const target = input.target.kind === "preview" && input.target.preview ? { ...input.target, preview: parseRiddlePreviewReceipt(input.target.preview) } : input.target;
+  return {
+    version: RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION,
+    observation_id: input.observation_id || defaultObservationId(input.comparison_role, capturedAt),
+    comparison_role: input.comparison_role,
+    executor: input.executor,
+    target,
+    source: normalizedSourceIdentity(input.source || input.target.preview?.source),
+    captured_at: capturedAt,
+    artifacts,
+    canonical_screenshot: canonicalScreenshot,
+    profile_summary: input.profile_result ? {
+      profile_name: input.profile_result.profile_name,
+      status: input.profile_result.status,
+      summary: input.profile_result.summary,
+      route: input.profile_result.route,
+      checks: profileCheckCounts(input.profile_result)
+    } : void 0,
+    proof: input.profile_result ? {
+      profile_name: input.profile_result.profile_name,
+      result: input.profile_result
+    } : void 0,
+    publication: input.publication,
+    execution: input.execution,
+    metadata: input.metadata
+  };
+}
+function parseRiddleProofObservationReceipt(value) {
+  if (!isRecord3(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 (!isRecord3(value.executor)) throw new Error("Observation receipt executor must be an object.");
+  if (!isRecord3(value.target)) throw new Error("Observation receipt target must be an object.");
+  if (!isRecord3(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 (!isRecord3(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 (!isRecord3(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_CONTRACT_VERSION = "riddle-proof.change-contract.v1";
 var RIDDLE_PROOF_CHANGE_RESULT_VERSION = "riddle-proof.change-result.v1";
-var RIDDLE_PROOF_CHANGE_RECEIPT_VERSION = "riddle-proof.change-receipt.v1";
+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"];
 var DEFAULT_PROFILE_STATUS_TRANSITION_BEFORE = ["product_regression"];
@@ -20061,13 +20352,163 @@ function assessDelta(delta, before, after) {
   }
   return checkStatusTransitionResult(delta, before, after);
 }
-function collapsedChangeStatus(groups, deltas) {
+function profileResultFromObservation(observation) {
+  return observation?.proof?.result;
+}
+function previewReceiptCoversTarget(previewUrl, targetUrl) {
+  try {
+    const preview = new URL(previewUrl);
+    const target = new URL(targetUrl);
+    const previewPath = preview.pathname.replace(/\/+$/u, "");
+    return preview.origin === target.origin && (target.pathname === previewPath || target.pathname.startsWith(`${previewPath}/`));
+  } catch {
+    return false;
+  }
+}
+function sourceBindingResult(side, requirement, observation, expectedRevision, evaluatedAt) {
+  const expected = expectedRevision || requirement?.expected_git_revision;
+  const required = Boolean(
+    requirement?.preview_receipt_required || requirement?.require_clean_source || requirement?.require_content_digest || requirement?.expected_git_revision || expected
+  );
+  if (!required) return { side, required: false, ok: true, status: "not_required" };
+  if (!observation) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "missing",
+      expected_git_revision: expected,
+      message: `${side} source binding requires an Observation receipt.`
+    };
+  }
+  const preview = observation.target.preview;
+  if (requirement?.preview_receipt_required && !preview) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "missing",
+      expected_git_revision: expected,
+      message: `${side} source binding requires a Preview receipt.`
+    };
+  }
+  if (preview && !previewReceiptCoversTarget(preview.url, observation.target.url)) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "mismatched",
+      expected_git_revision: expected,
+      observed_git_revision: preview.source.git_revision || observation.source.git_revision,
+      content_digest: preview.content_digest,
+      preview_id: preview.preview_id,
+      preview_url: preview.url,
+      target_url: observation.target.url,
+      message: `${side} observation target is not contained by Preview ${preview.preview_id}.`
+    };
+  }
+  const observed = preview?.source.git_revision || observation.source.git_revision;
+  const digestRequired = requirement?.require_content_digest === true || requirement?.preview_receipt_required === true;
+  if (digestRequired && !preview?.content_digest) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "missing",
+      expected_git_revision: expected,
+      observed_git_revision: observed,
+      preview_id: preview?.preview_id,
+      preview_url: preview?.url,
+      target_url: observation.target.url,
+      message: `${side} Preview receipt is missing a content digest.`
+    };
+  }
+  if (expected && !observed) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "missing",
+      expected_git_revision: expected,
+      content_digest: preview?.content_digest,
+      preview_id: preview?.preview_id,
+      preview_url: preview?.url,
+      target_url: observation.target.url,
+      message: `${side} evidence is missing its source Git revision.`
+    };
+  }
+  if (expected && observed !== expected) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "mismatched",
+      expected_git_revision: expected,
+      observed_git_revision: observed,
+      content_digest: preview?.content_digest,
+      preview_id: preview?.preview_id,
+      preview_url: preview?.url,
+      target_url: observation.target.url,
+      message: `${side} evidence came from Git revision ${observed}, not expected revision ${expected}.`
+    };
+  }
+  const cleanRequired = requirement?.require_clean_source === true || requirement?.preview_receipt_required === true;
+  const dirty = preview?.source.dirty ?? observation.source.dirty;
+  if (cleanRequired && dirty !== false) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: dirty === true ? "mismatched" : "missing",
+      expected_git_revision: expected,
+      observed_git_revision: observed,
+      content_digest: preview?.content_digest,
+      preview_id: preview?.preview_id,
+      preview_url: preview?.url,
+      target_url: observation.target.url,
+      message: dirty === true ? `${side} evidence was built from a dirty worktree and is not bound only to its Git revision.` : `${side} evidence does not record whether its source worktree was clean.`
+    };
+  }
+  const evaluatedMs = Date.parse(evaluatedAt);
+  const expiresMs = preview?.expires_at ? Date.parse(preview.expires_at) : Number.NaN;
+  if (preview && Number.isFinite(evaluatedMs) && Number.isFinite(expiresMs) && expiresMs <= evaluatedMs) {
+    return {
+      side,
+      required: true,
+      ok: false,
+      status: "stale",
+      expected_git_revision: expected,
+      observed_git_revision: observed,
+      content_digest: preview.content_digest,
+      preview_id: preview.preview_id,
+      preview_url: preview.url,
+      target_url: observation.target.url,
+      expires_at: preview.expires_at,
+      message: `${side} Preview receipt expired at ${preview.expires_at}.`
+    };
+  }
+  return {
+    side,
+    required: true,
+    ok: true,
+    status: "matched",
+    expected_git_revision: expected,
+    observed_git_revision: observed,
+    content_digest: preview?.content_digest,
+    preview_id: preview?.preview_id,
+    preview_url: preview?.url,
+    target_url: observation.target.url,
+    expires_at: preview?.expires_at
+  };
+}
+function collapsedChangeStatus(groups, deltas, sourceBindings) {
   const groupResults = [groups.before, groups.after];
   if (groupResults.some((group) => group.status === "environment_blocked")) return "environment_blocked";
   if (groupResults.some((group) => group.status === "configuration_error")) return "configuration_error";
   if (deltas.some((delta) => delta.status === "configuration_error")) return "configuration_error";
   if (groupResults.some((group) => group.status === "needs_human_review")) return "needs_human_review";
   if (groupResults.some((group) => group.status === "missing" || group.status === "proof_insufficient")) return "proof_insufficient";
+  if ([sourceBindings.before, sourceBindings.after].some((binding) => binding.required && !binding.ok)) return "proof_insufficient";
   if (!deltas.length || deltas.some((delta) => delta.status === "proof_insufficient")) return "proof_insufficient";
   if (groupResults.some((group) => !group.ok)) return "product_regression";
   if (deltas.some((delta) => delta.status === "failed")) return "product_regression";
@@ -20082,18 +20523,38 @@ function changeSummary(name, status, deltas) {
   return `${name} failed ${deltas.filter((delta) => delta.status === "failed").length} change delta(s).`;
 }
 function assessRiddleProofChange(contract, input) {
+  const beforeResult = input.before_result || profileResultFromObservation(input.before_observation);
+  const afterResult = input.after_result || profileResultFromObservation(input.after_observation);
   const groups = {
-    before: groupResult("before", contract.before, input.before_result),
-    after: groupResult("after", contract.after, input.after_result)
+    before: groupResult("before", contract.before, beforeResult),
+    after: groupResult("after", contract.after, afterResult)
   };
-  const deltas = (contract.deltas || []).map((delta) => assessDelta(delta, input.before_result, input.after_result));
-  const status = collapsedChangeStatus(groups, deltas);
+  const deltas = (contract.deltas || []).map((delta) => assessDelta(delta, beforeResult, afterResult));
+  const evaluatedAt = input.evaluated_at || (/* @__PURE__ */ new Date()).toISOString();
+  const sourceBindings = {
+    before: sourceBindingResult(
+      "before",
+      contract.source_binding?.before,
+      input.before_observation,
+      input.expected_source_revisions?.before,
+      evaluatedAt
+    ),
+    after: sourceBindingResult(
+      "after",
+      contract.source_binding?.after,
+      input.after_observation,
+      input.expected_source_revisions?.after,
+      evaluatedAt
+    )
+  };
+  const status = collapsedChangeStatus(groups, deltas, sourceBindings);
   return {
     version: RIDDLE_PROOF_CHANGE_RESULT_VERSION,
     contract_name: contract.name,
     status,
     groups,
     deltas,
+    source_bindings: sourceBindings,
     summary: changeSummary(contract.name, status, deltas),
     metadata: contract.metadata
   };
@@ -20106,7 +20567,7 @@ function changeReceiptVerdict(status) {
   if (status === "proof_insufficient") return "proof_insufficient";
   return "not_mergeable";
 }
-function profileCheckCounts(result) {
+function profileCheckCounts2(result) {
   const counts = {
     total: result.checks.length,
     passed: 0,
@@ -20122,86 +20583,90 @@ function profileCheckCounts(result) {
   }
   return counts;
 }
-function artifactKind(ref) {
-  const text = [ref.name, ref.url, ref.path, ref.kind, ref.content_type].filter(Boolean).join(" ").toLowerCase();
-  if (/\bimage\b/.test(text) || /\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/.test(text)) return "image";
-  if (/\bjson\b|\btext\b|\bmarkdown\b|\bhtml\b|\blog\b/.test(text) || /\.(json|md|txt|html|log|har)(\?|#|$)/.test(text)) return "data";
-  return "artifact";
+function artifactIsScreenshot(artifact) {
+  if (artifact.kind !== "image") return false;
+  return /screenshot|\.png|\.jpe?g|\.webp|\.gif|\.avif|\.svg/i.test([artifact.name, artifact.url, artifact.path].filter(Boolean).join(" "));
 }
-function receiptArtifactFromRef(side, ref) {
-  return {
-    side,
-    name: ref.name,
-    kind: artifactKind(ref),
-    url: ref.url,
-    path: ref.path,
-    source: ref.source
-  };
+function metadataStringList(metadata, key) {
+  const value = metadata?.[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
 }
-function comparableArtifactName(value) {
-  return (value || "").split(/[/?#]/).pop()?.toLowerCase().replace(/\.(png|jpe?g|gif|webp|avif|svg)$/u, "").replace(/[^a-z0-9_-]+/gu, "-").replace(/^-+|-+$/g, "") || "";
+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 artifactMatchesScreenshotLabel(artifact, screenshot) {
-  const screenshotName = comparableArtifactName(screenshot);
-  if (!screenshotName) return false;
-  return [artifact.name, artifact.url, artifact.path].map(comparableArtifactName).some((name) => name === screenshotName || name.endsWith(`-${screenshotName}`));
+function noShippingAuthorization() {
+  return { status: "not_granted", authorized: false, source: "none" };
 }
-function collectReceiptArtifacts(side, result) {
-  const artifacts = [];
-  const seen = /* @__PURE__ */ new Set();
-  const add = (artifact) => {
-    const key = artifact.url || artifact.path || `${artifact.kind}:${artifact.name}`;
-    if (!artifact.name || seen.has(key)) return;
-    seen.add(key);
-    artifacts.push(artifact);
-  };
-  for (const ref of result.artifacts.riddle_artifacts || []) {
-    add(receiptArtifactFromRef(side, ref));
+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.`);
   }
-  for (const screenshot of result.artifacts.screenshots || []) {
-    if (artifacts.some((artifact) => artifactMatchesScreenshotLabel(artifact, screenshot))) continue;
-    add({
-      side,
-      name: screenshot,
-      kind: "image"
-    });
+  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.`);
   }
-  return artifacts;
 }
-function artifactIsScreenshot(artifact) {
-  if (artifact.kind !== "image") return false;
-  return /screenshot|\.png|\.jpe?g|\.webp|\.gif|\.avif|\.svg/i.test([artifact.name, artifact.url, artifact.path].filter(Boolean).join(" "));
+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 receiptSide(side, source, result) {
-  const artifacts = collectReceiptArtifacts(side, result);
-  return {
-    side,
-    source,
-    profile_name: result.profile_name,
-    status: result.status,
-    summary: result.summary,
-    route: result.route,
-    captured_at: result.captured_at,
-    checks: profileCheckCounts(result),
-    screenshots: artifacts.filter(artifactIsScreenshot),
-    artifacts
+function observationExecutor(result) {
+  return result.runner === "local-playwright" ? { kind: "local_playwright", runner: result.runner } : {
+    kind: "riddle_hosted",
+    runner: result.runner,
+    job_id: result.riddle?.job_id
   };
 }
-function metadataStringList(metadata, key) {
-  const value = metadata?.[key];
-  if (!Array.isArray(value)) return [];
-  return value.filter((item) => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
+function observationForReceiptSide(side, result, source, sourceIdentity) {
+  if (!result) throw new Error(`${side}_result or ${side}_observation is required.`);
+  if (!source) throw new Error(`${side}_source or ${side}_observation is required.`);
+  return createRiddleProofObservationReceipt({
+    comparison_role: side,
+    executor: observationExecutor(result),
+    target: { kind: "url", url: source },
+    source: sourceIdentity,
+    profile_result: result,
+    execution: result.riddle?.execution,
+    publication: source.startsWith("http") ? { kind: result.runner === "local-playwright" ? "other" : "riddle_cdn", url: source } : { kind: "local", path: source }
+  });
 }
 function createRiddleProofChangeReceipt(input) {
+  const before = input.before_observation ? parseRiddleProofObservationReceipt(input.before_observation) : observationForReceiptSide("before", input.before_result, input.before_source, input.before_source_identity);
+  const after = input.after_observation ? parseRiddleProofObservationReceipt(input.after_observation) : observationForReceiptSide("after", input.after_result, input.after_source, input.after_source_identity);
+  const verdict = changeReceiptVerdict(input.result.status);
+  const shippingAuthorization = input.shipping_authorization || noShippingAuthorization();
+  assertShippingAuthorizationConsistent(shippingAuthorization, "Change receipt");
   return {
     version: RIDDLE_PROOF_CHANGE_RECEIPT_VERSION,
     contract_name: input.result.contract_name,
     profile_name: input.profile_name,
     status: input.result.status,
-    verdict: changeReceiptVerdict(input.result.status),
+    verdict,
     summary: input.result.summary,
-    before: receiptSide("before", input.before_source, input.before_result),
-    after: receiptSide("after", input.after_source, input.after_result),
+    before,
+    after,
+    groups: input.result.groups,
+    source_bindings: input.result.source_bindings,
     deltas: input.result.deltas.map((delta) => ({
       type: delta.type,
       label: delta.label,
@@ -20210,17 +20675,201 @@ function createRiddleProofChangeReceipt(input) {
       after_observed: delta.after_observed,
       message: delta.message
     })),
+    recommendation: changeRecommendation(verdict),
+    shipping_authorization: shippingAuthorization,
     proves: metadataStringList(input.contract.metadata, "required_receipts"),
     does_not_prove: metadataStringList(input.contract.metadata, "does_not_prove"),
     metadata: input.result.metadata
   };
 }
+function isRecord4(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 (!isRecord4(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 (!isRecord4(value) || value.version !== RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION) {
+    throw new Error(`Unsupported Handoff receipt version ${String(isRecord4(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 markdownTableCell(value) {
   return String(value ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
 }
 function artifactTarget(artifact) {
   return artifact.url || artifact.path;
 }
+function observationArtifactKind(artifact) {
+  if (artifact.role === "canonical_screenshot" || artifact.role === "setup_screenshot" || artifact.kind === "image") return "image";
+  if (artifact.role === "data" || /\.(json|md|txt|html|log|har)(\?|#|$)/i.test(artifact.name)) return "data";
+  return "artifact";
+}
+function receiptSideView(side, observation) {
+  const artifacts = observation.artifacts.map((artifact) => ({
+    side,
+    name: artifact.name,
+    kind: observationArtifactKind(artifact),
+    url: artifact.url,
+    path: artifact.path,
+    source: artifact.source
+  }));
+  const summary = observation.profile_summary;
+  const canonical = observation.canonical_screenshot;
+  const screenshots = artifacts.filter(artifactIsScreenshot);
+  if (canonical) {
+    const canonicalTarget = canonical.url || canonical.path;
+    screenshots.sort((left, right) => {
+      const leftCanonical = (left.url || left.path) === canonicalTarget || left.name === canonical.name;
+      const rightCanonical = (right.url || right.path) === canonicalTarget || right.name === canonical.name;
+      return Number(rightCanonical) - Number(leftCanonical);
+    });
+  }
+  return {
+    side,
+    source: observation.target.url,
+    profile_name: summary?.profile_name || observation.proof?.profile_name || "profile",
+    status: summary?.status || observation.proof?.result.status || "proof_insufficient",
+    summary: summary?.summary || observation.proof?.result.summary || "No profile summary recorded.",
+    route: summary?.route,
+    captured_at: observation.captured_at,
+    checks: summary?.checks || (observation.proof ? profileCheckCounts2(observation.proof.result) : {
+      total: 0,
+      passed: 0,
+      failed: 0,
+      skipped: 0,
+      needs_human_review: 0
+    }),
+    screenshots,
+    artifacts
+  };
+}
 function markdownLink(label, target) {
   return `[${label.replace(/\]/g, "\\]")}](${target})`;
 }
@@ -20244,6 +20893,8 @@ function appendMarkdownArtifacts(lines, title, artifacts) {
   lines.push("");
 }
 function riddleProofChangeReceiptMarkdown(receipt) {
+  const before = receiptSideView("before", receipt.before);
+  const after = receiptSideView("after", receipt.after);
   const lines = [
     "# Riddle Proof Change Receipt",
     "",
@@ -20251,6 +20902,8 @@ function riddleProofChangeReceiptMarkdown(receipt) {
     `**Status:** ${receipt.status}`,
     `**Contract:** ${receipt.contract_name}`,
     receipt.profile_name ? `**Profile:** ${receipt.profile_name}` : "",
+    `**Recommendation:** ${receipt.recommendation.label}`,
+    `**Shipping authorization:** ${receipt.shipping_authorization.status}`,
     "",
     receipt.summary,
     "",
@@ -20258,8 +20911,15 @@ function riddleProofChangeReceiptMarkdown(receipt) {
     "",
     "| Side | Source | Status | Checks |",
     "| --- | --- | --- | --- |",
-    `| Before | ${markdownTableCell(receipt.before.source)} | ${receipt.before.status} | ${receipt.before.checks.passed} passed / ${receipt.before.checks.failed} failed |`,
-    `| After | ${markdownTableCell(receipt.after.source)} | ${receipt.after.status} | ${receipt.after.checks.passed} passed / ${receipt.after.checks.failed} failed |`,
+    `| Before | ${markdownTableCell(before.source)} | ${before.status}${receipt.groups.before.ok ? " (matched baseline)" : " (baseline mismatch)"} | ${before.checks.passed} passed / ${before.checks.failed} failed |`,
+    `| After | ${markdownTableCell(after.source)} | ${after.status} | ${after.checks.passed} passed / ${after.checks.failed} failed |`,
+    "",
+    "## Source Binding",
+    "",
+    "| Side | Status | Git revision | Preview | Digest |",
+    "| --- | --- | --- | --- | --- |",
+    `| Before | ${receipt.source_bindings.before.status} | ${markdownTableCell(receipt.source_bindings.before.observed_git_revision || "not recorded")} | ${markdownTableCell(receipt.source_bindings.before.preview_id || "not required")} | ${markdownTableCell(receipt.source_bindings.before.content_digest || "not required")} |`,
+    `| After | ${receipt.source_bindings.after.status} | ${markdownTableCell(receipt.source_bindings.after.observed_git_revision || "not recorded")} | ${markdownTableCell(receipt.source_bindings.after.preview_id || "not required")} | ${markdownTableCell(receipt.source_bindings.after.content_digest || "not required")} |`,
     "",
     "## Delta Checks",
     "",
@@ -20271,8 +20931,8 @@ function riddleProofChangeReceiptMarkdown(receipt) {
     if (delta.message) lines.push(`| ${markdownTableCell(`${delta.label} message`)} | ${markdownTableCell(delta.message)} |  |  |`);
   }
   lines.push("");
-  appendMarkdownArtifacts(lines, "Before Screenshot", receipt.before.screenshots);
-  appendMarkdownArtifacts(lines, "After Screenshot", receipt.after.screenshots);
+  appendMarkdownArtifacts(lines, "Before Canonical Screenshot", before.screenshots.slice(0, 1));
+  appendMarkdownArtifacts(lines, "After Canonical Screenshot", after.screenshots.slice(0, 1));
   if (receipt.proves.length) {
     lines.push("## What This Proves", "");
     for (const claim of receipt.proves) lines.push(`- ${claim}`);
@@ -20283,7 +20943,7 @@ function riddleProofChangeReceiptMarkdown(receipt) {
     for (const claim of receipt.does_not_prove) lines.push(`- ${claim}`);
     lines.push("");
   }
-  const linkedArtifacts = [...receipt.before.artifacts, ...receipt.after.artifacts].filter((artifact) => artifactTarget(artifact)).slice(0, 24);
+  const linkedArtifacts = [...before.artifacts, ...after.artifacts].filter((artifact) => artifactTarget(artifact)).slice(0, 24);
   if (linkedArtifacts.length) {
     lines.push("## Artifacts", "");
     for (const artifact of linkedArtifacts) {
@@ -20315,7 +20975,9 @@ function htmlList(items, emptyText) {
   return `<ul>${items.map((item) => `<li>${escapeHtml(item)}</li>`).join("")}</ul>`;
 }
 function riddleProofChangeReceiptHtml(receipt) {
-  const artifactLinks = [...receipt.before.artifacts, ...receipt.after.artifacts].filter((artifact) => artifactTarget(artifact)).slice(0, 32);
+  const before = receiptSideView("before", receipt.before);
+  const after = receiptSideView("after", receipt.after);
+  const artifactLinks = [...before.artifacts, ...after.artifacts].filter((artifact) => artifactTarget(artifact)).slice(0, 32);
   const deltaRows = receipt.deltas.map((delta) => `
       <tr>
         <td>${escapeHtml(delta.label)}</td>
@@ -20363,26 +21025,37 @@ function riddleProofChangeReceiptHtml(receipt) {
     <h1>${escapeHtml(receipt.contract_name)}</h1>
     <p>${escapeHtml(receipt.summary)}</p>
     <p class="muted">Status: ${escapeHtml(receipt.status)}${receipt.profile_name ? ` | Profile: ${escapeHtml(receipt.profile_name)}` : ""}</p>
+    <p>${escapeHtml(receipt.recommendation.label)}. Shipping authorization: ${escapeHtml(receipt.shipping_authorization.status)}.</p>
   </header>
   <section>
     <h2>Evidence Pair</h2>
     <div class="grid">
       <div class="side">
         <h3>Before</h3>
-        <p><code>${escapeHtml(receipt.before.source)}</code></p>
-        <p>Status: <strong class="${escapeHtml(receipt.before.status)}">${escapeHtml(receipt.before.status)}</strong></p>
-        <p>${escapeHtml(receipt.before.summary)}</p>
-        <p class="muted">${receipt.before.checks.passed} passed / ${receipt.before.checks.failed} failed checks</p>
+        <p><code>${escapeHtml(before.source)}</code></p>
+        <p>Status: <strong class="${escapeHtml(before.status)}">${escapeHtml(before.status)}</strong>${receipt.groups.before.ok ? " (matched baseline)" : " (baseline mismatch)"}</p>
+        <p>${escapeHtml(before.summary)}</p>
+        <p class="muted">${before.checks.passed} passed / ${before.checks.failed} failed checks</p>
       </div>
       <div class="side">
         <h3>After</h3>
-        <p><code>${escapeHtml(receipt.after.source)}</code></p>
-        <p>Status: <strong class="${escapeHtml(receipt.after.status)}">${escapeHtml(receipt.after.status)}</strong></p>
-        <p>${escapeHtml(receipt.after.summary)}</p>
-        <p class="muted">${receipt.after.checks.passed} passed / ${receipt.after.checks.failed} failed checks</p>
+        <p><code>${escapeHtml(after.source)}</code></p>
+        <p>Status: <strong class="${escapeHtml(after.status)}">${escapeHtml(after.status)}</strong></p>
+        <p>${escapeHtml(after.summary)}</p>
+        <p class="muted">${after.checks.passed} passed / ${after.checks.failed} failed checks</p>
       </div>
     </div>
   </section>
+  <section>
+    <h2>Source Binding</h2>
+    <table>
+      <thead><tr><th>Side</th><th>Status</th><th>Git revision</th><th>Preview</th><th>Digest</th></tr></thead>
+      <tbody>
+        <tr><td>Before</td><td>${escapeHtml(receipt.source_bindings.before.status)}</td><td>${escapeHtml(receipt.source_bindings.before.observed_git_revision || "not recorded")}</td><td>${escapeHtml(receipt.source_bindings.before.preview_id || "not required")}</td><td>${escapeHtml(receipt.source_bindings.before.content_digest || "not required")}</td></tr>
+        <tr><td>After</td><td>${escapeHtml(receipt.source_bindings.after.status)}</td><td>${escapeHtml(receipt.source_bindings.after.observed_git_revision || "not recorded")}</td><td>${escapeHtml(receipt.source_bindings.after.preview_id || "not required")}</td><td>${escapeHtml(receipt.source_bindings.after.content_digest || "not required")}</td></tr>
+      </tbody>
+    </table>
+  </section>
   <section>
     <h2>Delta Checks</h2>
     <table>
@@ -20393,8 +21066,8 @@ function riddleProofChangeReceiptHtml(receipt) {
   <section>
     <h2>Screenshots</h2>
     <div class="grid">
-      <div>${receipt.before.screenshots.slice(0, 4).map(htmlArtifactCard).join("") || `<p class="muted">No before screenshots recorded.</p>`}</div>
-      <div>${receipt.after.screenshots.slice(0, 4).map(htmlArtifactCard).join("") || `<p class="muted">No after screenshots recorded.</p>`}</div>
+      <div>${before.screenshots.slice(0, 1).map(htmlArtifactCard).join("") || `<p class="muted">No canonical before screenshot recorded.</p>`}</div>
+      <div>${after.screenshots.slice(0, 1).map(htmlArtifactCard).join("") || `<p class="muted">No canonical after screenshot recorded.</p>`}</div>
     </div>
   </section>
   <section>
@@ -20481,6 +21154,7 @@ async function getRiddleBalance(config = {}) {
 }
 function previewDeployResultFromRecord(input) {
   const { record, id, label, framework, expiresAt, publishRecovered, publishError } = input;
+  const receipt = record.receipt && typeof record.receipt === "object" ? parseRiddlePreviewReceipt(record.receipt) : void 0;
   return {
     ok: true,
     id: String(record.id || record.preview_id || id),
@@ -20489,13 +21163,32 @@ function previewDeployResultFromRecord(input) {
     preview_url: String(record.preview_url || ""),
     file_count: typeof record.file_count === "number" ? record.file_count : void 0,
     total_bytes: typeof record.total_bytes === "number" ? record.total_bytes : void 0,
-    expires_at: expiresAt,
+    expires_at: receipt?.expires_at || expiresAt,
+    receipt,
     publish_recovered: publishRecovered || void 0,
     publish_error: publishError,
     warnings: input.warnings?.length ? input.warnings : void 0,
     raw: record
   };
 }
+function gitOutput(directory, args) {
+  try {
+    return (0, import_node_child_process4.execFileSync)("git", ["-C", directory, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function detectRiddlePreviewSource(directory) {
+  const gitRevision = gitOutput(directory, ["rev-parse", "HEAD"]);
+  if (!gitRevision) return {};
+  const repository = gitOutput(directory, ["config", "--get", "remote.origin.url"]);
+  const status = gitOutput(directory, ["status", "--porcelain", "--untracked-files=normal"]);
+  return {
+    git_revision: gitRevision,
+    repository: repository || void 0,
+    dirty: Boolean(status)
+  };
+}
 function canRecoverPreviewPublish(error) {
   return error instanceof RiddleApiError && PREVIEW_PUBLISH_RECOVERY_STATUSES.has(error.status);
 }
@@ -20578,12 +21271,13 @@ async function waitForPublishedPreview(config, input) {
   }
   throw input.publishError;
 }
-async function deployRiddlePreview(config, directory, label, framework = "static") {
+async function deployRiddlePreview(config, directory, label, framework = "static", options = {}) {
   if (!directory?.trim()) throw new Error("directory is required");
   if (!label?.trim()) throw new Error("label is required");
   if (framework !== "spa" && framework !== "static") throw new Error("framework must be spa or static");
   const startedAt = Date.now();
   const warnings = collectRiddlePreviewDeployWarnings(directory, framework);
+  const source = options.source || detectRiddlePreviewSource(directory);
   const emitProgress = previewProgressEmitter(config, { label, framework, directory, startedAt, warnings });
   await emitProgress({ stage: "validating", message: "checking preview input directory" });
   const localSummary = summarizePreviewDirectory(directory);
@@ -20595,7 +21289,7 @@ async function deployRiddlePreview(config, directory, label, framework = "static
   });
   const created = await riddleRequestJson(config, "/v1/preview", {
     method: "POST",
-    body: JSON.stringify({ framework, label })
+    body: JSON.stringify({ framework, label, source })
   });
   const id = String(created.id || "");
   const uploadUrl = String(created.upload_url || "");
@@ -20737,8 +21431,8 @@ function collectRiddlePreviewDeployWarnings(directory, framework = "static") {
     return [];
   }
 }
-async function deployRiddleStaticPreview(config, directory, label) {
-  return deployRiddlePreview(config, directory, label, "static");
+async function deployRiddleStaticPreview(config, directory, label, options = {}) {
+  return deployRiddlePreview(config, directory, label, "static", options);
 }
 function createTarball(directory, label, exclude = []) {
   const scratch = (0, import_node_fs5.mkdtempSync)(import_node_path5.default.join((0, import_node_os2.tmpdir)(), "riddle-upload-"));
@@ -20860,21 +21554,31 @@ function parseTimestampMs(value) {
 }
 function buildPollSnapshot(jobId, job, input) {
   const status = job?.status ? String(job.status) : null;
+  const phase = job?.phase ? String(job.phase) : null;
   const terminal = isTerminalRiddleJobStatus(status);
   const createdAt = stringField(job, "created_at");
   const submittedAt = stringField(job, "submitted_at");
   const completedAt = stringField(job, "completed_at");
   const createdMs = parseTimestampMs(createdAt);
   const submittedMs = parseTimestampMs(submittedAt);
+  const rawExecution = job?.execution && typeof job.execution === "object" && !Array.isArray(job.execution) ? job.execution : null;
+  const enqueuedAt = rawExecution ? stringField(rawExecution, "enqueued_at") : null;
+  const enqueuedMs = parseTimestampMs(enqueuedAt);
+  const queueStartedMs = enqueuedMs ?? createdMs;
+  const claimedAt = rawExecution ? stringField(rawExecution, "claimed_at") : null;
+  const claimedMs = parseTimestampMs(claimedAt);
   let queueElapsedMs = null;
-  if (createdMs !== null && submittedMs !== null) {
-    queueElapsedMs = Math.max(0, submittedMs - createdMs);
-  } else if (createdMs !== null && !submittedAt && !terminal) {
-    queueElapsedMs = Math.max(0, input.observedAt - createdMs);
+  if (queueStartedMs !== null && claimedMs !== null) {
+    queueElapsedMs = Math.max(0, claimedMs - queueStartedMs);
+  } else if (queueStartedMs !== null && submittedMs !== null) {
+    queueElapsedMs = Math.max(0, submittedMs - queueStartedMs);
+  } else if (queueStartedMs !== null && !submittedAt && !terminal) {
+    queueElapsedMs = Math.max(0, input.observedAt - queueStartedMs);
   }
   return {
     job_id: jobId,
     status,
+    phase,
     terminal,
     attempt: input.attempt,
     attempts: input.attempts,
@@ -20884,7 +21588,9 @@ function buildPollSnapshot(jobId, job, input) {
     completed_at: completedAt,
     queue_elapsed_ms: queueElapsedMs,
     pre_submission_elapsed_ms: Math.max(0, Math.floor(input.preSubmissionElapsedMs ?? 0)),
-    running_without_submission: Boolean(status && !terminal && !submittedAt)
+    running_without_submission: Boolean(status && !terminal && !submittedAt),
+    active_execution: Boolean(status === "running" && phase && phase !== "queued"),
+    execution: rawExecution ? rawExecution : void 0
   };
 }
 function pollMessage(snapshot, timedOut) {
@@ -20893,7 +21599,7 @@ function pollMessage(snapshot, timedOut) {
   const wakeHint = snapshot.running_without_submission && !snapshot.created_at && !snapshot.submitted_at ? ` ${RIDDLE_UNSUBMITTED_WAKE_HINT}.` : "";
   const queue = snapshot.queue_elapsed_ms !== null ? ` queue_elapsed_ms=${snapshot.queue_elapsed_ms}` : "";
   const preSubmit = snapshot.pre_submission_elapsed_ms > 0 ? ` pre_submission_elapsed_ms=${snapshot.pre_submission_elapsed_ms}` : "";
-  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} submitted_at=${submitted}.${wakeHint}${queue}${preSubmit}`;
+  return `Riddle job ${snapshot.job_id} did not reach a terminal status after ${snapshot.attempt} poll attempts; status=${snapshot.status || "unknown"} phase=${snapshot.phase || "unknown"} submitted_at=${submitted}.${wakeHint}${queue}${preSubmit}`;
 }
 async function pollRiddleJob(config, jobId, options = {}) {
   if (!jobId?.trim()) throw new Error("jobId is required");
@@ -20927,6 +21633,7 @@ async function pollRiddleJob(config, jobId, options = {}) {
     };
     const progressKey = [
       lastSnapshot.status || "unknown",
+      lastSnapshot.phase || "unknown",
       lastSnapshot.terminal ? "terminal" : "nonterminal",
       lastSnapshot.submitted_at ? "submitted" : "unsubmitted"
     ].join(":");
@@ -20993,8 +21700,8 @@ function createRiddleApiClient(config = {}) {
     apiKeySource: () => resolveRiddleApiKeySource(config),
     requestJson: (pathname, init) => riddleRequestJson(config, pathname, init),
     getBalance: () => getRiddleBalance(config),
-    deployPreview: (directory, label, framework = "static") => deployRiddlePreview(config, directory, label, framework),
-    deployStaticPreview: (directory, label) => deployRiddleStaticPreview(config, directory, label),
+    deployPreview: (directory, label, framework = "static", options) => deployRiddlePreview(config, directory, label, framework, options),
+    deployStaticPreview: (directory, label, options) => deployRiddleStaticPreview(config, directory, label, options),
     runScript: (input) => runRiddleScript(config, input),
     runServerPreview: (input) => runRiddleServerPreview(config, input),
     pollJob: (jobId, options) => pollRiddleJob(config, jobId, options)
@@ -21025,7 +21732,7 @@ function firstStringValue2(...values) {
   }
   return void 0;
 }
-function artifactKind2(name, url) {
+function artifactKind(name, url) {
   const target = `${name} ${url}`.toLowerCase();
   if (/\.(png|jpe?g|gif|webp|avif|svg)(\?|#|$)/.test(target)) return "image";
   if (/\.(json|har|txt|md|html|log)(\?|#|$)/.test(target)) return "data";
@@ -21050,7 +21757,7 @@ function collectArtifacts(runResponse) {
     artifacts.push({
       name,
       url,
-      kind: artifactKind2(name, url),
+      kind: artifactKind(name, url),
       size_bytes: numberValue5(artifact.size)
     });
   }
@@ -21070,7 +21777,7 @@ function collectProfileArtifacts(result) {
     artifacts.push({
       name,
       url,
-      kind: artifactKind2(name, url),
+      kind: artifactKind(name, url),
       size_bytes: numberValue5(artifact.size_bytes) ?? numberValue5(artifact.size)
     });
   }
@@ -21081,9 +21788,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 = stringValue7(artifact.url) || stringValue7(artifact.path);
@@ -21094,7 +21802,7 @@ function collectChangeReceiptArtifacts(result) {
       artifacts.push({
         name,
         url,
-        kind: artifactKind2(name, url),
+        kind: artifactKind(name, url),
         size_bytes: numberValue5(artifact.size_bytes) ?? numberValue5(artifact.size)
       });
     }
@@ -21129,7 +21837,7 @@ function pageSummaries(result) {
   }
   return pages;
 }
-function profileCheckCounts2(result) {
+function profileCheckCounts3(result) {
   const checks = asArray(result.checks);
   if (checks.length) {
     let passed2 = 0;
@@ -21175,9 +21883,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: numberValue5(checks.passed) ?? 0,
       failed: numberValue5(checks.failed) ?? 0
     });
@@ -21240,7 +21949,11 @@ function isProfileResult(result) {
   return version === "riddle-proof.profile-result.v1" || version === "riddle-proof.profile-compact-result.v1";
 }
 function isChangeReceiptResult(result) {
-  return stringValue7(result.version) === "riddle-proof.change-receipt.v1";
+  const version = stringValue7(result.version);
+  return version === RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION || version === RIDDLE_PROOF_CHANGE_RECEIPT_VERSION;
+}
+function isHandoffReceiptResult(result) {
+  return stringValue7(result.version) === RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION;
 }
 function isChangeResult(result) {
   const version = stringValue7(result.version);
@@ -21248,10 +21961,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);
@@ -21260,7 +21976,7 @@ function summarizeRiddleProofPrComment(input) {
   const resultDetails = asRecord2(result.details);
   const resultRaw = asRecord2(result.raw);
   const rawDetails = asRecord2(resultRaw.details);
-  const profileChecks = profileResult ? profileCheckCounts2(result) : void 0;
+  const profileChecks = profileResult ? profileCheckCounts3(result) : void 0;
   const changeChecks = changeResult ? changeReceiptCheckCounts(result) : void 0;
   const artifacts = mergeArtifacts(
     collectArtifacts(runResponse),
@@ -21272,7 +21988,7 @@ function summarizeRiddleProofPrComment(input) {
   delete checkSource.ok;
   const nestedChecks = summarizeExplicitChecks(checkSource);
   const resultStatus = firstStringValue2(result.status, stopCondition.status);
-  const ok = changeResult ? resultStatus === "passed" : booleanValue3(result.ok) ?? booleanValue3(runResponse.ok) ?? null;
+  const ok = changeReceiptResult ? parsedChangeReceipt?.recommendation.merge_recommended ?? false : changeResult ? resultStatus === "passed" : booleanValue3(result.ok) ?? booleanValue3(runResponse.ok) ?? null;
   const checkpointSummary = checkpointSummaryFrom2(
     result.checkpoint_summary,
     stopCondition.checkpoint_summary,
@@ -21280,19 +21996,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: numberValue5(proofResult.duration_ms) ?? numberValue5(profileRiddle.elapsed_ms),
     proof_url: stringValue7(runResponse.proofUrl),
@@ -21300,13 +22016,13 @@ function summarizeRiddleProofPrComment(input) {
     preview_url: stringValue7(preview.preview_url) || stringValue7(preview.url),
     preview_publish_recovered: booleanValue3(preview.publish_recovered),
     preview_publish_error: stringValue7(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 ? stringValue7(result.verdict) : mergeRecommendation,
+    merge_recommendation: changeReceiptResult ? parsedChangeReceipt?.recommendation.label : mergeRecommendation,
     checkpoint_summary: checkpointSummary,
     public_state: publicState,
     passed_checks: changeChecks?.passed ?? profileChecks?.passed ?? nestedChecks.passed,
@@ -21374,7 +22090,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}: ${markdownLink2(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 = [
@@ -21450,16 +22247,20 @@ function buildRiddleProofPrCommentMarkdown(input) {
   DEFAULT_DIAGNOSTIC_STRING_LIMIT,
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
+  RIDDLE_PREVIEW_RECEIPT_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_CATCH_VERSION,
   RIDDLE_PROOF_BASIC_GAMEPLAY_VERSION,
   RIDDLE_PROOF_CAPTURE_DIAGNOSTIC_VERSION,
   RIDDLE_PROOF_CHANGE_CONTRACT_VERSION,
+  RIDDLE_PROOF_CHANGE_RECEIPT_V1_VERSION,
   RIDDLE_PROOF_CHANGE_RECEIPT_VERSION,
   RIDDLE_PROOF_CHANGE_RESULT_VERSION,
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
+  RIDDLE_PROOF_HANDOFF_RECEIPT_VERSION,
   RIDDLE_PROOF_HOSTED_PROFILE_ARTIFACTS,
+  RIDDLE_PROOF_OBSERVATION_RECEIPT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_ASSESSMENT_VERSION,
   RIDDLE_PROOF_PLAYABILITY_VERSION,
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
@@ -21498,6 +22299,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   buildAuthorCheckpointPacket,
   buildCheckpointPacketForEngineResult,
   buildProofAssessmentCheckpointPacket,
+  buildRiddleProofHandoffPrCommentMarkdown,
   buildRiddleProofPrCommentMarkdown,
   buildRiddleProofProfileScript,
   buildStageCheckpointPacket,
@@ -21522,6 +22324,8 @@ function buildRiddleProofPrCommentMarkdown(input) {
   createLocalAgentJsonRunner,
   createRiddleApiClient,
   createRiddleProofChangeReceipt,
+  createRiddleProofHandoffReceipt,
+  createRiddleProofObservationReceipt,
   createRiddleProofProfileConfigurationError,
   createRiddleProofProfileEnvironmentBlockedResult,
   createRiddleProofProfileInsufficientResult,
@@ -21532,6 +22336,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   deployRiddlePreview,
   deployRiddleStaticPreview,
   deriveRiddleProofArtifactBodyAssertions,
+  detectRiddlePreviewSource,
   extractBasicGameplayEvidence,
   extractPlayabilityEvidence,
   extractRiddleProofProfileResult,
@@ -21542,6 +22347,7 @@ function buildRiddleProofPrCommentMarkdown(input) {
   isSuccessfulStatus,
   isTerminalRiddleJobStatus,
   isTerminalStatus,
+  migrateRiddleProofChangeReceipt,
   nonEmptyString,
   normalizeCheckpointResponse,
   normalizeIntegrationContext,
@@ -21549,6 +22355,10 @@ function buildRiddleProofPrCommentMarkdown(input) {
   normalizeRiddleProofProfile,
   normalizeRunParams,
   normalizeTerminalMetadata,
+  parseRiddlePreviewReceipt,
+  parseRiddleProofChangeReceipt,
+  parseRiddleProofHandoffReceipt,
+  parseRiddleProofObservationReceipt,
   parseRiddleViewport,
   parseVisualProofSession,
   pollRiddleJob,