@riddledc/riddle-proof 0.8.74 → 0.8.76

package/README.md

@@ -86,6 +86,39 @@ group may be `passed` or `product_regression`, while the after group must be
 `proof_insufficient`, and a missing or failed required delta cannot become a
 passing change proof.
 
+The CLI can collect the two sides against hosted Riddle targets and write one
+change receipt:
+
+```sh
+riddle-proof-loop run-change-proof \
+  --profile .riddle-proof/profiles/hero-art.json \
+  --change-contract .riddle-proof/change-contracts/hero-art-change.json \
+  --before-url https://example.com \
+  --after-url https://preview.example.com \
+  --output artifacts/riddle-proof/hero-art-change
+```
+
+It can also compare saved profile packets without starting new browser jobs:
+
+```sh
+riddle-proof-loop run-change-proof \
+  --profile .riddle-proof/profiles/hero-art.json \
+  --change-contract .riddle-proof/change-contracts/hero-art-change.json \
+  --before-result artifacts/before/profile-result.json \
+  --after-result artifacts/after/profile-result.json \
+  --result-format compact-json
+```
+
+When `--output` / `--output-dir` is set, the command writes
+`change-proof-result.json`, `summary.md`, and normalized copies of the
+`before/profile-result.json` and `after/profile-result.json` inputs. A
+non-passing change proof exits nonzero so CI and PR-comment automation can use
+the receipt as a gate.
+
+For a small hosted-preview dogfood target, see
+`examples/profiles/hosted-change-proof-preview.json` and
+`examples/change-contracts/hosted-change-proof-preview.json`.
+
 ## Durable Loop CLI
 
 The package publishes `riddle-proof-loop` as a host-agnostic runner surface for

package/dist/{chunk-ANUWU3DO.js → chunk-AK2EPEVO.js}

@@ -30,6 +30,9 @@ import {
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
 } from "./chunk-GG2D3MFZ.js";
+import {
+  assessRiddleProofChange
+} from "./chunk-6S7DZWVC.js";
 import {
   createCodexExecAgentAdapter,
   runCodexExecAgentDoctor
@@ -57,8 +60,13 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "attempts",
   "balancePreflight",
   "baseUrl",
+  "afterResult",
+  "afterUrl",
+  "beforeResult",
+  "beforeUrl",
   "candidateJson",
   "candidatesJson",
+  "changeContract",
   "checkpointMode",
   "checkpointVisibility",
   "changedFiles",
@@ -165,6 +173,7 @@ function usage() {
     "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--base-url <base-url>] [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--balance-preflight true|false; default true] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> [--base-url <base-url>] --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> [--base-url <base-url>] --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
+    "  riddle-proof-loop run-change-proof --profile <file|json|-> --change-contract <file|json|-> (--before-url <url> --after-url <url> | --before-result <file> --after-result <file>) [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop profile-suggest --route /path|--url <url> [--changed-files a,b] [--selectors .a,.b] [--changed-text-json <file|json|->] [--format json|profile]",
     "  riddle-proof-loop regression-pack run [--pack oc-flow-regression|--pack-file <file>] [--local-core true|false; default true] [--hosted-riddle true|false; default false] [--format json|markdown|compact-json; default json] [--output <dir>|--output-dir <dir>]",
     "  riddle-proof-loop pr-comment --proof-dir <dir>|--run-response <file> [--result-json <file>] --pr <number|url> [--repo owner/name] [--dry-run] [--body-file <file>] [--comment-mode update|append]",
@@ -1230,14 +1239,19 @@ function parseProfileViewports(value) {
     };
   });
 }
-function normalizeProfileForCli(options) {
-  const rawProfile = readJsonValue(optionString(options, "profile"), "--profile");
+function readProfileRecordForCli(options) {
+  return readJsonValue(optionString(options, "profile"), "--profile");
+}
+function normalizeProfileRecordForCli(rawProfile, options) {
   return normalizeRiddleProofProfile(rawProfile, {
     url: optionString(options, "url") ?? optionString(options, "baseUrl"),
     route: optionString(options, "route"),
     viewports: parseProfileViewports(optionString(options, "viewports") || optionString(options, "viewport"))
   });
 }
+function normalizeProfileForCli(options) {
+  return normalizeProfileRecordForCli(readProfileRecordForCli(options), options);
+}
 function profileHttpStatusPreflightSummary(result) {
   const lines = [
     result.summary,
@@ -3909,6 +3923,136 @@ function writeProfileOutput(outputDir, result) {
   if (result.evidence?.dom_summary) writeFileSync(path.join(outputDir, "dom-summary.json"), `${JSON.stringify(result.evidence.dom_summary, null, 2)}
 `);
 }
+function readChangeContractForCli(options) {
+  const parsed = readJsonValue(optionString(options, "changeContract"), "--change-contract");
+  if (parsed.version !== void 0 && parsed.version !== "riddle-proof.change-contract.v1") {
+    throw new Error(`Unsupported change contract version ${parsed.version}. Expected riddle-proof.change-contract.v1.`);
+  }
+  if (typeof parsed.name !== "string" || !parsed.name.trim()) {
+    throw new Error("--change-contract must include a non-empty name.");
+  }
+  if (!Array.isArray(parsed.deltas) || !parsed.deltas.length) {
+    throw new Error("--change-contract must include at least one delta.");
+  }
+  return parsed;
+}
+function changeProofSideOutputDir(outputDir, side) {
+  return outputDir ? path.join(outputDir, side) : void 0;
+}
+function profileOptionsForChangeProofSide(options, url, outputDir) {
+  const next = {
+    ...options,
+    url,
+    baseUrl: url
+  };
+  if (outputDir) {
+    next.output = outputDir;
+    next.outputDir = outputDir;
+  } else {
+    delete next.output;
+    delete next.outputDir;
+  }
+  return next;
+}
+function compactChangeProofResult(run, options) {
+  const outputDir = profileOutputDirOption(options);
+  return {
+    version: "riddle-proof.change-compact-result.v1",
+    contract_name: run.result.contract_name,
+    profile_name: run.profile.name,
+    status: run.result.status,
+    summary: run.result.summary,
+    before: {
+      source: run.beforeSource,
+      profile_name: run.beforeResult.profile_name,
+      status: run.beforeResult.status,
+      summary: run.beforeResult.summary
+    },
+    after: {
+      source: run.afterSource,
+      profile_name: run.afterResult.profile_name,
+      status: run.afterResult.status,
+      summary: run.afterResult.summary
+    },
+    deltas: run.result.deltas.map((delta) => ({
+      type: delta.type,
+      label: delta.label,
+      status: delta.status,
+      before_observed: delta.before_observed,
+      after_observed: delta.after_observed,
+      message: delta.message
+    })),
+    metadata: run.result.metadata,
+    output_dir: outputDir,
+    output_files: outputDir ? {
+      change_proof_result: "change-proof-result.json",
+      summary: "summary.md",
+      before_profile_result: "before/profile-result.json",
+      after_profile_result: "after/profile-result.json"
+    } : void 0
+  };
+}
+function changeProofResultMarkdown(run) {
+  const lines = [
+    "# Riddle Proof Change Proof",
+    "",
+    `Contract: ${run.result.contract_name}`,
+    `Profile: ${run.profile.name}`,
+    `Status: ${run.result.status}`,
+    "",
+    run.result.summary,
+    "",
+    "## Before",
+    "",
+    `- source: ${markdownInlineCode(run.beforeSource, 160)}`,
+    `- profile: ${run.beforeResult.profile_name}`,
+    `- status: ${run.beforeResult.status}`,
+    `- summary: ${run.beforeResult.summary}`,
+    "",
+    "## After",
+    "",
+    `- source: ${markdownInlineCode(run.afterSource, 160)}`,
+    `- profile: ${run.afterResult.profile_name}`,
+    `- status: ${run.afterResult.status}`,
+    `- summary: ${run.afterResult.summary}`,
+    "",
+    "## Deltas",
+    ""
+  ];
+  for (const delta of run.result.deltas) {
+    const observed = [
+      delta.before_observed !== void 0 ? `before ${markdownInlineCode(String(delta.before_observed))}` : "",
+      delta.after_observed !== void 0 ? `after ${markdownInlineCode(String(delta.after_observed))}` : ""
+    ].filter(Boolean).join(" -> ");
+    lines.push(`- ${delta.status}: ${delta.label}${observed ? ` (${observed})` : ""}${delta.message ? ` - ${delta.message}` : ""}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function writeChangeProofOutput(outputDir, run) {
+  if (!outputDir) return;
+  mkdirSync(outputDir, { recursive: true });
+  writeFileSync(path.join(outputDir, "change-proof-result.json"), `${JSON.stringify(run.result, null, 2)}
+`);
+  writeFileSync(path.join(outputDir, "summary.md"), changeProofResultMarkdown(run));
+  writeProfileOutput(changeProofSideOutputDir(outputDir, "before"), run.beforeResult);
+  writeProfileOutput(changeProofSideOutputDir(outputDir, "after"), run.afterResult);
+}
+function writeRunChangeProofResult(run, options) {
+  const format = runProfileResultFormatOption(options);
+  if (format === "none") return;
+  if (format === "summary") {
+    process.stdout.write(changeProofResultMarkdown(run));
+    return;
+  }
+  if (format === "compact-json") {
+    process.stdout.write(`${JSON.stringify(compactChangeProofResult(run, options), null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(run.result, null, 2)}
+`);
+}
 function writeRiddleJobReceipt(outputDir, input) {
   if (!outputDir) return;
   mkdirSync(outputDir, { recursive: true });
@@ -4214,13 +4358,16 @@ function runProfileAggregateInputPathsOption(options) {
   }
   return uniquePaths;
 }
-function readProfileResultForAggregate(resultPath) {
-  const parsed = readJsonValue(resultPath, resultPath);
+function readProfileResultForCli(resultPath, label = resultPath) {
+  const parsed = readJsonValue(resultPath, label);
   if (parsed.version !== "riddle-proof.profile-result.v1" || !Array.isArray(parsed.checks)) {
-    throw new Error(`Profile aggregate input is not a riddle-proof.profile-result.v1 result: ${resultPath}`);
+    throw new Error(`${label} is not a riddle-proof.profile-result.v1 result: ${resultPath}`);
   }
   return parsed;
 }
+function readProfileResultForAggregate(resultPath) {
+  return readProfileResultForCli(resultPath, resultPath);
+}
 function profileResultIsAggregateParent(result) {
   const mode = cliString(cliRecord(result.riddle)?.mode);
   return (mode === "split-viewports" || mode === "named-viewport-aggregate") && (result.evidence?.viewports?.length || 0) > 1;
@@ -4751,6 +4898,58 @@ async function runProfileForCli(profile, options) {
   }
   return runSingleRiddleProfileForCli(profile, options, { client, runner, outputDir: profileOutputDirOption(options) });
 }
+async function runChangeProofForCli(rawProfile, options) {
+  const contract = readChangeContractForCli(options);
+  const beforeResultPath = optionString(options, "beforeResult");
+  const afterResultPath = optionString(options, "afterResult");
+  const beforeUrl = optionString(options, "beforeUrl");
+  const afterUrl = optionString(options, "afterUrl");
+  const hasResultInputs = Boolean(beforeResultPath || afterResultPath);
+  const hasUrlInputs = Boolean(beforeUrl || afterUrl);
+  if (hasResultInputs && hasUrlInputs) {
+    throw new Error("run-change-proof accepts either --before-result/--after-result or --before-url/--after-url, not both.");
+  }
+  if (hasResultInputs && (!beforeResultPath || !afterResultPath)) {
+    throw new Error("run-change-proof requires both --before-result and --after-result.");
+  }
+  if (!hasResultInputs && (!beforeUrl || !afterUrl)) {
+    throw new Error("run-change-proof requires both --before-url and --after-url unless saved results are provided.");
+  }
+  const outputDir = profileOutputDirOption(options);
+  let profile;
+  let beforeResult;
+  let afterResult;
+  let beforeSource;
+  let afterSource;
+  if (hasResultInputs) {
+    if (!beforeResultPath || !afterResultPath) {
+      throw new Error("run-change-proof requires both --before-result and --after-result.");
+    }
+    profile = profileWithSelectedViewportNamesForCli(normalizeProfileRecordForCli(rawProfile, options), options);
+    beforeResult = readProfileResultForCli(beforeResultPath, "--before-result");
+    afterResult = readProfileResultForCli(afterResultPath, "--after-result");
+    beforeSource = beforeResultPath;
+    afterSource = afterResultPath;
+  } else {
+    if (!beforeUrl || !afterUrl) {
+      throw new Error("run-change-proof requires both --before-url and --after-url unless saved results are provided.");
+    }
+    const beforeOptions = profileOptionsForChangeProofSide(options, beforeUrl, changeProofSideOutputDir(outputDir, "before"));
+    const afterOptions = profileOptionsForChangeProofSide(options, afterUrl, changeProofSideOutputDir(outputDir, "after"));
+    const beforeProfile = profileWithSelectedViewportNamesForCli(normalizeProfileRecordForCli(rawProfile, beforeOptions), beforeOptions);
+    const afterProfile = profileWithSelectedViewportNamesForCli(normalizeProfileRecordForCli(rawProfile, afterOptions), afterOptions);
+    profile = beforeProfile;
+    beforeResult = await runProfileForCli(beforeProfile, beforeOptions);
+    afterResult = await runProfileForCli(afterProfile, afterOptions);
+    beforeSource = beforeUrl;
+    afterSource = afterUrl;
+  }
+  const result = assessRiddleProofChange(contract, {
+    before_result: beforeResult,
+    after_result: afterResult
+  });
+  return { profile, contract, beforeResult, afterResult, result, beforeSource, afterSource };
+}
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
   const withEngineModuleUrl = (request) => {
@@ -4811,6 +5010,13 @@ async function main() {
     process.exitCode = profileStatusExitCode(profile, result.status);
     return;
   }
+  if (command === "run-change-proof") {
+    const run = await runChangeProofForCli(readProfileRecordForCli(options), options);
+    writeChangeProofOutput(profileOutputDirOption(options), run);
+    writeRunChangeProofResult(run, options);
+    process.exitCode = run.result.status === "passed" ? 0 : 1;
+    return;
+  }
   if (command === "regression-pack") {
     const action = positional[1] || "run";
     if (action !== "run") throw new Error("Only `regression-pack run` is supported.");

package/dist/cli/index.js

@@ -1,9 +1,10 @@
-import "../chunk-ANUWU3DO.js";
+import "../chunk-AK2EPEVO.js";
 import "../chunk-B2DP2LET.js";
 import "../chunk-JFQXAJH2.js";
 import "../chunk-CWRIXP5H.js";
 import "../chunk-UE4I7RTI.js";
 import "../chunk-GG2D3MFZ.js";
+import "../chunk-6S7DZWVC.js";
 import "../chunk-KXLEN4SA.js";
 import "../chunk-WLUMLHII.js";
 import "../chunk-CGJX7LJO.js";

package/dist/cli.cjs

@@ -18608,6 +18608,167 @@ function suggestRiddleProofProfileChecks(input) {
   };
 }
 
+// src/change-proof.ts
+var RIDDLE_PROOF_CHANGE_RESULT_VERSION = "riddle-proof.change-result.v1";
+var DEFAULT_BEFORE_STATUSES = ["passed", "product_regression"];
+var DEFAULT_AFTER_STATUSES = ["passed"];
+var DEFAULT_PROFILE_STATUS_TRANSITION_BEFORE = ["product_regression"];
+var DEFAULT_PROFILE_STATUS_TRANSITION_AFTER = ["passed"];
+var DEFAULT_CHECK_STATUS_TRANSITION_BEFORE = ["failed"];
+var DEFAULT_CHECK_STATUS_TRANSITION_AFTER = ["passed"];
+function listValue(value, fallback) {
+  if (Array.isArray(value)) return value;
+  if (value === void 0) return fallback;
+  return [value];
+}
+function includesValue(allowed, observed) {
+  return observed !== void 0 && allowed.includes(observed);
+}
+function groupResult(side, contract, result) {
+  const fallback = side === "before" ? DEFAULT_BEFORE_STATUSES : DEFAULT_AFTER_STATUSES;
+  const requiredStatus = listValue(contract?.required_status, fallback);
+  const label = contract?.label || side;
+  if (!result) {
+    return {
+      side,
+      label,
+      ok: false,
+      status: "missing",
+      required_status: requiredStatus,
+      message: `${label} profile result is missing.`
+    };
+  }
+  const ok = includesValue(requiredStatus, result.status);
+  return {
+    side,
+    label,
+    ok,
+    profile_name: result.profile_name,
+    status: result.status,
+    required_status: requiredStatus,
+    summary: result.summary,
+    message: ok ? void 0 : `${label} profile status ${result.status} did not match required status ${requiredStatus.join(", ")}.`
+  };
+}
+function findCheck(result, delta) {
+  return result.checks.find((check) => {
+    if (delta.check_label && check.label !== delta.check_label) return false;
+    if (delta.check_type && check.type !== delta.check_type) return false;
+    return Boolean(delta.check_label || delta.check_type);
+  });
+}
+function profileStatusTransitionResult(delta, before, after) {
+  const label = delta.label || "profile-status-transition";
+  if (!before || !after) {
+    return {
+      type: delta.type,
+      label,
+      status: "proof_insufficient",
+      before_observed: before?.status,
+      after_observed: after?.status,
+      message: `${label} needs both before and after profile results.`
+    };
+  }
+  const beforeAllowed = listValue(delta.before_status, DEFAULT_PROFILE_STATUS_TRANSITION_BEFORE);
+  const afterAllowed = listValue(delta.after_status, DEFAULT_PROFILE_STATUS_TRANSITION_AFTER);
+  const passed = includesValue(beforeAllowed, before.status) && includesValue(afterAllowed, after.status);
+  return {
+    type: delta.type,
+    label,
+    status: passed ? "passed" : "failed",
+    before_observed: before.status,
+    after_observed: after.status,
+    message: passed ? void 0 : `${label} expected before ${beforeAllowed.join(", ")} and after ${afterAllowed.join(", ")}, got ${before.status} -> ${after.status}.`
+  };
+}
+function checkStatusTransitionResult(delta, before, after) {
+  const label = delta.label || delta.check_label || delta.check_type || "check-status-transition";
+  if (!delta.check_label && !delta.check_type) {
+    return {
+      type: delta.type,
+      label,
+      status: "configuration_error",
+      message: `${label} needs check_label or check_type.`
+    };
+  }
+  if (!before || !after) {
+    return {
+      type: delta.type,
+      label,
+      status: "proof_insufficient",
+      before_observed: before?.status,
+      after_observed: after?.status,
+      message: `${label} needs both before and after profile results.`
+    };
+  }
+  const beforeCheck = findCheck(before, delta);
+  const afterCheck = findCheck(after, delta);
+  if (!beforeCheck || !afterCheck) {
+    return {
+      type: delta.type,
+      label,
+      status: "proof_insufficient",
+      before_observed: beforeCheck?.status,
+      after_observed: afterCheck?.status,
+      message: `${label} was not present in ${!beforeCheck && !afterCheck ? "before or after" : !beforeCheck ? "before" : "after"} profile checks.`
+    };
+  }
+  const beforeAllowed = listValue(delta.before_status, DEFAULT_CHECK_STATUS_TRANSITION_BEFORE);
+  const afterAllowed = listValue(delta.after_status, DEFAULT_CHECK_STATUS_TRANSITION_AFTER);
+  const passed = includesValue(beforeAllowed, beforeCheck.status) && includesValue(afterAllowed, afterCheck.status);
+  return {
+    type: delta.type,
+    label,
+    status: passed ? "passed" : "failed",
+    before_observed: beforeCheck.status,
+    after_observed: afterCheck.status,
+    message: passed ? void 0 : `${label} expected before ${beforeAllowed.join(", ")} and after ${afterAllowed.join(", ")}, got ${beforeCheck.status} -> ${afterCheck.status}.`
+  };
+}
+function assessDelta(delta, before, after) {
+  if (delta.type === "profile_status_transition") {
+    return profileStatusTransitionResult(delta, before, after);
+  }
+  return checkStatusTransitionResult(delta, before, after);
+}
+function collapsedChangeStatus(groups, deltas) {
+  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 (!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";
+  return "passed";
+}
+function changeSummary(name, status, deltas) {
+  if (status === "passed") return `${name} passed ${deltas.length} change delta(s).`;
+  if (status === "environment_blocked") return `${name} could not compare reliable evidence because an environment was blocked.`;
+  if (status === "configuration_error") return `${name} has an invalid change proof contract.`;
+  if (status === "needs_human_review") return `${name} needs human review before the change proof can pass.`;
+  if (status === "proof_insufficient") return `${name} did not produce enough before/after evidence for a change proof.`;
+  return `${name} failed ${deltas.filter((delta) => delta.status === "failed").length} change delta(s).`;
+}
+function assessRiddleProofChange(contract, input) {
+  const groups = {
+    before: groupResult("before", contract.before, input.before_result),
+    after: groupResult("after", contract.after, input.after_result)
+  };
+  const deltas = (contract.deltas || []).map((delta) => assessDelta(delta, input.before_result, input.after_result));
+  const status = collapsedChangeStatus(groups, deltas);
+  return {
+    version: RIDDLE_PROOF_CHANGE_RESULT_VERSION,
+    contract_name: contract.name,
+    status,
+    groups,
+    deltas,
+    summary: changeSummary(contract.name, status, deltas),
+    metadata: contract.metadata
+  };
+}
+
 // src/cli.ts
 var RIDDLE_PROFILE_BALANCE_PREFLIGHT_MIN_SECONDS_PER_JOB = 30;
 var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
@@ -18619,8 +18780,13 @@ var KNOWN_CLI_OPTIONS = /* @__PURE__ */ new Set([
   "attempts",
   "balancePreflight",
   "baseUrl",
+  "afterResult",
+  "afterUrl",
+  "beforeResult",
+  "beforeUrl",
   "candidateJson",
   "candidatesJson",
+  "changeContract",
   "checkpointMode",
   "checkpointVisibility",
   "changedFiles",
@@ -18727,6 +18893,7 @@ function usage() {
     "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--base-url <base-url>] [--runner riddle] [--viewport-name <name[,name...]>] [--strict true|false; default false] [--split-viewports true|false; default false] [--balance-preflight true|false; default true] [--poll-attempts n] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json] [--quiet]",
     "  riddle-proof-loop run-profile aggregate --profile <file|json|-> --url <base-url> [--base-url <base-url>] --input-dir <dir>|--inputs <path[,path...]> [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop run-profile recover --profile <file|json|-> --url <base-url> [--base-url <base-url>] --job <job-id> [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
+    "  riddle-proof-loop run-change-proof --profile <file|json|-> --change-contract <file|json|-> (--before-url <url> --after-url <url> | --before-result <file> --after-result <file>) [--viewport-name <name[,name...]>] [--output <dir>|--output-dir <dir>] [--result-format json|compact-json|summary|none; default json]",
     "  riddle-proof-loop profile-suggest --route /path|--url <url> [--changed-files a,b] [--selectors .a,.b] [--changed-text-json <file|json|->] [--format json|profile]",
     "  riddle-proof-loop regression-pack run [--pack oc-flow-regression|--pack-file <file>] [--local-core true|false; default true] [--hosted-riddle true|false; default false] [--format json|markdown|compact-json; default json] [--output <dir>|--output-dir <dir>]",
     "  riddle-proof-loop pr-comment --proof-dir <dir>|--run-response <file> [--result-json <file>] --pr <number|url> [--repo owner/name] [--dry-run] [--body-file <file>] [--comment-mode update|append]",
@@ -19792,14 +19959,19 @@ function parseProfileViewports(value) {
     };
   });
 }
-function normalizeProfileForCli(options) {
-  const rawProfile = readJsonValue(optionString(options, "profile"), "--profile");
+function readProfileRecordForCli(options) {
+  return readJsonValue(optionString(options, "profile"), "--profile");
+}
+function normalizeProfileRecordForCli(rawProfile, options) {
   return normalizeRiddleProofProfile(rawProfile, {
     url: optionString(options, "url") ?? optionString(options, "baseUrl"),
     route: optionString(options, "route"),
     viewports: parseProfileViewports(optionString(options, "viewports") || optionString(options, "viewport"))
   });
 }
+function normalizeProfileForCli(options) {
+  return normalizeProfileRecordForCli(readProfileRecordForCli(options), options);
+}
 function profileHttpStatusPreflightSummary(result) {
   const lines = [
     result.summary,
@@ -22471,6 +22643,136 @@ function writeProfileOutput(outputDir, result) {
   if (result.evidence?.dom_summary) (0, import_node_fs6.writeFileSync)(import_node_path6.default.join(outputDir, "dom-summary.json"), `${JSON.stringify(result.evidence.dom_summary, null, 2)}
 `);
 }
+function readChangeContractForCli(options) {
+  const parsed = readJsonValue(optionString(options, "changeContract"), "--change-contract");
+  if (parsed.version !== void 0 && parsed.version !== "riddle-proof.change-contract.v1") {
+    throw new Error(`Unsupported change contract version ${parsed.version}. Expected riddle-proof.change-contract.v1.`);
+  }
+  if (typeof parsed.name !== "string" || !parsed.name.trim()) {
+    throw new Error("--change-contract must include a non-empty name.");
+  }
+  if (!Array.isArray(parsed.deltas) || !parsed.deltas.length) {
+    throw new Error("--change-contract must include at least one delta.");
+  }
+  return parsed;
+}
+function changeProofSideOutputDir(outputDir, side) {
+  return outputDir ? import_node_path6.default.join(outputDir, side) : void 0;
+}
+function profileOptionsForChangeProofSide(options, url, outputDir) {
+  const next = {
+    ...options,
+    url,
+    baseUrl: url
+  };
+  if (outputDir) {
+    next.output = outputDir;
+    next.outputDir = outputDir;
+  } else {
+    delete next.output;
+    delete next.outputDir;
+  }
+  return next;
+}
+function compactChangeProofResult(run, options) {
+  const outputDir = profileOutputDirOption(options);
+  return {
+    version: "riddle-proof.change-compact-result.v1",
+    contract_name: run.result.contract_name,
+    profile_name: run.profile.name,
+    status: run.result.status,
+    summary: run.result.summary,
+    before: {
+      source: run.beforeSource,
+      profile_name: run.beforeResult.profile_name,
+      status: run.beforeResult.status,
+      summary: run.beforeResult.summary
+    },
+    after: {
+      source: run.afterSource,
+      profile_name: run.afterResult.profile_name,
+      status: run.afterResult.status,
+      summary: run.afterResult.summary
+    },
+    deltas: run.result.deltas.map((delta) => ({
+      type: delta.type,
+      label: delta.label,
+      status: delta.status,
+      before_observed: delta.before_observed,
+      after_observed: delta.after_observed,
+      message: delta.message
+    })),
+    metadata: run.result.metadata,
+    output_dir: outputDir,
+    output_files: outputDir ? {
+      change_proof_result: "change-proof-result.json",
+      summary: "summary.md",
+      before_profile_result: "before/profile-result.json",
+      after_profile_result: "after/profile-result.json"
+    } : void 0
+  };
+}
+function changeProofResultMarkdown(run) {
+  const lines = [
+    "# Riddle Proof Change Proof",
+    "",
+    `Contract: ${run.result.contract_name}`,
+    `Profile: ${run.profile.name}`,
+    `Status: ${run.result.status}`,
+    "",
+    run.result.summary,
+    "",
+    "## Before",
+    "",
+    `- source: ${markdownInlineCode(run.beforeSource, 160)}`,
+    `- profile: ${run.beforeResult.profile_name}`,
+    `- status: ${run.beforeResult.status}`,
+    `- summary: ${run.beforeResult.summary}`,
+    "",
+    "## After",
+    "",
+    `- source: ${markdownInlineCode(run.afterSource, 160)}`,
+    `- profile: ${run.afterResult.profile_name}`,
+    `- status: ${run.afterResult.status}`,
+    `- summary: ${run.afterResult.summary}`,
+    "",
+    "## Deltas",
+    ""
+  ];
+  for (const delta of run.result.deltas) {
+    const observed = [
+      delta.before_observed !== void 0 ? `before ${markdownInlineCode(String(delta.before_observed))}` : "",
+      delta.after_observed !== void 0 ? `after ${markdownInlineCode(String(delta.after_observed))}` : ""
+    ].filter(Boolean).join(" -> ");
+    lines.push(`- ${delta.status}: ${delta.label}${observed ? ` (${observed})` : ""}${delta.message ? ` - ${delta.message}` : ""}`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function writeChangeProofOutput(outputDir, run) {
+  if (!outputDir) return;
+  (0, import_node_fs6.mkdirSync)(outputDir, { recursive: true });
+  (0, import_node_fs6.writeFileSync)(import_node_path6.default.join(outputDir, "change-proof-result.json"), `${JSON.stringify(run.result, null, 2)}
+`);
+  (0, import_node_fs6.writeFileSync)(import_node_path6.default.join(outputDir, "summary.md"), changeProofResultMarkdown(run));
+  writeProfileOutput(changeProofSideOutputDir(outputDir, "before"), run.beforeResult);
+  writeProfileOutput(changeProofSideOutputDir(outputDir, "after"), run.afterResult);
+}
+function writeRunChangeProofResult(run, options) {
+  const format = runProfileResultFormatOption(options);
+  if (format === "none") return;
+  if (format === "summary") {
+    process.stdout.write(changeProofResultMarkdown(run));
+    return;
+  }
+  if (format === "compact-json") {
+    process.stdout.write(`${JSON.stringify(compactChangeProofResult(run, options), null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(run.result, null, 2)}
+`);
+}
 function writeRiddleJobReceipt(outputDir, input) {
   if (!outputDir) return;
   (0, import_node_fs6.mkdirSync)(outputDir, { recursive: true });
@@ -22776,13 +23078,16 @@ function runProfileAggregateInputPathsOption(options) {
   }
   return uniquePaths;
 }
-function readProfileResultForAggregate(resultPath) {
-  const parsed = readJsonValue(resultPath, resultPath);
+function readProfileResultForCli(resultPath, label = resultPath) {
+  const parsed = readJsonValue(resultPath, label);
   if (parsed.version !== "riddle-proof.profile-result.v1" || !Array.isArray(parsed.checks)) {
-    throw new Error(`Profile aggregate input is not a riddle-proof.profile-result.v1 result: ${resultPath}`);
+    throw new Error(`${label} is not a riddle-proof.profile-result.v1 result: ${resultPath}`);
   }
   return parsed;
 }
+function readProfileResultForAggregate(resultPath) {
+  return readProfileResultForCli(resultPath, resultPath);
+}
 function profileResultIsAggregateParent(result) {
   const mode = cliString(cliRecord(result.riddle)?.mode);
   return (mode === "split-viewports" || mode === "named-viewport-aggregate") && (result.evidence?.viewports?.length || 0) > 1;
@@ -23313,6 +23618,58 @@ async function runProfileForCli(profile, options) {
   }
   return runSingleRiddleProfileForCli(profile, options, { client, runner, outputDir: profileOutputDirOption(options) });
 }
+async function runChangeProofForCli(rawProfile, options) {
+  const contract = readChangeContractForCli(options);
+  const beforeResultPath = optionString(options, "beforeResult");
+  const afterResultPath = optionString(options, "afterResult");
+  const beforeUrl = optionString(options, "beforeUrl");
+  const afterUrl = optionString(options, "afterUrl");
+  const hasResultInputs = Boolean(beforeResultPath || afterResultPath);
+  const hasUrlInputs = Boolean(beforeUrl || afterUrl);
+  if (hasResultInputs && hasUrlInputs) {
+    throw new Error("run-change-proof accepts either --before-result/--after-result or --before-url/--after-url, not both.");
+  }
+  if (hasResultInputs && (!beforeResultPath || !afterResultPath)) {
+    throw new Error("run-change-proof requires both --before-result and --after-result.");
+  }
+  if (!hasResultInputs && (!beforeUrl || !afterUrl)) {
+    throw new Error("run-change-proof requires both --before-url and --after-url unless saved results are provided.");
+  }
+  const outputDir = profileOutputDirOption(options);
+  let profile;
+  let beforeResult;
+  let afterResult;
+  let beforeSource;
+  let afterSource;
+  if (hasResultInputs) {
+    if (!beforeResultPath || !afterResultPath) {
+      throw new Error("run-change-proof requires both --before-result and --after-result.");
+    }
+    profile = profileWithSelectedViewportNamesForCli(normalizeProfileRecordForCli(rawProfile, options), options);
+    beforeResult = readProfileResultForCli(beforeResultPath, "--before-result");
+    afterResult = readProfileResultForCli(afterResultPath, "--after-result");
+    beforeSource = beforeResultPath;
+    afterSource = afterResultPath;
+  } else {
+    if (!beforeUrl || !afterUrl) {
+      throw new Error("run-change-proof requires both --before-url and --after-url unless saved results are provided.");
+    }
+    const beforeOptions = profileOptionsForChangeProofSide(options, beforeUrl, changeProofSideOutputDir(outputDir, "before"));
+    const afterOptions = profileOptionsForChangeProofSide(options, afterUrl, changeProofSideOutputDir(outputDir, "after"));
+    const beforeProfile = profileWithSelectedViewportNamesForCli(normalizeProfileRecordForCli(rawProfile, beforeOptions), beforeOptions);
+    const afterProfile = profileWithSelectedViewportNamesForCli(normalizeProfileRecordForCli(rawProfile, afterOptions), afterOptions);
+    profile = beforeProfile;
+    beforeResult = await runProfileForCli(beforeProfile, beforeOptions);
+    afterResult = await runProfileForCli(afterProfile, afterOptions);
+    beforeSource = beforeUrl;
+    afterSource = afterUrl;
+  }
+  const result = assessRiddleProofChange(contract, {
+    before_result: beforeResult,
+    after_result: afterResult
+  });
+  return { profile, contract, beforeResult, afterResult, result, beforeSource, afterSource };
+}
 function requestForRun(options) {
   const statePath = optionString(options, "statePath");
   const withEngineModuleUrl = (request) => {
@@ -23373,6 +23730,13 @@ async function main() {
     process.exitCode = profileStatusExitCode(profile, result.status);
     return;
   }
+  if (command === "run-change-proof") {
+    const run = await runChangeProofForCli(readProfileRecordForCli(options), options);
+    writeChangeProofOutput(profileOutputDirOption(options), run);
+    writeRunChangeProofResult(run, options);
+    process.exitCode = run.result.status === "passed" ? 0 : 1;
+    return;
+  }
   if (command === "regression-pack") {
     const action = positional[1] || "run";
     if (action !== "run") throw new Error("Only `regression-pack run` is supported.");

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import "./chunk-ANUWU3DO.js";
+import "./chunk-AK2EPEVO.js";
 import "./chunk-B2DP2LET.js";
 import "./chunk-JFQXAJH2.js";
 import "./chunk-CWRIXP5H.js";
 import "./chunk-UE4I7RTI.js";
 import "./chunk-GG2D3MFZ.js";
+import "./chunk-6S7DZWVC.js";
 import "./chunk-KXLEN4SA.js";
 import "./chunk-WLUMLHII.js";
 import "./chunk-CGJX7LJO.js";

package/dist/index.js

@@ -37,11 +37,6 @@ import {
   resolveBasicGameplayProgressionCheckWithArtifactScreenshots,
   sanitizeBasicGameplayJsonString
 } from "./chunk-ELZSPOWV.js";
-import {
-  RIDDLE_PROOF_CHANGE_CONTRACT_VERSION,
-  RIDDLE_PROOF_CHANGE_RESULT_VERSION,
-  assessRiddleProofChange
-} from "./chunk-6S7DZWVC.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,
@@ -101,6 +96,11 @@ import {
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
 } from "./chunk-GG2D3MFZ.js";
+import {
+  RIDDLE_PROOF_CHANGE_CONTRACT_VERSION,
+  RIDDLE_PROOF_CHANGE_RESULT_VERSION,
+  assessRiddleProofChange
+} from "./chunk-6S7DZWVC.js";
 import {
   createCodexExecAgentAdapter,
   createCodexExecJsonRunner,

package/examples/change-contracts/hosted-change-proof-preview.json

@@ -0,0 +1,16 @@
+{
+  "version": "riddle-proof.change-contract.v1",
+  "name": "Hosted preview marker appears after change",
+  "deltas": [
+    {
+      "type": "check_status_transition",
+      "label": "hosted preview marker becomes visible",
+      "check_label": "hosted-preview-marker-visible",
+      "before_status": "failed",
+      "after_status": "passed"
+    }
+  ],
+  "metadata": {
+    "example": "hosted preview before/after proof"
+  }
+}

package/examples/neutral-fixture-site/pass.html

@@ -28,6 +28,10 @@
             <dt>Fixture</dt>
             <dd>neutral-fixture-pass</dd>
           </div>
+          <div>
+            <dt>Hosted proof</dt>
+            <dd data-rp-change-proof="hosted-preview">hosted preview change proof</dd>
+          </div>
         </dl>
       </section>
     </main>

package/examples/neutral-fixture-site/styles.css

@@ -70,7 +70,7 @@ p {
 
 dl {
   display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
+  grid-template-columns: repeat(4, minmax(0, 1fr));
   margin: 0;
 }
 

package/examples/profiles/hosted-change-proof-preview.json

@@ -0,0 +1,36 @@
+{
+  "version": "riddle-proof.profile.v1",
+  "name": "hosted-change-proof-preview",
+  "target": {
+    "route": "/pass.html",
+    "viewports": [
+      { "name": "phone", "width": 390, "height": 844 },
+      { "name": "desktop", "width": 1440, "height": 1000 }
+    ],
+    "auth": "none",
+    "wait_for_selector": "[data-rp-fixture=\"pass\"]",
+    "setup_actions": [
+      { "type": "screenshot", "label": "initial-fixture-state", "full_page": false },
+      { "type": "wait", "ms": 100 }
+    ],
+    "screenshot_full_page": false
+  },
+  "checks": [
+    { "type": "route_loaded", "expected_path": "/pass.html" },
+    { "type": "selector_visible", "selector": "[data-rp-fixture=\"pass\"]" },
+    {
+      "type": "selector_text_visible",
+      "label": "hosted-preview-marker-visible",
+      "selector": "[data-rp-change-proof=\"hosted-preview\"]",
+      "text": "hosted preview change proof"
+    },
+    { "type": "no_mobile_horizontal_overflow" },
+    { "type": "no_fatal_console_errors" }
+  ],
+  "artifacts": ["screenshot", "console", "dom_summary", "proof_json"],
+  "failure_policy": {
+    "environment_blocked": "neutral",
+    "proof_insufficient": "fail",
+    "product_regression": "fail"
+  }
+}

package/package.json

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