@riddledc/riddle-proof 0.7.54 → 0.7.56

package/README.md

@@ -174,6 +174,9 @@ riddle-proof-loop run-profile \
 Hosted profile runs emit Riddle poll progress to stderr while waiting. Use
 `--quiet` to suppress progress lines, or `--progress-every-ms` to tune the
 heartbeat cadence for long route-inventory or workflow profiles.
+Strict Riddle script validation remains on by default; use `--strict=false`
+only for trusted profile-generated scripts when the validator blocks a large
+workflow profile.
 
 The package includes a generic starter profile at
 `examples/profiles/page-content-basic.json`; copy that shape into a repository
@@ -303,6 +306,22 @@ These checks are useful for audit/no-diff profiles where the product should
 show a fallback state and avoid rendering stale loaders, duplicate rows, or
 missing-resource iframes.
 
+Use `url_search_param_equals` and `url_search_param_absent` when the final URL
+is part of the contract, such as deep-link recovery that must drop a stale
+local identifier while preserving shareable query state:
+
+```json
+[
+  { "type": "url_search_param_absent", "param": "seq" },
+  { "type": "url_search_param_equals", "param": "song", "expected_value": "monkberry-moon-delight-tab" },
+  { "type": "url_search_param_equals", "param": "view", "expected_value": "trainer" }
+]
+```
+
+The check uses the captured browser URL for each viewport after setup actions
+and waits have completed. `search_param` and `key` are accepted as aliases for
+`param`; `value` is accepted as an alias for `expected_value`.
+
 Use `selector_text_order` when a table, list, or card group must show visible
 items in a specific order after setup actions such as sorting or filtering:
 

package/dist/{chunk-H3DOYKAQ.js → chunk-2JFDTCIC.js}

@@ -12,6 +12,8 @@ var RIDDLE_PROOF_PROFILE_STATUSES = [
 ];
 var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "route_loaded",
+  "url_search_param_equals",
+  "url_search_param_absent",
   "selector_visible",
   "selector_absent",
   "selector_count_at_least",
@@ -488,6 +490,13 @@ function normalizeCheck(input, index) {
   if ((type === "text_visible" || type === "text_absent") && !stringValue(input.text) && !stringValue(input.pattern)) {
     throw new Error(`checks[${index}] ${type} requires text or pattern.`);
   }
+  if ((type === "url_search_param_equals" || type === "url_search_param_absent") && !stringValue(input.param) && !stringValue(input.search_param) && !stringValue(input.searchParam) && !stringValue(input.key)) {
+    throw new Error(`checks[${index}] ${type} requires param.`);
+  }
+  const expectedValue = stringFromOwn(input, "expected_value", "expectedValue", "value");
+  if (type === "url_search_param_equals" && expectedValue === void 0) {
+    throw new Error(`checks[${index}] url_search_param_equals requires expected_value.`);
+  }
   if (type === "selector_count_at_least" && numberValue(input.min_count) === void 0) {
     throw new Error(`checks[${index}] selector_count_at_least requires min_count.`);
   }
@@ -508,6 +517,8 @@ function normalizeCheck(input, index) {
     type,
     label: stringValue(input.label),
     expected_path: stringValue(input.expected_path),
+    param: stringValue(input.param) || stringValue(input.search_param) || stringValue(input.searchParam) || stringValue(input.key),
+    expected_value: expectedValue,
     expected_routes: expectedRoutes,
     selector: stringValue(input.selector),
     expected_texts: expectedTexts,
@@ -760,6 +771,32 @@ function successfulRoute(route, targetUrl) {
   const matched = route.matched || routePathMatches(route.observed, route.expected_path, targetUrl);
   return matched && !route.error && (route.http_status === null || route.http_status === void 0 || route.http_status < 400);
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return void 0;
+  try {
+    return targetUrl ? new URL(value, targetUrl) : new URL(value);
+  } catch {
+    try {
+      return new URL(value);
+    } catch {
+      return void 0;
+    }
+  }
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport.url, targetUrl) || parseEvidenceUrl(viewport.route?.observed, targetUrl) || parseEvidenceUrl(viewport.route?.requested, targetUrl) || parseEvidenceUrl(targetUrl, void 0);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport.name,
+    url: url?.href || null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0
+  };
+}
 function viewportsForCheck(check, viewports) {
   if (!check.viewports?.length) return viewports;
   const names = new Set(check.viewports);
@@ -797,6 +834,44 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed.length ? `Route did not load as ${expectedPath} in ${failed.length} viewport(s).` : void 0
     };
   }
+  if (check.type === "url_search_param_equals") {
+    const param = check.param || "";
+    const expectedValue = check.expected_value ?? "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.value !== expectedValue);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        expected_value: expectedValue,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} did not equal ${JSON.stringify(expectedValue)} in ${failed.length} viewport(s).` : void 0
+    };
+  }
+  if (check.type === "url_search_param_absent") {
+    const param = check.param || "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.present);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} was present in ${failed.length} viewport(s).` : void 0
+    };
+  }
   if (check.type === "selector_visible") {
     const key = selectorKey(check);
     const failed = viewports.filter((viewport) => (viewport.selectors?.[key]?.visible_count || 0) < 1);
@@ -1332,6 +1407,29 @@ function routePathMatches(observed, expected, targetUrl) {
 function routeOk(route, targetUrl) {
   return Boolean(route && (route.matched || routePathMatches(route.observed, route.expected_path, targetUrl)) && !route.error && (route.http_status == null || route.http_status < 400));
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return null;
+  try { return targetUrl ? new URL(value, targetUrl) : new URL(value); } catch {}
+  try { return new URL(value); } catch {}
+  return null;
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport && viewport.url, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.observed, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.requested, targetUrl)
+    || parseEvidenceUrl(targetUrl, null);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport && viewport.name,
+    url: url ? url.href : null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0,
+  };
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -1636,6 +1734,46 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "url_search_param_equals") {
+      const param = check.param || "";
+      const expectedValue = check.expected_value == null ? "" : String(check.expected_value);
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.value !== expectedValue);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          expected_value: expectedValue,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " did not equal " + JSON.stringify(expectedValue) + " in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
+    if (check.type === "url_search_param_absent") {
+      const param = check.param || "";
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.present);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " was present in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "selector_visible") {
       const selector = check.selector || "";
       const failed = checkViewports.filter((viewport) => !viewport.selectors || !viewport.selectors[selector] || viewport.selectors[selector].visible_count < 1);

package/dist/cli.cjs

@@ -6885,6 +6885,8 @@ var RIDDLE_PROOF_PROFILE_STATUSES = [
 ];
 var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "route_loaded",
+  "url_search_param_equals",
+  "url_search_param_absent",
   "selector_visible",
   "selector_absent",
   "selector_count_at_least",
@@ -7361,6 +7363,13 @@ function normalizeCheck(input, index) {
   if ((type === "text_visible" || type === "text_absent") && !stringValue2(input.text) && !stringValue2(input.pattern)) {
     throw new Error(`checks[${index}] ${type} requires text or pattern.`);
   }
+  if ((type === "url_search_param_equals" || type === "url_search_param_absent") && !stringValue2(input.param) && !stringValue2(input.search_param) && !stringValue2(input.searchParam) && !stringValue2(input.key)) {
+    throw new Error(`checks[${index}] ${type} requires param.`);
+  }
+  const expectedValue = stringFromOwn(input, "expected_value", "expectedValue", "value");
+  if (type === "url_search_param_equals" && expectedValue === void 0) {
+    throw new Error(`checks[${index}] url_search_param_equals requires expected_value.`);
+  }
   if (type === "selector_count_at_least" && numberValue(input.min_count) === void 0) {
     throw new Error(`checks[${index}] selector_count_at_least requires min_count.`);
   }
@@ -7381,6 +7390,8 @@ function normalizeCheck(input, index) {
     type,
     label: stringValue2(input.label),
     expected_path: stringValue2(input.expected_path),
+    param: stringValue2(input.param) || stringValue2(input.search_param) || stringValue2(input.searchParam) || stringValue2(input.key),
+    expected_value: expectedValue,
     expected_routes: expectedRoutes,
     selector: stringValue2(input.selector),
     expected_texts: expectedTexts,
@@ -7633,6 +7644,32 @@ function successfulRoute(route, targetUrl) {
   const matched = route.matched || routePathMatches(route.observed, route.expected_path, targetUrl);
   return matched && !route.error && (route.http_status === null || route.http_status === void 0 || route.http_status < 400);
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return void 0;
+  try {
+    return targetUrl ? new URL(value, targetUrl) : new URL(value);
+  } catch {
+    try {
+      return new URL(value);
+    } catch {
+      return void 0;
+    }
+  }
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport.url, targetUrl) || parseEvidenceUrl(viewport.route?.observed, targetUrl) || parseEvidenceUrl(viewport.route?.requested, targetUrl) || parseEvidenceUrl(targetUrl, void 0);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport.name,
+    url: url?.href || null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0
+  };
+}
 function viewportsForCheck(check, viewports) {
   if (!check.viewports?.length) return viewports;
   const names = new Set(check.viewports);
@@ -7670,6 +7707,44 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed.length ? `Route did not load as ${expectedPath} in ${failed.length} viewport(s).` : void 0
     };
   }
+  if (check.type === "url_search_param_equals") {
+    const param = check.param || "";
+    const expectedValue = check.expected_value ?? "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.value !== expectedValue);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        expected_value: expectedValue,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} did not equal ${JSON.stringify(expectedValue)} in ${failed.length} viewport(s).` : void 0
+    };
+  }
+  if (check.type === "url_search_param_absent") {
+    const param = check.param || "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.present);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} was present in ${failed.length} viewport(s).` : void 0
+    };
+  }
   if (check.type === "selector_visible") {
     const key = selectorKey(check);
     const failed = viewports.filter((viewport) => (viewport.selectors?.[key]?.visible_count || 0) < 1);
@@ -8189,6 +8264,29 @@ function routePathMatches(observed, expected, targetUrl) {
 function routeOk(route, targetUrl) {
   return Boolean(route && (route.matched || routePathMatches(route.observed, route.expected_path, targetUrl)) && !route.error && (route.http_status == null || route.http_status < 400));
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return null;
+  try { return targetUrl ? new URL(value, targetUrl) : new URL(value); } catch {}
+  try { return new URL(value); } catch {}
+  return null;
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport && viewport.url, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.observed, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.requested, targetUrl)
+    || parseEvidenceUrl(targetUrl, null);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport && viewport.name,
+    url: url ? url.href : null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0,
+  };
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -8493,6 +8591,46 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "url_search_param_equals") {
+      const param = check.param || "";
+      const expectedValue = check.expected_value == null ? "" : String(check.expected_value);
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.value !== expectedValue);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          expected_value: expectedValue,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " did not equal " + JSON.stringify(expectedValue) + " in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
+    if (check.type === "url_search_param_absent") {
+      const param = check.param || "";
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.present);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " was present in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "selector_visible") {
       const selector = check.selector || "";
       const failed = checkViewports.filter((viewport) => !viewport.selectors || !viewport.selectors[selector] || viewport.selectors[selector].visible_count < 1);
@@ -10138,7 +10276,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--output <dir>] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false] [--output <dir>] [--quiet]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
     "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720] [--strict true|false]",
@@ -10496,6 +10634,7 @@ async function runProfileForCli(profile, options) {
         profile,
         optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0
       ),
+      strict: optionBoolean(options, "strict"),
       sync: options.sync === true ? true : void 0
     });
   } catch (error) {

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-H3DOYKAQ.js";
+} from "./chunk-2JFDTCIC.js";
 import {
   createRiddleApiClient,
   parseRiddleViewport
@@ -44,7 +44,7 @@ function usage() {
     "  riddle-proof-loop respond --state-path <path> --response-json <file|json|->",
     "  riddle-proof-loop respond --state-path <path> --decision <decision> --summary <text> [--payload-json <file|json|->]",
     "  riddle-proof-loop status --state-path <path>",
-    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--output <dir>] [--quiet]",
+    "  riddle-proof-loop run-profile --profile <file|json|-> --url <base-url> [--runner riddle] [--strict true|false] [--output <dir>] [--quiet]",
     "  riddle-proof-loop riddle-preview-deploy <build-dir> <label>",
     "  riddle-proof-loop riddle-server-preview <directory> --script-file <file> [--path /route] [--wait-for-selector selector]",
     "  riddle-proof-loop riddle-run-script --url <url> --script-file <file> [--viewport 1280x720] [--strict true|false]",
@@ -402,6 +402,7 @@ async function runProfileForCli(profile, options) {
         profile,
         optionString(options, "timeout") ? Number(optionString(options, "timeout")) : void 0
       ),
+      strict: optionBoolean(options, "strict"),
       sync: options.sync === true ? true : void 0
     });
   } catch (error) {

package/dist/index.cjs

@@ -8726,6 +8726,8 @@ var RIDDLE_PROOF_PROFILE_STATUSES = [
 ];
 var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "route_loaded",
+  "url_search_param_equals",
+  "url_search_param_absent",
   "selector_visible",
   "selector_absent",
   "selector_count_at_least",
@@ -9202,6 +9204,13 @@ function normalizeCheck(input, index) {
   if ((type === "text_visible" || type === "text_absent") && !stringValue5(input.text) && !stringValue5(input.pattern)) {
     throw new Error(`checks[${index}] ${type} requires text or pattern.`);
   }
+  if ((type === "url_search_param_equals" || type === "url_search_param_absent") && !stringValue5(input.param) && !stringValue5(input.search_param) && !stringValue5(input.searchParam) && !stringValue5(input.key)) {
+    throw new Error(`checks[${index}] ${type} requires param.`);
+  }
+  const expectedValue = stringFromOwn(input, "expected_value", "expectedValue", "value");
+  if (type === "url_search_param_equals" && expectedValue === void 0) {
+    throw new Error(`checks[${index}] url_search_param_equals requires expected_value.`);
+  }
   if (type === "selector_count_at_least" && numberValue3(input.min_count) === void 0) {
     throw new Error(`checks[${index}] selector_count_at_least requires min_count.`);
   }
@@ -9222,6 +9231,8 @@ function normalizeCheck(input, index) {
     type,
     label: stringValue5(input.label),
     expected_path: stringValue5(input.expected_path),
+    param: stringValue5(input.param) || stringValue5(input.search_param) || stringValue5(input.searchParam) || stringValue5(input.key),
+    expected_value: expectedValue,
     expected_routes: expectedRoutes,
     selector: stringValue5(input.selector),
     expected_texts: expectedTexts,
@@ -9474,6 +9485,32 @@ function successfulRoute(route, targetUrl) {
   const matched = route.matched || routePathMatches(route.observed, route.expected_path, targetUrl);
   return matched && !route.error && (route.http_status === null || route.http_status === void 0 || route.http_status < 400);
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return void 0;
+  try {
+    return targetUrl ? new URL(value, targetUrl) : new URL(value);
+  } catch {
+    try {
+      return new URL(value);
+    } catch {
+      return void 0;
+    }
+  }
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport.url, targetUrl) || parseEvidenceUrl(viewport.route?.observed, targetUrl) || parseEvidenceUrl(viewport.route?.requested, targetUrl) || parseEvidenceUrl(targetUrl, void 0);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport.name,
+    url: url?.href || null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0
+  };
+}
 function viewportsForCheck(check, viewports) {
   if (!check.viewports?.length) return viewports;
   const names = new Set(check.viewports);
@@ -9511,6 +9548,44 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed.length ? `Route did not load as ${expectedPath} in ${failed.length} viewport(s).` : void 0
     };
   }
+  if (check.type === "url_search_param_equals") {
+    const param = check.param || "";
+    const expectedValue = check.expected_value ?? "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.value !== expectedValue);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        expected_value: expectedValue,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} did not equal ${JSON.stringify(expectedValue)} in ${failed.length} viewport(s).` : void 0
+    };
+  }
+  if (check.type === "url_search_param_absent") {
+    const param = check.param || "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.present);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} was present in ${failed.length} viewport(s).` : void 0
+    };
+  }
   if (check.type === "selector_visible") {
     const key = selectorKey(check);
     const failed = viewports.filter((viewport) => (viewport.selectors?.[key]?.visible_count || 0) < 1);
@@ -10046,6 +10121,29 @@ function routePathMatches(observed, expected, targetUrl) {
 function routeOk(route, targetUrl) {
   return Boolean(route && (route.matched || routePathMatches(route.observed, route.expected_path, targetUrl)) && !route.error && (route.http_status == null || route.http_status < 400));
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return null;
+  try { return targetUrl ? new URL(value, targetUrl) : new URL(value); } catch {}
+  try { return new URL(value); } catch {}
+  return null;
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport && viewport.url, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.observed, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.requested, targetUrl)
+    || parseEvidenceUrl(targetUrl, null);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport && viewport.name,
+    url: url ? url.href : null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0,
+  };
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -10350,6 +10448,46 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "url_search_param_equals") {
+      const param = check.param || "";
+      const expectedValue = check.expected_value == null ? "" : String(check.expected_value);
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.value !== expectedValue);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          expected_value: expectedValue,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " did not equal " + JSON.stringify(expectedValue) + " in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
+    if (check.type === "url_search_param_absent") {
+      const param = check.param || "";
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.present);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " was present in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "selector_visible") {
       const selector = check.selector || "";
       const failed = checkViewports.filter((viewport) => !viewport.selectors || !viewport.selectors[selector] || viewport.selectors[selector].visible_count < 1);

package/dist/index.js

@@ -58,7 +58,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-H3DOYKAQ.js";
+} from "./chunk-2JFDTCIC.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,

package/dist/profile.cjs

@@ -55,6 +55,8 @@ var RIDDLE_PROOF_PROFILE_STATUSES = [
 ];
 var RIDDLE_PROOF_PROFILE_CHECK_TYPES = [
   "route_loaded",
+  "url_search_param_equals",
+  "url_search_param_absent",
   "selector_visible",
   "selector_absent",
   "selector_count_at_least",
@@ -531,6 +533,13 @@ function normalizeCheck(input, index) {
   if ((type === "text_visible" || type === "text_absent") && !stringValue(input.text) && !stringValue(input.pattern)) {
     throw new Error(`checks[${index}] ${type} requires text or pattern.`);
   }
+  if ((type === "url_search_param_equals" || type === "url_search_param_absent") && !stringValue(input.param) && !stringValue(input.search_param) && !stringValue(input.searchParam) && !stringValue(input.key)) {
+    throw new Error(`checks[${index}] ${type} requires param.`);
+  }
+  const expectedValue = stringFromOwn(input, "expected_value", "expectedValue", "value");
+  if (type === "url_search_param_equals" && expectedValue === void 0) {
+    throw new Error(`checks[${index}] url_search_param_equals requires expected_value.`);
+  }
   if (type === "selector_count_at_least" && numberValue(input.min_count) === void 0) {
     throw new Error(`checks[${index}] selector_count_at_least requires min_count.`);
   }
@@ -551,6 +560,8 @@ function normalizeCheck(input, index) {
     type,
     label: stringValue(input.label),
     expected_path: stringValue(input.expected_path),
+    param: stringValue(input.param) || stringValue(input.search_param) || stringValue(input.searchParam) || stringValue(input.key),
+    expected_value: expectedValue,
     expected_routes: expectedRoutes,
     selector: stringValue(input.selector),
     expected_texts: expectedTexts,
@@ -803,6 +814,32 @@ function successfulRoute(route, targetUrl) {
   const matched = route.matched || routePathMatches(route.observed, route.expected_path, targetUrl);
   return matched && !route.error && (route.http_status === null || route.http_status === void 0 || route.http_status < 400);
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return void 0;
+  try {
+    return targetUrl ? new URL(value, targetUrl) : new URL(value);
+  } catch {
+    try {
+      return new URL(value);
+    } catch {
+      return void 0;
+    }
+  }
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport.url, targetUrl) || parseEvidenceUrl(viewport.route?.observed, targetUrl) || parseEvidenceUrl(viewport.route?.requested, targetUrl) || parseEvidenceUrl(targetUrl, void 0);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport.name,
+    url: url?.href || null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0
+  };
+}
 function viewportsForCheck(check, viewports) {
   if (!check.viewports?.length) return viewports;
   const names = new Set(check.viewports);
@@ -840,6 +877,44 @@ function assessCheckFromEvidence(check, evidence) {
       message: failed.length ? `Route did not load as ${expectedPath} in ${failed.length} viewport(s).` : void 0
     };
   }
+  if (check.type === "url_search_param_equals") {
+    const param = check.param || "";
+    const expectedValue = check.expected_value ?? "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.value !== expectedValue);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        expected_value: expectedValue,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} did not equal ${JSON.stringify(expectedValue)} in ${failed.length} viewport(s).` : void 0
+    };
+  }
+  if (check.type === "url_search_param_absent") {
+    const param = check.param || "";
+    const observations = viewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+    const failed = observations.filter((observation) => observation.present);
+    return {
+      type: check.type,
+      label: checkLabel(check),
+      status: failed.length ? "failed" : "passed",
+      evidence: {
+        param,
+        observed_values: observations.map((observation) => observation.value),
+        observed_all_values: observations.map((observation) => observation.values),
+        observed_urls: observations.map((observation) => observation.url),
+        viewports: observations.map((observation) => toJsonValue(observation))
+      },
+      message: failed.length ? `URL search param ${param} was present in ${failed.length} viewport(s).` : void 0
+    };
+  }
   if (check.type === "selector_visible") {
     const key = selectorKey(check);
     const failed = viewports.filter((viewport) => (viewport.selectors?.[key]?.visible_count || 0) < 1);
@@ -1375,6 +1450,29 @@ function routePathMatches(observed, expected, targetUrl) {
 function routeOk(route, targetUrl) {
   return Boolean(route && (route.matched || routePathMatches(route.observed, route.expected_path, targetUrl)) && !route.error && (route.http_status == null || route.http_status < 400));
 }
+function parseEvidenceUrl(value, targetUrl) {
+  if (!value) return null;
+  try { return targetUrl ? new URL(value, targetUrl) : new URL(value); } catch {}
+  try { return new URL(value); } catch {}
+  return null;
+}
+function observedUrlForViewport(viewport, targetUrl) {
+  return parseEvidenceUrl(viewport && viewport.url, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.observed, targetUrl)
+    || parseEvidenceUrl(viewport && viewport.route && viewport.route.requested, targetUrl)
+    || parseEvidenceUrl(targetUrl, null);
+}
+function searchParamObservation(viewport, targetUrl, param) {
+  const url = observedUrlForViewport(viewport, targetUrl);
+  const values = url ? url.searchParams.getAll(param) : [];
+  return {
+    viewport: viewport && viewport.name,
+    url: url ? url.href : null,
+    value: values.length ? values[0] : null,
+    values,
+    present: values.length > 0,
+  };
+}
 function textMatches(sample, check) {
   if (check.pattern) {
     try { return new RegExp(check.pattern, check.flags || "").test(sample || ""); } catch { return false; }
@@ -1679,6 +1777,46 @@ function assessProfile(profile, evidence) {
       });
       continue;
     }
+    if (check.type === "url_search_param_equals") {
+      const param = check.param || "";
+      const expectedValue = check.expected_value == null ? "" : String(check.expected_value);
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.value !== expectedValue);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          expected_value: expectedValue,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " did not equal " + JSON.stringify(expectedValue) + " in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
+    if (check.type === "url_search_param_absent") {
+      const param = check.param || "";
+      const observations = checkViewports.map((viewport) => searchParamObservation(viewport, evidence.target_url, param));
+      const failed = observations.filter((observation) => observation.present);
+      checks.push({
+        type: check.type,
+        label: check.label || check.type,
+        status: failed.length ? "failed" : "passed",
+        evidence: {
+          param,
+          observed_values: observations.map((observation) => observation.value),
+          observed_all_values: observations.map((observation) => observation.values),
+          observed_urls: observations.map((observation) => observation.url),
+          viewports: observations,
+        },
+        message: failed.length ? "URL search param " + param + " was present in " + failed.length + " viewport(s)." : undefined,
+      });
+      continue;
+    }
     if (check.type === "selector_visible") {
       const selector = check.selector || "";
       const failed = checkViewports.filter((viewport) => !viewport.selectors || !viewport.selectors[selector] || viewport.selectors[selector].visible_count < 1);

package/dist/profile.d.cts

@@ -4,7 +4,7 @@ declare const RIDDLE_PROOF_PROFILE_VERSION: "riddle-proof.profile.v1";
 declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evidence.v1";
 declare const RIDDLE_PROOF_PROFILE_RESULT_VERSION: "riddle-proof.profile-result.v1";
 declare const RIDDLE_PROOF_PROFILE_STATUSES: readonly ["passed", "product_regression", "proof_insufficient", "environment_blocked", "configuration_error", "needs_human_review"];
-declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "selector_text_order", "frame_text_visible", "frame_no_horizontal_overflow", "text_visible", "text_absent", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
+declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "url_search_param_equals", "url_search_param_absent", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "selector_text_order", "frame_text_visible", "frame_no_horizontal_overflow", "text_visible", "text_absent", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
 declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "fill", "set_input_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "local_storage", "session_storage", "clear_storage", "wait", "wait_for_selector", "wait_for_text", "window_call"];
 type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
 type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
@@ -88,6 +88,8 @@ interface RiddleProofProfileCheck {
     type: RiddleProofProfileCheckType;
     label?: string;
     expected_path?: string;
+    param?: string;
+    expected_value?: string;
     expected_routes?: RiddleProofProfileRouteInventoryRoute[];
     selector?: string;
     expected_texts?: string[];

package/dist/profile.d.ts

@@ -4,7 +4,7 @@ declare const RIDDLE_PROOF_PROFILE_VERSION: "riddle-proof.profile.v1";
 declare const RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION: "riddle-proof.profile-evidence.v1";
 declare const RIDDLE_PROOF_PROFILE_RESULT_VERSION: "riddle-proof.profile-result.v1";
 declare const RIDDLE_PROOF_PROFILE_STATUSES: readonly ["passed", "product_regression", "proof_insufficient", "environment_blocked", "configuration_error", "needs_human_review"];
-declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "selector_text_order", "frame_text_visible", "frame_no_horizontal_overflow", "text_visible", "text_absent", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
+declare const RIDDLE_PROOF_PROFILE_CHECK_TYPES: readonly ["route_loaded", "url_search_param_equals", "url_search_param_absent", "selector_visible", "selector_absent", "selector_count_at_least", "selector_count_equals", "selector_count_equal", "selector_count_eq", "selector_text_order", "frame_text_visible", "frame_no_horizontal_overflow", "text_visible", "text_absent", "route_inventory", "no_horizontal_overflow", "no_mobile_horizontal_overflow", "no_fatal_console_errors"];
 declare const RIDDLE_PROOF_PROFILE_SETUP_ACTION_TYPES: readonly ["click", "fill", "set_input_value", "assert_text_visible", "assert_text_absent", "assert_selector_count", "assert_window_value", "local_storage", "session_storage", "clear_storage", "wait", "wait_for_selector", "wait_for_text", "window_call"];
 type RiddleProofProfileStatus = typeof RIDDLE_PROOF_PROFILE_STATUSES[number];
 type RiddleProofProfileCheckType = typeof RIDDLE_PROOF_PROFILE_CHECK_TYPES[number];
@@ -88,6 +88,8 @@ interface RiddleProofProfileCheck {
     type: RiddleProofProfileCheckType;
     label?: string;
     expected_path?: string;
+    param?: string;
+    expected_value?: string;
     expected_routes?: RiddleProofProfileRouteInventoryRoute[];
     selector?: string;
     expected_texts?: string[];

package/dist/profile.js

@@ -19,7 +19,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-H3DOYKAQ.js";
+} from "./chunk-2JFDTCIC.js";
 export {
   RIDDLE_PROOF_PROFILE_CHECK_TYPES,
   RIDDLE_PROOF_PROFILE_EVIDENCE_VERSION,

package/package.json

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