@riddledc/riddle-proof 0.5.42 → 0.5.44

package/dist/{chunk-U4VNN2CT.js → chunk-4ASMX4R6.js}

@@ -381,6 +381,21 @@ function visualDeltaShipGateReason(state = {}) {
   if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
   return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
 }
+function visualDeltaEvidenceIssueCode(state = {}, blocker = "") {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = String(visualDelta.status || "").trim();
+  const reason = `${String(visualDelta.reason || "")}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -570,7 +585,7 @@ var CHECKPOINT_CONTRACT_SPECS = {
       description: "JSON assessment with decision, summary, recommended_stage, continue_with_stage, escalation_target, and reasons."
     }],
     response_schema: {
-      decision: ["ready_to_ship", "needs_richer_proof"],
+      decision: ["ready_to_ship", "needs_richer_proof", "revise_capture"],
       summary: "string",
       recommended_stage: ["ship", "author", "implement", "recon", "verify"],
       continue_with_stage: ["ship", "author", "implement", "recon", "verify"],
@@ -773,9 +788,15 @@ function mergeStateFromParams(statePath, params) {
       const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
       if (readyBlocker) {
         assessment.blocked_decision = assessment.decision;
-        assessment.decision = "needs_richer_proof";
-        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
-        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        assessment.decision = "revise_capture";
+        assessment.recommended_stage = "verify";
+        assessment.continue_with_stage = "verify";
+        assessment.evidence_collection_incomplete = true;
+        assessment.recovery_stage = "verify";
+        assessment.recovery_reason = readyBlocker;
+        assessment.evidence_issue_code = visualDeltaEvidenceIssueCode(state, readyBlocker);
+        assessment.visual_delta = visualDeltaForState(state);
+        assessment.suggested_repair = "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.";
         const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
         assessment.blockers = [...blockers, readyBlocker];
       }
@@ -794,7 +815,7 @@ function mergeStateFromParams(statePath, params) {
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
       if (readyBlocker) {
-        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+        appendProofSummaryLine(state, `Ready-to-ship assessment routed to evidence recovery: ${readyBlocker}`);
       }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);

package/dist/{chunk-VSLU6XNI.js → chunk-MJD37CLH.js}

@@ -25,8 +25,10 @@ import {
   recordValue
 } from "./chunk-W7VTDN4T.js";
 import {
+  visualDeltaForState,
+  visualDeltaRequiredForState,
   visualDeltaShipGateReason
-} from "./chunk-U4VNN2CT.js";
+} from "./chunk-4ASMX4R6.js";
 
 // src/engine-harness.ts
 import { execFileSync } from "child_process";
@@ -315,14 +317,36 @@ function proofAssessmentVisualBlocker(state, payload) {
     proof_assessment_source: source
   });
 }
-function blockedProofAssessmentPayload(payload, blocker) {
+function visualDeltaBlockerCode(state, blocker) {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = nonEmptyString(visualDelta.status);
+  const reason = `${nonEmptyString(visualDelta.reason) || ""}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
+function visualDeltaEvidenceRecoveryAssessment(state, payload, blocker) {
+  const visualDelta = visualDeltaForState(state || {});
   const blockers = Array.isArray(payload.blockers) ? payload.blockers.filter((item) => typeof item === "string") : [];
   return {
     ...payload,
     blocked_decision: payload.decision || "ready_to_ship",
-    decision: "needs_richer_proof",
-    recommended_stage: payload.recommended_stage === "ship" ? "verify" : payload.recommended_stage || "verify",
-    continue_with_stage: payload.continue_with_stage === "ship" ? "verify" : payload.continue_with_stage || "verify",
+    decision: "revise_capture",
+    recommended_stage: "verify",
+    continue_with_stage: "verify",
+    evidence_collection_incomplete: true,
+    recovery_stage: "verify",
+    recovery_reason: blocker,
+    evidence_issue_code: visualDeltaBlockerCode(state, blocker),
+    visual_delta: Object.keys(visualDelta).length ? visualDelta : null,
+    suggested_repair: "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.",
     blockers: [...blockers, blocker]
   };
 }
@@ -887,14 +911,24 @@ async function routeCheckpoint(request, state, result, agent, input) {
       verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
     }, payload);
     if (visualBlocker) {
+      const recoveryAssessment = visualDeltaEvidenceRecoveryAssessment({
+        ...context.fullRiddleState || {},
+        verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
+      }, payload, visualBlocker);
       recordEvent(state, {
-        kind: "agent.proof_assessment.blocked",
+        kind: "agent.proof_assessment.evidence_recovery_required",
         checkpoint,
         stage: "verify",
         summary: visualBlocker,
-        details: { payload }
+        details: compactRecord({
+          evidence_collection_incomplete: true,
+          recovery_stage: "verify",
+          evidence_issue_code: recoveryAssessment.evidence_issue_code || null,
+          visual_delta: recoveryAssessment.visual_delta || null,
+          proof_assessment: recoveryAssessment
+        })
       });
-      return { next: proofAssessmentContinuation(result, blockedProofAssessmentPayload(payload, visualBlocker)) };
+      return { next: proofAssessmentContinuation(result, recoveryAssessment) };
     }
     if (effectiveShipMode(request, input.config) !== "ship" && proofAssessmentRequestsShip(payload)) {
       return {

package/dist/{chunk-DWQK7J4U.js → chunk-XNRMMQAY.js}

@@ -96,14 +96,16 @@ function summarizeCaptureArtifacts(payload) {
   const record = isRecord(payload) ? payload : {};
   const artifactJson = isRecord(record._artifact_json) ? record._artifact_json : {};
   const proofJson = isRecord(record._proof_json) ? record._proof_json : isRecord(artifactJson["proof.json"]) ? artifactJson["proof.json"] : {};
+  const visualDiffJson = isRecord(record.visual_diff) ? record.visual_diff : isRecord(record.visualDiff) ? record.visualDiff : isRecord(artifactJson["visual-diff.json"]) ? artifactJson["visual-diff.json"] : {};
   const consoleJson = isRecord(record.console) ? record.console : isRecord(artifactJson["console.json"]) ? artifactJson["console.json"] : {};
   const result = isRecord(record.result) ? record.result : isRecord(proofJson.result) ? proofJson.result : isRecord(proofJson.script_result) ? proofJson.script_result : isRecord(proofJson.return_value) ? proofJson.return_value : isRecord(proofJson.value) ? proofJson.value : {};
   const consoleSummary = isRecord(consoleJson.summary) ? redactForProofDiagnostics(consoleJson.summary, { string_limit: 500 }) : void 0;
+  const resultKeys = /* @__PURE__ */ new Set([...sortedKeys(result), ...sortedKeys(visualDiffJson)]);
   return {
     outputs: artifactItems(record.outputs).slice(0, 20).map((item) => artifactSummary(item, "outputs")),
     screenshots: artifactItems(record.screenshots).slice(0, 10).map((item) => artifactSummary(item, "screenshots")),
     artifacts: artifactItems(record.artifacts).slice(0, 20).map((item) => artifactSummary(item, "artifacts")),
-    result_keys: sortedKeys(result),
+    result_keys: Array.from(resultKeys).sort(),
     artifact_json: sortedKeys(artifactJson),
     artifact_errors: artifactErrorMap(record._artifact_errors),
     proof_script_error: Boolean(proofJson.script_error),

package/dist/diagnostics.cjs

@@ -127,14 +127,16 @@ function summarizeCaptureArtifacts(payload) {
   const record = isRecord(payload) ? payload : {};
   const artifactJson = isRecord(record._artifact_json) ? record._artifact_json : {};
   const proofJson = isRecord(record._proof_json) ? record._proof_json : isRecord(artifactJson["proof.json"]) ? artifactJson["proof.json"] : {};
+  const visualDiffJson = isRecord(record.visual_diff) ? record.visual_diff : isRecord(record.visualDiff) ? record.visualDiff : isRecord(artifactJson["visual-diff.json"]) ? artifactJson["visual-diff.json"] : {};
   const consoleJson = isRecord(record.console) ? record.console : isRecord(artifactJson["console.json"]) ? artifactJson["console.json"] : {};
   const result = isRecord(record.result) ? record.result : isRecord(proofJson.result) ? proofJson.result : isRecord(proofJson.script_result) ? proofJson.script_result : isRecord(proofJson.return_value) ? proofJson.return_value : isRecord(proofJson.value) ? proofJson.value : {};
   const consoleSummary = isRecord(consoleJson.summary) ? redactForProofDiagnostics(consoleJson.summary, { string_limit: 500 }) : void 0;
+  const resultKeys = /* @__PURE__ */ new Set([...sortedKeys(result), ...sortedKeys(visualDiffJson)]);
   return {
     outputs: artifactItems(record.outputs).slice(0, 20).map((item) => artifactSummary(item, "outputs")),
     screenshots: artifactItems(record.screenshots).slice(0, 10).map((item) => artifactSummary(item, "screenshots")),
     artifacts: artifactItems(record.artifacts).slice(0, 20).map((item) => artifactSummary(item, "artifacts")),
-    result_keys: sortedKeys(result),
+    result_keys: Array.from(resultKeys).sort(),
     artifact_json: sortedKeys(artifactJson),
     artifact_errors: artifactErrorMap(record._artifact_errors),
     proof_script_error: Boolean(proofJson.script_error),

package/dist/diagnostics.js

@@ -7,7 +7,7 @@ import {
   createCaptureDiagnostic,
   redactForProofDiagnostics,
   summarizeCaptureArtifacts
-} from "./chunk-DWQK7J4U.js";
+} from "./chunk-XNRMMQAY.js";
 export {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,

package/dist/engine-harness.cjs

@@ -389,6 +389,21 @@ function visualDeltaShipGateReason(state = {}) {
   if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
   return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
 }
+function visualDeltaEvidenceIssueCode(state = {}, blocker = "") {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = String(visualDelta.status || "").trim();
+  const reason = `${String(visualDelta.reason || "")}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -613,9 +628,15 @@ function mergeStateFromParams(statePath, params) {
       const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
       if (readyBlocker) {
         assessment.blocked_decision = assessment.decision;
-        assessment.decision = "needs_richer_proof";
-        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
-        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        assessment.decision = "revise_capture";
+        assessment.recommended_stage = "verify";
+        assessment.continue_with_stage = "verify";
+        assessment.evidence_collection_incomplete = true;
+        assessment.recovery_stage = "verify";
+        assessment.recovery_reason = readyBlocker;
+        assessment.evidence_issue_code = visualDeltaEvidenceIssueCode(state, readyBlocker);
+        assessment.visual_delta = visualDeltaForState(state);
+        assessment.suggested_repair = "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.";
         const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
         assessment.blockers = [...blockers, readyBlocker];
       }
@@ -634,7 +655,7 @@ function mergeStateFromParams(statePath, params) {
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
       if (readyBlocker) {
-        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+        appendProofSummaryLine(state, `Ready-to-ship assessment routed to evidence recovery: ${readyBlocker}`);
       }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
@@ -908,7 +929,7 @@ var init_proof_run_core = __esm({
           description: "JSON assessment with decision, summary, recommended_stage, continue_with_stage, escalation_target, and reasons."
         }],
         response_schema: {
-          decision: ["ready_to_ship", "needs_richer_proof"],
+          decision: ["ready_to_ship", "needs_richer_proof", "revise_capture"],
           summary: "string",
           recommended_stage: ["ship", "author", "implement", "recon", "verify"],
           continue_with_stage: ["ship", "author", "implement", "recon", "verify"],
@@ -1713,10 +1734,10 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
   const primaryShipGateNextAction = (shipGate) => {
     const reasons = shipGate.reasons || [];
     if (reasons.some((reason) => reason.includes("proof_assessment"))) {
-      return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
+      return "resume with riddle_proof_review using decision=ready_to_ship only after screenshots, semantic evidence, and required comparison metrics prove the request; otherwise choose needs_implementation, revise_capture, or needs_richer_proof for the specific missing stage";
     }
     if (reasons.some((reason) => reason.includes("visual_delta"))) {
-      return "rerun verify with a measured before/after visual delta, or choose needs_richer_proof instead of ready_to_ship for this visual proof";
+      return "keep the run in verify/evidence recovery until a measured before/after visual_delta exists; choose revise_capture rather than ready_to_ship or generic needs_richer_proof for this visual proof";
     }
     if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
       return "rerun verify with stronger proof framing so after evidence is captured before shipping";
@@ -3692,14 +3713,36 @@ function proofAssessmentVisualBlocker(state, payload) {
     proof_assessment_source: source
   });
 }
-function blockedProofAssessmentPayload(payload, blocker) {
+function visualDeltaBlockerCode(state, blocker) {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = nonEmptyString(visualDelta.status);
+  const reason = `${nonEmptyString(visualDelta.reason) || ""}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
+function visualDeltaEvidenceRecoveryAssessment(state, payload, blocker) {
+  const visualDelta = visualDeltaForState(state || {});
   const blockers = Array.isArray(payload.blockers) ? payload.blockers.filter((item) => typeof item === "string") : [];
   return {
     ...payload,
     blocked_decision: payload.decision || "ready_to_ship",
-    decision: "needs_richer_proof",
-    recommended_stage: payload.recommended_stage === "ship" ? "verify" : payload.recommended_stage || "verify",
-    continue_with_stage: payload.continue_with_stage === "ship" ? "verify" : payload.continue_with_stage || "verify",
+    decision: "revise_capture",
+    recommended_stage: "verify",
+    continue_with_stage: "verify",
+    evidence_collection_incomplete: true,
+    recovery_stage: "verify",
+    recovery_reason: blocker,
+    evidence_issue_code: visualDeltaBlockerCode(state, blocker),
+    visual_delta: Object.keys(visualDelta).length ? visualDelta : null,
+    suggested_repair: "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.",
     blockers: [...blockers, blocker]
   };
 }
@@ -4264,14 +4307,24 @@ async function routeCheckpoint(request, state, result, agent, input) {
       verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
     }, payload);
     if (visualBlocker) {
+      const recoveryAssessment = visualDeltaEvidenceRecoveryAssessment({
+        ...context.fullRiddleState || {},
+        verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
+      }, payload, visualBlocker);
       recordEvent(state, {
-        kind: "agent.proof_assessment.blocked",
+        kind: "agent.proof_assessment.evidence_recovery_required",
         checkpoint,
         stage: "verify",
         summary: visualBlocker,
-        details: { payload }
+        details: compactRecord({
+          evidence_collection_incomplete: true,
+          recovery_stage: "verify",
+          evidence_issue_code: recoveryAssessment.evidence_issue_code || null,
+          visual_delta: recoveryAssessment.visual_delta || null,
+          proof_assessment: recoveryAssessment
+        })
       });
-      return { next: proofAssessmentContinuation(result, blockedProofAssessmentPayload(payload, visualBlocker)) };
+      return { next: proofAssessmentContinuation(result, recoveryAssessment) };
     }
     if (effectiveShipMode(request, input.config) !== "ship" && proofAssessmentRequestsShip(payload)) {
       return {

package/dist/engine-harness.js

@@ -2,11 +2,11 @@ import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-VSLU6XNI.js";
+} from "./chunk-MJD37CLH.js";
 import "./chunk-RI25RGQP.js";
 import "./chunk-7S7O3NKF.js";
 import "./chunk-W7VTDN4T.js";
-import "./chunk-U4VNN2CT.js";
+import "./chunk-4ASMX4R6.js";
 export {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,

package/dist/index.cjs

@@ -389,6 +389,21 @@ function visualDeltaShipGateReason(state = {}) {
   if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
   return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
 }
+function visualDeltaEvidenceIssueCode(state = {}, blocker = "") {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = String(visualDelta.status || "").trim();
+  const reason = `${String(visualDelta.reason || "")}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -613,9 +628,15 @@ function mergeStateFromParams(statePath, params) {
       const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
       if (readyBlocker) {
         assessment.blocked_decision = assessment.decision;
-        assessment.decision = "needs_richer_proof";
-        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
-        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        assessment.decision = "revise_capture";
+        assessment.recommended_stage = "verify";
+        assessment.continue_with_stage = "verify";
+        assessment.evidence_collection_incomplete = true;
+        assessment.recovery_stage = "verify";
+        assessment.recovery_reason = readyBlocker;
+        assessment.evidence_issue_code = visualDeltaEvidenceIssueCode(state, readyBlocker);
+        assessment.visual_delta = visualDeltaForState(state);
+        assessment.suggested_repair = "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.";
         const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
         assessment.blockers = [...blockers, readyBlocker];
       }
@@ -634,7 +655,7 @@ function mergeStateFromParams(statePath, params) {
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
       if (readyBlocker) {
-        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+        appendProofSummaryLine(state, `Ready-to-ship assessment routed to evidence recovery: ${readyBlocker}`);
       }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
@@ -908,7 +929,7 @@ var init_proof_run_core = __esm({
           description: "JSON assessment with decision, summary, recommended_stage, continue_with_stage, escalation_target, and reasons."
         }],
         response_schema: {
-          decision: ["ready_to_ship", "needs_richer_proof"],
+          decision: ["ready_to_ship", "needs_richer_proof", "revise_capture"],
           summary: "string",
           recommended_stage: ["ship", "author", "implement", "recon", "verify"],
           continue_with_stage: ["ship", "author", "implement", "recon", "verify"],
@@ -1713,10 +1734,10 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
   const primaryShipGateNextAction = (shipGate) => {
     const reasons = shipGate.reasons || [];
     if (reasons.some((reason) => reason.includes("proof_assessment"))) {
-      return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
+      return "resume with riddle_proof_review using decision=ready_to_ship only after screenshots, semantic evidence, and required comparison metrics prove the request; otherwise choose needs_implementation, revise_capture, or needs_richer_proof for the specific missing stage";
     }
     if (reasons.some((reason) => reason.includes("visual_delta"))) {
-      return "rerun verify with a measured before/after visual delta, or choose needs_richer_proof instead of ready_to_ship for this visual proof";
+      return "keep the run in verify/evidence recovery until a measured before/after visual_delta exists; choose revise_capture rather than ready_to_ship or generic needs_richer_proof for this visual proof";
     }
     if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
       return "rerun verify with stronger proof framing so after evidence is captured before shipping";
@@ -4270,14 +4291,36 @@ function proofAssessmentVisualBlocker(state, payload) {
     proof_assessment_source: source
   });
 }
-function blockedProofAssessmentPayload(payload, blocker) {
+function visualDeltaBlockerCode(state, blocker) {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = nonEmptyString(visualDelta.status);
+  const reason = `${nonEmptyString(visualDelta.reason) || ""}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
+function visualDeltaEvidenceRecoveryAssessment(state, payload, blocker) {
+  const visualDelta = visualDeltaForState(state || {});
   const blockers = Array.isArray(payload.blockers) ? payload.blockers.filter((item) => typeof item === "string") : [];
   return {
     ...payload,
     blocked_decision: payload.decision || "ready_to_ship",
-    decision: "needs_richer_proof",
-    recommended_stage: payload.recommended_stage === "ship" ? "verify" : payload.recommended_stage || "verify",
-    continue_with_stage: payload.continue_with_stage === "ship" ? "verify" : payload.continue_with_stage || "verify",
+    decision: "revise_capture",
+    recommended_stage: "verify",
+    continue_with_stage: "verify",
+    evidence_collection_incomplete: true,
+    recovery_stage: "verify",
+    recovery_reason: blocker,
+    evidence_issue_code: visualDeltaBlockerCode(state, blocker),
+    visual_delta: Object.keys(visualDelta).length ? visualDelta : null,
+    suggested_repair: "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.",
     blockers: [...blockers, blocker]
   };
 }
@@ -4842,14 +4885,24 @@ async function routeCheckpoint(request, state, result, agent, input) {
       verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
     }, payload);
     if (visualBlocker) {
+      const recoveryAssessment = visualDeltaEvidenceRecoveryAssessment({
+        ...context.fullRiddleState || {},
+        verification_mode: context.fullRiddleState?.verification_mode || request.verification_mode
+      }, payload, visualBlocker);
       recordEvent(state, {
-        kind: "agent.proof_assessment.blocked",
+        kind: "agent.proof_assessment.evidence_recovery_required",
         checkpoint,
         stage: "verify",
         summary: visualBlocker,
-        details: { payload }
+        details: compactRecord({
+          evidence_collection_incomplete: true,
+          recovery_stage: "verify",
+          evidence_issue_code: recoveryAssessment.evidence_issue_code || null,
+          visual_delta: recoveryAssessment.visual_delta || null,
+          proof_assessment: recoveryAssessment
+        })
       });
-      return { next: proofAssessmentContinuation(result, blockedProofAssessmentPayload(payload, visualBlocker)) };
+      return { next: proofAssessmentContinuation(result, recoveryAssessment) };
     }
     if (effectiveShipMode(request, input.config) !== "ship" && proofAssessmentRequestsShip(payload)) {
       return {
@@ -5172,14 +5225,16 @@ function summarizeCaptureArtifacts(payload) {
   const record = isRecord(payload) ? payload : {};
   const artifactJson = isRecord(record._artifact_json) ? record._artifact_json : {};
   const proofJson = isRecord(record._proof_json) ? record._proof_json : isRecord(artifactJson["proof.json"]) ? artifactJson["proof.json"] : {};
+  const visualDiffJson = isRecord(record.visual_diff) ? record.visual_diff : isRecord(record.visualDiff) ? record.visualDiff : isRecord(artifactJson["visual-diff.json"]) ? artifactJson["visual-diff.json"] : {};
   const consoleJson = isRecord(record.console) ? record.console : isRecord(artifactJson["console.json"]) ? artifactJson["console.json"] : {};
   const result = isRecord(record.result) ? record.result : isRecord(proofJson.result) ? proofJson.result : isRecord(proofJson.script_result) ? proofJson.script_result : isRecord(proofJson.return_value) ? proofJson.return_value : isRecord(proofJson.value) ? proofJson.value : {};
   const consoleSummary = isRecord(consoleJson.summary) ? redactForProofDiagnostics(consoleJson.summary, { string_limit: 500 }) : void 0;
+  const resultKeys = /* @__PURE__ */ new Set([...sortedKeys(result), ...sortedKeys(visualDiffJson)]);
   return {
     outputs: artifactItems(record.outputs).slice(0, 20).map((item) => artifactSummary(item, "outputs")),
     screenshots: artifactItems(record.screenshots).slice(0, 10).map((item) => artifactSummary(item, "screenshots")),
     artifacts: artifactItems(record.artifacts).slice(0, 20).map((item) => artifactSummary(item, "artifacts")),
-    result_keys: sortedKeys(result),
+    result_keys: Array.from(resultKeys).sort(),
     artifact_json: sortedKeys(artifactJson),
     artifact_errors: artifactErrorMap(record._artifact_errors),
     proof_script_error: Boolean(proofJson.script_error),

package/dist/index.js

@@ -20,12 +20,12 @@ import {
   createCaptureDiagnostic,
   redactForProofDiagnostics,
   summarizeCaptureArtifacts
-} from "./chunk-DWQK7J4U.js";
+} from "./chunk-XNRMMQAY.js";
 import {
   createDisabledRiddleProofAgentAdapter,
   readRiddleProofRunStatus,
   runRiddleProofEngineHarness
-} from "./chunk-VSLU6XNI.js";
+} from "./chunk-MJD37CLH.js";
 import {
   RIDDLE_PROOF_CHECKPOINT_PACKET_VERSION,
   RIDDLE_PROOF_CHECKPOINT_RESPONSE_VERSION,
@@ -67,7 +67,7 @@ import {
   extractPlayabilityEvidence,
   isRiddleProofPlayabilityMode
 } from "./chunk-NSWT3VSV.js";
-import "./chunk-U4VNN2CT.js";
+import "./chunk-4ASMX4R6.js";
 export {
   DEFAULT_DIAGNOSTIC_ARRAY_LIMIT,
   DEFAULT_DIAGNOSTIC_HISTORY_LIMIT,

package/dist/proof-run-core.cjs

@@ -440,6 +440,21 @@ function visualDeltaShipGateReason(state = {}) {
   if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
   return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
 }
+function visualDeltaEvidenceIssueCode(state = {}, blocker = "") {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = String(visualDelta.status || "").trim();
+  const reason = `${String(visualDelta.reason || "")}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -629,7 +644,7 @@ var CHECKPOINT_CONTRACT_SPECS = {
       description: "JSON assessment with decision, summary, recommended_stage, continue_with_stage, escalation_target, and reasons."
     }],
     response_schema: {
-      decision: ["ready_to_ship", "needs_richer_proof"],
+      decision: ["ready_to_ship", "needs_richer_proof", "revise_capture"],
       summary: "string",
       recommended_stage: ["ship", "author", "implement", "recon", "verify"],
       continue_with_stage: ["ship", "author", "implement", "recon", "verify"],
@@ -832,9 +847,15 @@ function mergeStateFromParams(statePath, params) {
       const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
       if (readyBlocker) {
         assessment.blocked_decision = assessment.decision;
-        assessment.decision = "needs_richer_proof";
-        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
-        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        assessment.decision = "revise_capture";
+        assessment.recommended_stage = "verify";
+        assessment.continue_with_stage = "verify";
+        assessment.evidence_collection_incomplete = true;
+        assessment.recovery_stage = "verify";
+        assessment.recovery_reason = readyBlocker;
+        assessment.evidence_issue_code = visualDeltaEvidenceIssueCode(state, readyBlocker);
+        assessment.visual_delta = visualDeltaForState(state);
+        assessment.suggested_repair = "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.";
         const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
         assessment.blockers = [...blockers, readyBlocker];
       }
@@ -853,7 +874,7 @@ function mergeStateFromParams(statePath, params) {
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
       if (readyBlocker) {
-        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+        appendProofSummaryLine(state, `Ready-to-ship assessment routed to evidence recovery: ${readyBlocker}`);
       }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);

package/dist/proof-run-core.js

@@ -24,7 +24,7 @@ import {
   visualDeltaShipGateReason,
   workflowFile,
   writeState
-} from "./chunk-U4VNN2CT.js";
+} from "./chunk-4ASMX4R6.js";
 export {
   BUNDLED_RIDDLE_PROOF_DIR,
   CHECKPOINT_CONTRACT_VERSION,

package/dist/proof-run-engine.cjs

@@ -422,6 +422,21 @@ function visualDeltaShipGateReason(state = {}) {
   if (reason) return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof: ${reason}`;
   return `visual_delta.status=${status} blocks ready_to_ship for visual/UI proof`;
 }
+function visualDeltaEvidenceIssueCode(state = {}, blocker = "") {
+  const visualDelta = visualDeltaForState(state || {});
+  const status = String(visualDelta.status || "").trim();
+  const reason = `${String(visualDelta.reason || "")}
+${blocker}`.toLowerCase();
+  if (status === "unmeasured") {
+    if (reason.includes("fetch") || reason.includes("allowlist") || reason.includes("registered domain") || reason.includes("high risk") || reason.includes("comparator")) {
+      return "comparator_fetch_blocked";
+    }
+    return "visual_delta_unmeasured";
+  }
+  if (status === "measured" && visualDelta.passed === false) return "semantic_proof_failed";
+  if (visualDeltaRequiredForState(state || {})) return "visual_delta_unmeasured";
+  return "semantic_proof_failed";
+}
 function requiredBaselineLabelsForState(state = {}) {
   const reference = normalizedReference(state);
   const labels = [];
@@ -611,7 +626,7 @@ var CHECKPOINT_CONTRACT_SPECS = {
       description: "JSON assessment with decision, summary, recommended_stage, continue_with_stage, escalation_target, and reasons."
     }],
     response_schema: {
-      decision: ["ready_to_ship", "needs_richer_proof"],
+      decision: ["ready_to_ship", "needs_richer_proof", "revise_capture"],
       summary: "string",
       recommended_stage: ["ship", "author", "implement", "recon", "verify"],
       continue_with_stage: ["ship", "author", "implement", "recon", "verify"],
@@ -814,9 +829,15 @@ function mergeStateFromParams(statePath, params) {
       const readyBlocker = assessment?.decision === "ready_to_ship" ? visualDeltaShipGateReason({ ...state, proof_assessment: assessment, proof_assessment_source: assessment.source }) : null;
       if (readyBlocker) {
         assessment.blocked_decision = assessment.decision;
-        assessment.decision = "needs_richer_proof";
-        if (assessment.recommended_stage === "ship") assessment.recommended_stage = "verify";
-        if (assessment.continue_with_stage === "ship") assessment.continue_with_stage = "verify";
+        assessment.decision = "revise_capture";
+        assessment.recommended_stage = "verify";
+        assessment.continue_with_stage = "verify";
+        assessment.evidence_collection_incomplete = true;
+        assessment.recovery_stage = "verify";
+        assessment.recovery_reason = readyBlocker;
+        assessment.evidence_issue_code = visualDeltaEvidenceIssueCode(state, readyBlocker);
+        assessment.visual_delta = visualDeltaForState(state);
+        assessment.suggested_repair = "Keep the same Riddle Proof run in evidence/comparison recovery: repair or retry the visual comparator/fetch path, wait for artifact readiness if applicable, or produce a measured visual_delta artifact before proof review can mark ready_to_ship.";
         const blockers = Array.isArray(assessment.blockers) ? assessment.blockers : [];
         assessment.blockers = [...blockers, readyBlocker];
       }
@@ -835,7 +856,7 @@ function mergeStateFromParams(statePath, params) {
       }
       appendProofSummaryLine(state, `Supervising proof assessment: ${state.proof_assessment.decision || "unknown"}`);
       if (readyBlocker) {
-        appendProofSummaryLine(state, `Ready-to-ship assessment blocked: ${readyBlocker}`);
+        appendProofSummaryLine(state, `Ready-to-ship assessment routed to evidence recovery: ${readyBlocker}`);
       }
       if (state.proof_assessment_summary) {
         appendProofSummaryLine(state, `Assessment summary: ${state.proof_assessment_summary}`);
@@ -1711,10 +1732,10 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
   const primaryShipGateNextAction = (shipGate) => {
     const reasons = shipGate.reasons || [];
     if (reasons.some((reason) => reason.includes("proof_assessment"))) {
-      return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
+      return "resume with riddle_proof_review using decision=ready_to_ship only after screenshots, semantic evidence, and required comparison metrics prove the request; otherwise choose needs_implementation, revise_capture, or needs_richer_proof for the specific missing stage";
     }
     if (reasons.some((reason) => reason.includes("visual_delta"))) {
-      return "rerun verify with a measured before/after visual delta, or choose needs_richer_proof instead of ready_to_ship for this visual proof";
+      return "keep the run in verify/evidence recovery until a measured before/after visual_delta exists; choose revise_capture rather than ready_to_ship or generic needs_richer_proof for this visual proof";
     }
     if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
       return "rerun verify with stronger proof framing so after evidence is captured before shipping";

package/dist/proof-run-engine.js

@@ -14,7 +14,7 @@ import {
   validateShipGate,
   workflowFile,
   writeState
-} from "./chunk-U4VNN2CT.js";
+} from "./chunk-4ASMX4R6.js";
 
 // src/proof-run-engine.ts
 import { execFileSync } from "child_process";
@@ -768,10 +768,10 @@ async function executeWorkflow(params, pluginConfig, resolvedConfig) {
   const primaryShipGateNextAction = (shipGate) => {
     const reasons = shipGate.reasons || [];
     if (reasons.some((reason) => reason.includes("proof_assessment"))) {
-      return "resume with riddle_proof_review using decision=ready_to_ship only after the screenshots and semantic evidence visibly prove the request; otherwise choose needs_implementation or needs_richer_proof";
+      return "resume with riddle_proof_review using decision=ready_to_ship only after screenshots, semantic evidence, and required comparison metrics prove the request; otherwise choose needs_implementation, revise_capture, or needs_richer_proof for the specific missing stage";
     }
     if (reasons.some((reason) => reason.includes("visual_delta"))) {
-      return "rerun verify with a measured before/after visual delta, or choose needs_richer_proof instead of ready_to_ship for this visual proof";
+      return "keep the run in verify/evidence recovery until a measured before/after visual_delta exists; choose revise_capture rather than ready_to_ship or generic needs_richer_proof for this visual proof";
     }
     if (reasons.some((reason) => reason.includes("after_cdn") || reason.includes("verify_status"))) {
       return "rerun verify with stronger proof framing so after evidence is captured before shipping";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riddledc/riddle-proof",
-  "version": "0.5.42",
+  "version": "0.5.44",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",

package/runtime/lib/author.py

@@ -154,6 +154,7 @@ def author_request_payload(state, reference, baselines, current_plan, hypothesis
             'For playable/gameplay proof, start the experience, send keyboard or pointer input, sample state before/after, measure non-HUD playfield/canvas pixel deltas across time, and set window.__riddleProofEvidence.playability or playability_evidence with version riddle-proof.playability.v1.',
             'For data/audio/log/metric/custom proof, screenshots are optional; set window.__riddleProofEvidence inside page.evaluate to a JSON-serializable object with the measured observations the verifier should judge.',
             'Do not assign globalThis.__riddleProofEvidence, window.__riddleProofEvidence, or self.__riddleProofEvidence outside page.evaluate; the Riddle worker context may not expose those globals safely.',
+            'When page.evaluate needs data from the outer Playwright script, pass exactly one serializable argument object; do not pass multiple positional arguments.',
             'Do not begin capture_script with page.goto unless an in-app navigation is genuinely required after the preview opens the target route.',
             'Only escalate to the human after the supervising agent concludes the workflow is genuinely stuck or not converging.',
         ],

package/runtime/lib/riddle_core_call.mjs

@@ -136,6 +136,28 @@ async function run(tool, args) {
     });
   }
 
+  if (tool === "riddle_visual_diff") {
+    const {
+      async,
+      options,
+      stealth,
+      timeout_sec,
+      ...visualDiffOptions
+    } = args;
+    const script = `return await visualDiff(${JSON.stringify(visualDiffOptions)});`;
+    return core.runWithDefaults(config, {
+      url: args.url_before,
+      script,
+      options: { ...(options ?? {}), returnResult: true },
+      stealth,
+      timeout_sec: timeout_sec ?? 60,
+      async,
+    }, {
+      include: ["result", "console", "visual_diff"],
+      returnAsync: !!async,
+    });
+  }
+
   if (tool === "riddle_run") {
     return core.runWithDefaults(config, args.payload ?? args, {
       include: ["screenshot", "console", "result"],

package/runtime/lib/util.py

@@ -14,6 +14,7 @@ RIDDLE_DIRECT_TOOLS = {
     'riddle_build_preview',
     'riddle_build_preview_status',
     'riddle_script',
+    'riddle_visual_diff',
     'riddle_run',
 }
 CAPTURE_ARTIFACT_JSON_LIMIT = 256 * 1024
@@ -767,7 +768,7 @@ def enrich_capture_payload(payload):
     artifact_json = dict(enriched.get('_artifact_json') or {})
     artifact_errors = dict(enriched.get('_artifact_errors') or {})
 
-    for name in ('console.json', 'proof.json'):
+    for name in ('console.json', 'proof.json', 'visual-diff.json'):
         if name in artifact_json or name in artifact_errors:
             continue
         item = capture_output_item(enriched, name)
@@ -798,6 +799,10 @@ def enrich_capture_payload(payload):
                     enriched['result'] = result
                     break
 
+    visual_diff_json = artifact_json.get('visual-diff.json')
+    if isinstance(visual_diff_json, dict) and not enriched.get('visual_diff'):
+        enriched['visual_diff'] = visual_diff_json
+
     return enriched
 
 

package/runtime/lib/verify.py

@@ -55,13 +55,24 @@ MIN_VISUAL_CHANGED_PIXELS = 5000
 VISUAL_DELTA_PERCENT_KEYS = {
     'change_pct', 'change_percent', 'changed_percent', 'percent_changed',
     'diff_percent', 'visual_delta_percent', 'pixel_change_percent',
+    'changepercent', 'changedpercent', 'percentchanged', 'diffpercent',
+    'visualdeltapercent', 'pixelchangepercent', 'difference_percent',
+    'differencepercent', 'diff_percentage', 'diffpercentage',
+    'mismatch_percent', 'mismatchpercent', 'percentage', 'percent',
 }
 VISUAL_DELTA_RATIO_KEYS = {
     'change_ratio', 'changed_ratio', 'diff_ratio', 'visual_delta_ratio',
+    'changeratio', 'changedratio', 'diffratio', 'visualdeltaratio',
+    'difference_ratio', 'differenceratio', 'mismatch_ratio', 'mismatchratio',
 }
 VISUAL_CHANGED_PIXEL_KEYS = {
     'changed_pixels', 'changed_pixel_count', 'changedpixels',
     'diff_pixels', 'pixel_delta', 'visual_delta_pixels',
+    'diffpixels', 'pixeldelta', 'visualdeltapixels', 'different_pixels',
+    'differentpixels', 'mismatch_pixels', 'mismatchpixels', 'pixels_changed',
+    'pixelschanged', 'diff_pixel_count', 'diffpixelcount',
+    'pixel_diff_count', 'pixeldiffcount', 'different_pixel_count',
+    'differentpixelcount', 'num_different_pixels', 'numdifferentpixels',
 }
 VISUAL_TOTAL_PIXEL_KEYS = {
     'total_pixels', 'total_pixel_count', 'pixel_count', 'totalpixels',
@@ -800,6 +811,7 @@ def extract_visual_delta(payload):
     payload = enrich_capture_payload(payload)
     result = payload.get('result') if isinstance(payload, dict) else {}
     proof_json = payload.get('_proof_json') if isinstance(payload, dict) else {}
+    artifact_json = payload.get('_artifact_json') if isinstance(payload, dict) else {}
     proof_evidence = extract_proof_evidence(payload)
     screenshot_url = extract_screenshot_url(payload)
     artifact_summary = summarize_capture_artifacts(payload)
@@ -807,6 +819,11 @@ def extract_visual_delta(payload):
         payload if isinstance(payload, dict) else {},
         result if isinstance(result, dict) else {},
         proof_json if isinstance(proof_json, dict) else {},
+        payload.get('visual_diff') if isinstance(payload, dict) and isinstance(payload.get('visual_diff'), dict) else {},
+        payload.get('visualDiff') if isinstance(payload, dict) and isinstance(payload.get('visualDiff'), dict) else {},
+        result.get('visual_diff') if isinstance(result, dict) and isinstance(result.get('visual_diff'), dict) else {},
+        result.get('visualDiff') if isinstance(result, dict) and isinstance(result.get('visualDiff'), dict) else {},
+        artifact_json.get('visual-diff.json') if isinstance(artifact_json, dict) and isinstance(artifact_json.get('visual-diff.json'), dict) else {},
         proof_evidence,
     ]
 
@@ -899,6 +916,114 @@ def extract_visual_delta(payload):
     }
 
 
+def visual_delta_baseline_candidate(state, results):
+    reference = str(state.get('requested_reference') or state.get('reference') or 'both').strip().lower()
+    baseline = (results.get('baseline') or {}) if isinstance(results, dict) else {}
+    candidates = []
+    if reference in ('before', 'both', ''):
+        candidates.append(('before', (baseline.get('before') or {}).get('url') if isinstance(baseline.get('before'), dict) else ''))
+    if reference in ('prod', 'production', 'both'):
+        candidates.append(('prod', (baseline.get('prod') or {}).get('url') if isinstance(baseline.get('prod'), dict) else ''))
+    candidates.extend([
+        ('before', state.get('before_cdn') or ''),
+        ('prod', state.get('prod_cdn') or ''),
+    ])
+    for label, url in candidates:
+        text = str(url or '').strip()
+        if text:
+            return {'label': label, 'url': text}
+    return {'label': '', 'url': ''}
+
+
+def add_visual_delta_diagnostic(visual_delta, key, value):
+    updated = dict(visual_delta or {})
+    diagnostic = dict(updated.get('diagnostic') or {})
+    diagnostic[key] = value
+    updated['diagnostic'] = diagnostic
+    return updated
+
+
+def measure_visual_delta_against_baseline(state, results, after_payload, current_visual_delta):
+    if not visual_delta_applies(state.get('verification_mode')):
+        return current_visual_delta
+    if isinstance(current_visual_delta, dict) and current_visual_delta.get('status') == 'measured':
+        return current_visual_delta
+
+    baseline = visual_delta_baseline_candidate(state, results)
+    before_url = baseline.get('url') or ''
+    after_url = extract_screenshot_url(after_payload, 'after-proof') or str(state.get('after_cdn') or '').strip()
+    if not before_url or not after_url:
+        missing = []
+        if not before_url:
+            missing.append('baseline screenshot')
+        if not after_url:
+            missing.append('after screenshot')
+        return add_visual_delta_diagnostic(
+            current_visual_delta,
+            'visual_diff_fallback',
+            {
+                'status': 'skipped',
+                'reason': 'missing ' + ' and '.join(missing),
+                'baseline_label': baseline.get('label') or '',
+                'before_url_present': bool(before_url),
+                'after_url_present': bool(after_url),
+            },
+        )
+
+    args = {
+        'url_before': before_url,
+        'url_after': after_url,
+        'delay_ms': 250,
+        'timeout_sec': 60,
+    }
+    try:
+        payload = invoke_retry('riddle_visual_diff', args, retries=2, timeout=180)
+        append_capture_diagnostic(state, 'visual_delta', 'riddle_visual_diff', args, payload)
+    except Exception as exc:
+        return add_visual_delta_diagnostic(
+            current_visual_delta,
+            'visual_diff_fallback',
+            {
+                'status': 'error',
+                'error': type(exc).__name__ + ': ' + str(exc)[:300],
+                'baseline_label': baseline.get('label') or '',
+            },
+        )
+
+    measured = extract_visual_delta(payload)
+    if isinstance(measured, dict) and measured.get('status') == 'measured':
+        measured['source'] = 'riddle_visual_diff'
+        measured['comparison'] = {
+            'baseline_label': baseline.get('label') or '',
+            'before_url': before_url,
+            'after_url': after_url,
+        }
+        if isinstance(payload, dict):
+            diff_url = extract_screenshot_url(payload, 'visual-diff') or extract_screenshot_url(payload, 'diff')
+            if diff_url:
+                measured['comparison']['diff_url'] = diff_url
+            measured['artifact_summary'] = summarize_capture_artifacts(payload)
+        return measured
+
+    updated = add_visual_delta_diagnostic(
+        current_visual_delta,
+        'visual_diff_fallback',
+        {
+            'status': 'unmeasured',
+            'baseline_label': baseline.get('label') or '',
+            'before_url': before_url,
+            'after_url': after_url,
+            'payload_ok': payload.get('ok') if isinstance(payload, dict) else None,
+            'payload_error': str(payload.get('error') or payload.get('stderr') or '')[:500] if isinstance(payload, dict) else '',
+            'artifact_summary': summarize_capture_artifacts(payload) if isinstance(payload, dict) else {},
+        },
+    )
+    reason = str(updated.get('reason') or '').strip()
+    suffix = ' Riddle visual_diff fallback ran but did not publish a recognizable numeric delta.'
+    updated['reason'] = (reason + suffix).strip() if reason else suffix.strip()
+    return updated
+
+
 def visual_delta_applies(verification_mode):
     return screenshot_required_for_mode(verification_mode)
 
@@ -1443,6 +1568,7 @@ def build_evidence_bundle(state, results, after_payload, after_observation, requ
         if visual_delta_applies(state.get('verification_mode'))
         else {'status': 'not_applicable', 'passed': None, 'reason': 'Verification mode does not require visual delta gating.'}
     )
+    visual_delta = measure_visual_delta_against_baseline(state, results, after_payload, visual_delta)
     semantic_context = build_semantic_context(state, results, after_observation, expected_path)
     artifact_contract = artifact_contract_for_mode(state.get('verification_mode'))
     artifact_production = artifact_production_summary(after_payload, supporting)

package/runtime/tests/recon_verify_smoke.py

@@ -569,6 +569,50 @@ def run_verify_quality_ignores_proof_telemetry_console_text():
     assert unmeasured_delta['diagnostic']['after_screenshot_present'] is True
     assert 'After screenshot artifact is present' in unmeasured_delta['reason']
 
+    visual_diff_delta = namespace['extract_visual_delta']({
+        'ok': True,
+        'outputs': [{'name': 'visual-diff.json', 'url': 'https://cdn.example.com/visual-diff.json'}],
+        '_artifact_json': {
+            'visual-diff.json': {
+                'changePercent': '1.45',
+                'diffPixelCount': 14094,
+                'totalPixels': 972000,
+            },
+        },
+    })
+    assert visual_diff_delta['status'] == 'measured'
+    assert visual_diff_delta['passed'] is True
+    assert visual_diff_delta['change_percent'] == 1.45
+    assert visual_diff_delta['changed_pixels'] == 14094
+
+    fallback_calls = []
+
+    def fake_invoke_retry(tool, args, retries=3, timeout=180):
+        fallback_calls.append({'tool': tool, 'args': args, 'retries': retries, 'timeout': timeout})
+        return {
+            'ok': True,
+            'visual_diff': {
+                'diffPercentage': 0.82,
+                'differentPixels': 7970,
+                'totalPixels': 972000,
+            },
+            'outputs': [{'name': 'visual-diff.png', 'url': 'https://cdn.example.com/visual-diff.png'}],
+        }
+
+    namespace['invoke_retry'] = fake_invoke_retry
+    namespace['append_capture_diagnostic'] = lambda *args, **kwargs: None
+    fallback_delta = namespace['measure_visual_delta_against_baseline'](
+        {'verification_mode': 'visual', 'requested_reference': 'before', 'before_cdn': 'https://cdn.example.com/before.png'},
+        {'baseline': {'before': {'url': 'https://cdn.example.com/before.png'}}},
+        {'ok': True, 'screenshots': [{'name': 'after-proof.png', 'url': 'https://cdn.example.com/after.png'}]},
+        unmeasured_delta,
+    )
+    assert fallback_delta['status'] == 'measured'
+    assert fallback_delta['source'] == 'riddle_visual_diff'
+    assert fallback_delta['comparison']['before_url'] == 'https://cdn.example.com/before.png'
+    assert fallback_delta['comparison']['after_url'] == 'https://cdn.example.com/after.png'
+    assert fallback_calls[0]['tool'] == 'riddle_visual_diff'
+
     canvas_payload = {
         'bodyTextLength': 7,
         'visibleTextSample': 'Luge',