@riddledc/riddle-proof 0.7.65 → 0.7.67

package/README.md

@@ -226,6 +226,25 @@ cycle instead of reusing the final response, for example to repeat a fail-then-
 success pair across multiple viewports. Repeated sequences also record
 `sequence_cycle: true` after the first cycle.
 
+Use `max_hit_count` / `max_hits` when a profile needs to prove a request does
+not run too many times. Use `forbidden: true` as shorthand for
+`max_hit_count: 0` and `required: false`, for example when a chat failure must
+not trigger a downstream build:
+
+```json
+{
+  "label": "builder-build-should-not-run",
+  "url": "**/api/build",
+  "method": "POST",
+  "forbidden": true,
+  "json": { "previewUrl": "https://cdn.example/should-not-run/index.html" }
+}
+```
+
+The implicit `network_mocks_succeeded` check records `max_hits_by_label` and
+fails with `forbidden_mock_hit` or `mock_hit_count_exceeded` when a cap is
+exceeded.
+
 Set `capture_request_body: true` to include compact request-body evidence on
 mock hits. Add `request_body_contains` / `request_body_patterns` or
 `request_body_not_contains` / `request_body_not_patterns` when the request body

package/dist/{chunk-DQU65Z65.js → chunk-376FPGFA.js}

@@ -470,6 +470,22 @@ function normalizeNetworkMock(input, index) {
   if (requiredHitCount !== void 0 && (!Number.isInteger(requiredHitCount) || requiredHitCount < 1)) {
     throw new Error(`target.network_mocks[${index}].required_hit_count must be a positive integer.`);
   }
+  const forbidden = input.forbidden === true || input.must_not_hit === true || input.mustNotHit === true || input.should_not_run === true || input.shouldNotRun === true;
+  const configuredMaxHitCount = numberValue(
+    input.max_hit_count ?? input.maxHitCount ?? input.max_hits ?? input.maxHits
+  );
+  if (configuredMaxHitCount !== void 0 && (!Number.isInteger(configuredMaxHitCount) || configuredMaxHitCount < 0)) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count must be a non-negative integer.`);
+  }
+  if (forbidden && configuredMaxHitCount !== void 0 && configuredMaxHitCount !== 0) {
+    throw new Error(`target.network_mocks[${index}].forbidden cannot be combined with max_hit_count greater than 0.`);
+  }
+  const maxHitCount = forbidden ? 0 : configuredMaxHitCount;
+  const required = input.required === false || maxHitCount === 0 && input.required !== true ? false : true;
+  const effectiveRequiredHitCount = required ? requiredHitCount ?? (Array.isArray(responses) && responses.length ? responses.length : 1) : 0;
+  if (maxHitCount !== void 0 && effectiveRequiredHitCount > maxHitCount) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count cannot be less than its required hit count.`);
+  }
   return {
     ...payload,
     label: normalizeName(input.label || input.name, `network-mock-${index + 1}`),
@@ -478,7 +494,9 @@ function normalizeNetworkMock(input, index) {
     responses,
     repeat_responses: input.repeat_responses === true || input.repeatResponses === true || input.cycle_responses === true || input.cycleResponses === true,
     required_hit_count: requiredHitCount,
-    required: input.required === false ? false : true,
+    max_hit_count: maxHitCount,
+    forbidden,
+    required,
     capture_request_body: requestBody.capture_request_body,
     request_body_contains: requestBody.request_body_contains,
     request_body_patterns: requestBody.request_body_patterns,
@@ -1388,8 +1406,9 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
   const events = evidence.network_mocks || [];
   const failed = [];
   const requiredMocks = mocks.filter((mock) => mock.required !== false);
+  const hitCountForMock = (mock) => events.filter((event) => event.label === mock.label && event.ok !== false).length;
   for (const mock of requiredMocks) {
-    const hits = events.filter((event) => event.label === mock.label && event.ok !== false).length;
+    const hits = hitCountForMock(mock);
     const requiredHitCount = requiredNetworkMockHitCount(mock);
     if (hits < requiredHitCount) {
       failed.push({
@@ -1402,6 +1421,20 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       });
     }
   }
+  for (const mock of mocks) {
+    if (mock.max_hit_count === void 0) continue;
+    const hits = hitCountForMock(mock);
+    if (hits > mock.max_hit_count) {
+      failed.push({
+        label: mock.label,
+        url: mock.url,
+        method: mock.method || null,
+        reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+        max_hit_count: mock.max_hit_count,
+        hit_count: hits
+      });
+    }
+  }
   for (const event of events) {
     if (event.ok === false) {
       failed.push({
@@ -1436,15 +1469,16 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       hit_count: events.filter((event) => event.ok !== false).length,
       hits_by_label: Object.fromEntries(mocks.map((mock) => [
         mock.label,
-        events.filter((event) => event.label === mock.label && event.ok !== false).length
+        hitCountForMock(mock)
       ])),
       required_hits_by_label: Object.fromEntries(requiredMocks.map((mock) => [
         mock.label,
         requiredNetworkMockHitCount(mock)
       ])),
+      max_hits_by_label: Object.fromEntries(mocks.filter((mock) => mock.max_hit_count !== void 0).map((mock) => [mock.label, mock.max_hit_count ?? null])),
       failed
     },
-    message: failed.length ? `Network mocks failed or were not hit for ${failed.length} mock(s).` : void 0
+    message: failed.length ? `Network mocks failed or hit-count contracts failed for ${failed.length} mock(s).` : void 0
   };
 }
 function requiredNetworkMockHitCount(mock) {
@@ -1904,8 +1938,9 @@ function assessProfile(profile, evidence) {
     const events = evidence.network_mocks || [];
     const requiredMocks = profile.target.network_mocks.filter((mock) => mock && mock.required !== false);
     const failed = [];
+    const hitCountForMock = (mock) => events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
     for (const mock of requiredMocks) {
-      const hits = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      const hits = hitCountForMock(mock);
       const requiredHitCount = requiredNetworkMockHitCount(mock);
       if (hits < requiredHitCount) {
         failed.push({
@@ -1918,6 +1953,20 @@ function assessProfile(profile, evidence) {
         });
       }
     }
+    for (const mock of profile.target.network_mocks) {
+      if (!mock || mock.max_hit_count === undefined) continue;
+      const hits = hitCountForMock(mock);
+      if (hits > mock.max_hit_count) {
+        failed.push({
+          label: mock.label,
+          url: mock.url,
+          method: mock.method || null,
+          reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+          max_hit_count: mock.max_hit_count,
+          hit_count: hits,
+        });
+      }
+    }
     for (const event of events) {
       if (event && event.ok === false) {
         failed.push({
@@ -1944,9 +1993,11 @@ function assessProfile(profile, evidence) {
     }
     const hitsByLabel = {};
     const requiredHitsByLabel = {};
+    const maxHitsByLabel = {};
     for (const mock of profile.target.network_mocks) {
-      hitsByLabel[mock.label] = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      hitsByLabel[mock.label] = hitCountForMock(mock);
       if (mock && mock.required !== false) requiredHitsByLabel[mock.label] = requiredNetworkMockHitCount(mock);
+      if (mock && mock.max_hit_count !== undefined) maxHitsByLabel[mock.label] = mock.max_hit_count;
     }
     checks.push({
       type: "network_mocks_succeeded",
@@ -1958,9 +2009,10 @@ function assessProfile(profile, evidence) {
         hit_count: events.filter((event) => event && event.ok !== false).length,
         hits_by_label: hitsByLabel,
         required_hits_by_label: requiredHitsByLabel,
+        max_hits_by_label: maxHitsByLabel,
         failed,
       },
-      message: failed.length ? "Network mocks failed or were not hit for " + failed.length + " mock(s)." : undefined,
+      message: failed.length ? "Network mocks failed or hit-count contracts failed for " + failed.length + " mock(s)." : undefined,
     });
   }
   if (profile.target && Array.isArray(profile.target.setup_actions) && profile.target.setup_actions.length) {

package/dist/cli.cjs

@@ -7343,6 +7343,22 @@ function normalizeNetworkMock(input, index) {
   if (requiredHitCount !== void 0 && (!Number.isInteger(requiredHitCount) || requiredHitCount < 1)) {
     throw new Error(`target.network_mocks[${index}].required_hit_count must be a positive integer.`);
   }
+  const forbidden = input.forbidden === true || input.must_not_hit === true || input.mustNotHit === true || input.should_not_run === true || input.shouldNotRun === true;
+  const configuredMaxHitCount = numberValue(
+    input.max_hit_count ?? input.maxHitCount ?? input.max_hits ?? input.maxHits
+  );
+  if (configuredMaxHitCount !== void 0 && (!Number.isInteger(configuredMaxHitCount) || configuredMaxHitCount < 0)) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count must be a non-negative integer.`);
+  }
+  if (forbidden && configuredMaxHitCount !== void 0 && configuredMaxHitCount !== 0) {
+    throw new Error(`target.network_mocks[${index}].forbidden cannot be combined with max_hit_count greater than 0.`);
+  }
+  const maxHitCount = forbidden ? 0 : configuredMaxHitCount;
+  const required = input.required === false || maxHitCount === 0 && input.required !== true ? false : true;
+  const effectiveRequiredHitCount = required ? requiredHitCount ?? (Array.isArray(responses) && responses.length ? responses.length : 1) : 0;
+  if (maxHitCount !== void 0 && effectiveRequiredHitCount > maxHitCount) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count cannot be less than its required hit count.`);
+  }
   return {
     ...payload,
     label: normalizeName(input.label || input.name, `network-mock-${index + 1}`),
@@ -7351,7 +7367,9 @@ function normalizeNetworkMock(input, index) {
     responses,
     repeat_responses: input.repeat_responses === true || input.repeatResponses === true || input.cycle_responses === true || input.cycleResponses === true,
     required_hit_count: requiredHitCount,
-    required: input.required === false ? false : true,
+    max_hit_count: maxHitCount,
+    forbidden,
+    required,
     capture_request_body: requestBody.capture_request_body,
     request_body_contains: requestBody.request_body_contains,
     request_body_patterns: requestBody.request_body_patterns,
@@ -8261,8 +8279,9 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
   const events = evidence.network_mocks || [];
   const failed = [];
   const requiredMocks = mocks.filter((mock) => mock.required !== false);
+  const hitCountForMock = (mock) => events.filter((event) => event.label === mock.label && event.ok !== false).length;
   for (const mock of requiredMocks) {
-    const hits = events.filter((event) => event.label === mock.label && event.ok !== false).length;
+    const hits = hitCountForMock(mock);
     const requiredHitCount = requiredNetworkMockHitCount(mock);
     if (hits < requiredHitCount) {
       failed.push({
@@ -8275,6 +8294,20 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       });
     }
   }
+  for (const mock of mocks) {
+    if (mock.max_hit_count === void 0) continue;
+    const hits = hitCountForMock(mock);
+    if (hits > mock.max_hit_count) {
+      failed.push({
+        label: mock.label,
+        url: mock.url,
+        method: mock.method || null,
+        reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+        max_hit_count: mock.max_hit_count,
+        hit_count: hits
+      });
+    }
+  }
   for (const event of events) {
     if (event.ok === false) {
       failed.push({
@@ -8309,15 +8342,16 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       hit_count: events.filter((event) => event.ok !== false).length,
       hits_by_label: Object.fromEntries(mocks.map((mock) => [
         mock.label,
-        events.filter((event) => event.label === mock.label && event.ok !== false).length
+        hitCountForMock(mock)
       ])),
       required_hits_by_label: Object.fromEntries(requiredMocks.map((mock) => [
         mock.label,
         requiredNetworkMockHitCount(mock)
       ])),
+      max_hits_by_label: Object.fromEntries(mocks.filter((mock) => mock.max_hit_count !== void 0).map((mock) => [mock.label, mock.max_hit_count ?? null])),
       failed
     },
-    message: failed.length ? `Network mocks failed or were not hit for ${failed.length} mock(s).` : void 0
+    message: failed.length ? `Network mocks failed or hit-count contracts failed for ${failed.length} mock(s).` : void 0
   };
 }
 function requiredNetworkMockHitCount(mock) {
@@ -8761,8 +8795,9 @@ function assessProfile(profile, evidence) {
     const events = evidence.network_mocks || [];
     const requiredMocks = profile.target.network_mocks.filter((mock) => mock && mock.required !== false);
     const failed = [];
+    const hitCountForMock = (mock) => events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
     for (const mock of requiredMocks) {
-      const hits = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      const hits = hitCountForMock(mock);
       const requiredHitCount = requiredNetworkMockHitCount(mock);
       if (hits < requiredHitCount) {
         failed.push({
@@ -8775,6 +8810,20 @@ function assessProfile(profile, evidence) {
         });
       }
     }
+    for (const mock of profile.target.network_mocks) {
+      if (!mock || mock.max_hit_count === undefined) continue;
+      const hits = hitCountForMock(mock);
+      if (hits > mock.max_hit_count) {
+        failed.push({
+          label: mock.label,
+          url: mock.url,
+          method: mock.method || null,
+          reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+          max_hit_count: mock.max_hit_count,
+          hit_count: hits,
+        });
+      }
+    }
     for (const event of events) {
       if (event && event.ok === false) {
         failed.push({
@@ -8801,9 +8850,11 @@ function assessProfile(profile, evidence) {
     }
     const hitsByLabel = {};
     const requiredHitsByLabel = {};
+    const maxHitsByLabel = {};
     for (const mock of profile.target.network_mocks) {
-      hitsByLabel[mock.label] = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      hitsByLabel[mock.label] = hitCountForMock(mock);
       if (mock && mock.required !== false) requiredHitsByLabel[mock.label] = requiredNetworkMockHitCount(mock);
+      if (mock && mock.max_hit_count !== undefined) maxHitsByLabel[mock.label] = mock.max_hit_count;
     }
     checks.push({
       type: "network_mocks_succeeded",
@@ -8815,9 +8866,10 @@ function assessProfile(profile, evidence) {
         hit_count: events.filter((event) => event && event.ok !== false).length,
         hits_by_label: hitsByLabel,
         required_hits_by_label: requiredHitsByLabel,
+        max_hits_by_label: maxHitsByLabel,
         failed,
       },
-      message: failed.length ? "Network mocks failed or were not hit for " + failed.length + " mock(s)." : undefined,
+      message: failed.length ? "Network mocks failed or hit-count contracts failed for " + failed.length + " mock(s)." : undefined,
     });
   }
   if (profile.target && Array.isArray(profile.target.setup_actions) && profile.target.setup_actions.length) {
@@ -11138,6 +11190,10 @@ function profileResultMarkdown(result) {
     lines.push(`- ${check.status}: ${check.label || check.type}`);
     if (check.message) lines.push(`  ${check.message}`);
   }
+  const setupSummaryLines = profileSetupSummaryMarkdown(result);
+  if (setupSummaryLines.length) {
+    lines.push("", "## Setup Summary", "", ...setupSummaryLines);
+  }
   if (result.artifacts.riddle_artifacts?.length) {
     lines.push("", "## Riddle Artifacts", "");
     for (const artifact of result.artifacts.riddle_artifacts.slice(0, 40)) {
@@ -11147,6 +11203,46 @@ function profileResultMarkdown(result) {
   return `${lines.join("\n")}
 `;
 }
+function cliRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function cliFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function cliString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function profileSetupSummaryMarkdown(result) {
+  const setupCheck = result.checks.find((check) => check.type === "setup_actions_succeeded");
+  const setupSummary = cliRecord(setupCheck?.evidence?.setup_summary);
+  if (!setupSummary) return [];
+  const viewports = Array.isArray(setupSummary.viewports) ? setupSummary.viewports.map(cliRecord).filter((viewport) => Boolean(viewport)) : [];
+  if (!viewports.length) return [];
+  const declaredActions = cliFiniteNumber(setupSummary.action_count);
+  const totalResults = viewports.reduce((sum, viewport) => sum + (cliFiniteNumber(viewport.result_count) || 0), 0);
+  const setupScreenshots = viewports.reduce((sum, viewport) => {
+    const labels = Array.isArray(viewport.setup_screenshots) ? viewport.setup_screenshots : [];
+    return sum + labels.filter((label) => typeof label === "string" && label.trim()).length;
+  }, 0);
+  const clickedTotal = viewports.reduce((sum, viewport) => sum + (cliFiniteNumber(viewport.clicked_total) || 0), 0);
+  const failedTotal = viewports.reduce((sum, viewport) => sum + (Array.isArray(viewport.failed) ? viewport.failed.length : 0), 0);
+  const lines = [
+    `- setup actions: ${declaredActions === void 0 ? "unknown" : declaredActions} declared, ${totalResults} recorded result(s) across ${viewports.length} viewport(s)`,
+    `- setup screenshots: ${setupScreenshots}`,
+    `- clicked targets: ${clickedTotal}${failedTotal ? `; failed setup actions: ${failedTotal}` : ""}`
+  ];
+  for (const viewport of viewports.slice(0, 8)) {
+    const name = cliString(viewport.name) || "viewport";
+    const ok = viewport.ok === false ? "failed" : "ok";
+    const resultCount = cliFiniteNumber(viewport.result_count) || 0;
+    const screenshotCount = Array.isArray(viewport.setup_screenshots) ? viewport.setup_screenshots.filter((label) => typeof label === "string" && label.trim()).length : 0;
+    const clicked = cliFiniteNumber(viewport.clicked_total) || 0;
+    const observedPath = cliString(viewport.observed_path);
+    lines.push(`- ${name}: ${ok}, ${resultCount} result(s), ${screenshotCount} setup screenshot(s), ${clicked} click(s)${observedPath ? `, path ${observedPath}` : ""}`);
+  }
+  if (viewports.length > 8) lines.push(`- ${viewports.length - 8} additional viewport(s) omitted from setup summary.`);
+  return lines;
+}
 function writeProfileOutput(outputDir, result) {
   if (!outputDir) return;
   (0, import_node_fs6.mkdirSync)(outputDir, { recursive: true });

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
   profileStatusExitCode,
   resolveRiddleProofProfileTargetUrl,
   resolveRiddleProofProfileTimeoutSec
-} from "./chunk-DQU65Z65.js";
+} from "./chunk-376FPGFA.js";
 import {
   createRiddleApiClient,
   parseRiddleViewport
@@ -312,6 +312,10 @@ function profileResultMarkdown(result) {
     lines.push(`- ${check.status}: ${check.label || check.type}`);
     if (check.message) lines.push(`  ${check.message}`);
   }
+  const setupSummaryLines = profileSetupSummaryMarkdown(result);
+  if (setupSummaryLines.length) {
+    lines.push("", "## Setup Summary", "", ...setupSummaryLines);
+  }
   if (result.artifacts.riddle_artifacts?.length) {
     lines.push("", "## Riddle Artifacts", "");
     for (const artifact of result.artifacts.riddle_artifacts.slice(0, 40)) {
@@ -321,6 +325,46 @@ function profileResultMarkdown(result) {
   return `${lines.join("\n")}
 `;
 }
+function cliRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function cliFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function cliString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function profileSetupSummaryMarkdown(result) {
+  const setupCheck = result.checks.find((check) => check.type === "setup_actions_succeeded");
+  const setupSummary = cliRecord(setupCheck?.evidence?.setup_summary);
+  if (!setupSummary) return [];
+  const viewports = Array.isArray(setupSummary.viewports) ? setupSummary.viewports.map(cliRecord).filter((viewport) => Boolean(viewport)) : [];
+  if (!viewports.length) return [];
+  const declaredActions = cliFiniteNumber(setupSummary.action_count);
+  const totalResults = viewports.reduce((sum, viewport) => sum + (cliFiniteNumber(viewport.result_count) || 0), 0);
+  const setupScreenshots = viewports.reduce((sum, viewport) => {
+    const labels = Array.isArray(viewport.setup_screenshots) ? viewport.setup_screenshots : [];
+    return sum + labels.filter((label) => typeof label === "string" && label.trim()).length;
+  }, 0);
+  const clickedTotal = viewports.reduce((sum, viewport) => sum + (cliFiniteNumber(viewport.clicked_total) || 0), 0);
+  const failedTotal = viewports.reduce((sum, viewport) => sum + (Array.isArray(viewport.failed) ? viewport.failed.length : 0), 0);
+  const lines = [
+    `- setup actions: ${declaredActions === void 0 ? "unknown" : declaredActions} declared, ${totalResults} recorded result(s) across ${viewports.length} viewport(s)`,
+    `- setup screenshots: ${setupScreenshots}`,
+    `- clicked targets: ${clickedTotal}${failedTotal ? `; failed setup actions: ${failedTotal}` : ""}`
+  ];
+  for (const viewport of viewports.slice(0, 8)) {
+    const name = cliString(viewport.name) || "viewport";
+    const ok = viewport.ok === false ? "failed" : "ok";
+    const resultCount = cliFiniteNumber(viewport.result_count) || 0;
+    const screenshotCount = Array.isArray(viewport.setup_screenshots) ? viewport.setup_screenshots.filter((label) => typeof label === "string" && label.trim()).length : 0;
+    const clicked = cliFiniteNumber(viewport.clicked_total) || 0;
+    const observedPath = cliString(viewport.observed_path);
+    lines.push(`- ${name}: ${ok}, ${resultCount} result(s), ${screenshotCount} setup screenshot(s), ${clicked} click(s)${observedPath ? `, path ${observedPath}` : ""}`);
+  }
+  if (viewports.length > 8) lines.push(`- ${viewports.length - 8} additional viewport(s) omitted from setup summary.`);
+  return lines;
+}
 function writeProfileOutput(outputDir, result) {
   if (!outputDir) return;
   mkdirSync(outputDir, { recursive: true });

package/dist/index.cjs

@@ -9184,6 +9184,22 @@ function normalizeNetworkMock(input, index) {
   if (requiredHitCount !== void 0 && (!Number.isInteger(requiredHitCount) || requiredHitCount < 1)) {
     throw new Error(`target.network_mocks[${index}].required_hit_count must be a positive integer.`);
   }
+  const forbidden = input.forbidden === true || input.must_not_hit === true || input.mustNotHit === true || input.should_not_run === true || input.shouldNotRun === true;
+  const configuredMaxHitCount = numberValue3(
+    input.max_hit_count ?? input.maxHitCount ?? input.max_hits ?? input.maxHits
+  );
+  if (configuredMaxHitCount !== void 0 && (!Number.isInteger(configuredMaxHitCount) || configuredMaxHitCount < 0)) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count must be a non-negative integer.`);
+  }
+  if (forbidden && configuredMaxHitCount !== void 0 && configuredMaxHitCount !== 0) {
+    throw new Error(`target.network_mocks[${index}].forbidden cannot be combined with max_hit_count greater than 0.`);
+  }
+  const maxHitCount = forbidden ? 0 : configuredMaxHitCount;
+  const required = input.required === false || maxHitCount === 0 && input.required !== true ? false : true;
+  const effectiveRequiredHitCount = required ? requiredHitCount ?? (Array.isArray(responses) && responses.length ? responses.length : 1) : 0;
+  if (maxHitCount !== void 0 && effectiveRequiredHitCount > maxHitCount) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count cannot be less than its required hit count.`);
+  }
   return {
     ...payload,
     label: normalizeName(input.label || input.name, `network-mock-${index + 1}`),
@@ -9192,7 +9208,9 @@ function normalizeNetworkMock(input, index) {
     responses,
     repeat_responses: input.repeat_responses === true || input.repeatResponses === true || input.cycle_responses === true || input.cycleResponses === true,
     required_hit_count: requiredHitCount,
-    required: input.required === false ? false : true,
+    max_hit_count: maxHitCount,
+    forbidden,
+    required,
     capture_request_body: requestBody.capture_request_body,
     request_body_contains: requestBody.request_body_contains,
     request_body_patterns: requestBody.request_body_patterns,
@@ -10102,8 +10120,9 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
   const events = evidence.network_mocks || [];
   const failed = [];
   const requiredMocks = mocks.filter((mock) => mock.required !== false);
+  const hitCountForMock = (mock) => events.filter((event) => event.label === mock.label && event.ok !== false).length;
   for (const mock of requiredMocks) {
-    const hits = events.filter((event) => event.label === mock.label && event.ok !== false).length;
+    const hits = hitCountForMock(mock);
     const requiredHitCount = requiredNetworkMockHitCount(mock);
     if (hits < requiredHitCount) {
       failed.push({
@@ -10116,6 +10135,20 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       });
     }
   }
+  for (const mock of mocks) {
+    if (mock.max_hit_count === void 0) continue;
+    const hits = hitCountForMock(mock);
+    if (hits > mock.max_hit_count) {
+      failed.push({
+        label: mock.label,
+        url: mock.url,
+        method: mock.method || null,
+        reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+        max_hit_count: mock.max_hit_count,
+        hit_count: hits
+      });
+    }
+  }
   for (const event of events) {
     if (event.ok === false) {
       failed.push({
@@ -10150,15 +10183,16 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       hit_count: events.filter((event) => event.ok !== false).length,
       hits_by_label: Object.fromEntries(mocks.map((mock) => [
         mock.label,
-        events.filter((event) => event.label === mock.label && event.ok !== false).length
+        hitCountForMock(mock)
       ])),
       required_hits_by_label: Object.fromEntries(requiredMocks.map((mock) => [
         mock.label,
         requiredNetworkMockHitCount(mock)
       ])),
+      max_hits_by_label: Object.fromEntries(mocks.filter((mock) => mock.max_hit_count !== void 0).map((mock) => [mock.label, mock.max_hit_count ?? null])),
       failed
     },
-    message: failed.length ? `Network mocks failed or were not hit for ${failed.length} mock(s).` : void 0
+    message: failed.length ? `Network mocks failed or hit-count contracts failed for ${failed.length} mock(s).` : void 0
   };
 }
 function requiredNetworkMockHitCount(mock) {
@@ -10618,8 +10652,9 @@ function assessProfile(profile, evidence) {
     const events = evidence.network_mocks || [];
     const requiredMocks = profile.target.network_mocks.filter((mock) => mock && mock.required !== false);
     const failed = [];
+    const hitCountForMock = (mock) => events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
     for (const mock of requiredMocks) {
-      const hits = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      const hits = hitCountForMock(mock);
       const requiredHitCount = requiredNetworkMockHitCount(mock);
       if (hits < requiredHitCount) {
         failed.push({
@@ -10632,6 +10667,20 @@ function assessProfile(profile, evidence) {
         });
       }
     }
+    for (const mock of profile.target.network_mocks) {
+      if (!mock || mock.max_hit_count === undefined) continue;
+      const hits = hitCountForMock(mock);
+      if (hits > mock.max_hit_count) {
+        failed.push({
+          label: mock.label,
+          url: mock.url,
+          method: mock.method || null,
+          reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+          max_hit_count: mock.max_hit_count,
+          hit_count: hits,
+        });
+      }
+    }
     for (const event of events) {
       if (event && event.ok === false) {
         failed.push({
@@ -10658,9 +10707,11 @@ function assessProfile(profile, evidence) {
     }
     const hitsByLabel = {};
     const requiredHitsByLabel = {};
+    const maxHitsByLabel = {};
     for (const mock of profile.target.network_mocks) {
-      hitsByLabel[mock.label] = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      hitsByLabel[mock.label] = hitCountForMock(mock);
       if (mock && mock.required !== false) requiredHitsByLabel[mock.label] = requiredNetworkMockHitCount(mock);
+      if (mock && mock.max_hit_count !== undefined) maxHitsByLabel[mock.label] = mock.max_hit_count;
     }
     checks.push({
       type: "network_mocks_succeeded",
@@ -10672,9 +10723,10 @@ function assessProfile(profile, evidence) {
         hit_count: events.filter((event) => event && event.ok !== false).length,
         hits_by_label: hitsByLabel,
         required_hits_by_label: requiredHitsByLabel,
+        max_hits_by_label: maxHitsByLabel,
         failed,
       },
-      message: failed.length ? "Network mocks failed or were not hit for " + failed.length + " mock(s)." : undefined,
+      message: failed.length ? "Network mocks failed or hit-count contracts failed for " + failed.length + " mock(s)." : undefined,
     });
   }
   if (profile.target && Array.isArray(profile.target.setup_actions) && profile.target.setup_actions.length) {

package/dist/index.js

@@ -58,7 +58,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-DQU65Z65.js";
+} from "./chunk-376FPGFA.js";
 import {
   DEFAULT_RIDDLE_API_BASE_URL,
   DEFAULT_RIDDLE_API_KEY_FILE,

package/dist/profile.cjs

@@ -513,6 +513,22 @@ function normalizeNetworkMock(input, index) {
   if (requiredHitCount !== void 0 && (!Number.isInteger(requiredHitCount) || requiredHitCount < 1)) {
     throw new Error(`target.network_mocks[${index}].required_hit_count must be a positive integer.`);
   }
+  const forbidden = input.forbidden === true || input.must_not_hit === true || input.mustNotHit === true || input.should_not_run === true || input.shouldNotRun === true;
+  const configuredMaxHitCount = numberValue(
+    input.max_hit_count ?? input.maxHitCount ?? input.max_hits ?? input.maxHits
+  );
+  if (configuredMaxHitCount !== void 0 && (!Number.isInteger(configuredMaxHitCount) || configuredMaxHitCount < 0)) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count must be a non-negative integer.`);
+  }
+  if (forbidden && configuredMaxHitCount !== void 0 && configuredMaxHitCount !== 0) {
+    throw new Error(`target.network_mocks[${index}].forbidden cannot be combined with max_hit_count greater than 0.`);
+  }
+  const maxHitCount = forbidden ? 0 : configuredMaxHitCount;
+  const required = input.required === false || maxHitCount === 0 && input.required !== true ? false : true;
+  const effectiveRequiredHitCount = required ? requiredHitCount ?? (Array.isArray(responses) && responses.length ? responses.length : 1) : 0;
+  if (maxHitCount !== void 0 && effectiveRequiredHitCount > maxHitCount) {
+    throw new Error(`target.network_mocks[${index}].max_hit_count cannot be less than its required hit count.`);
+  }
   return {
     ...payload,
     label: normalizeName(input.label || input.name, `network-mock-${index + 1}`),
@@ -521,7 +537,9 @@ function normalizeNetworkMock(input, index) {
     responses,
     repeat_responses: input.repeat_responses === true || input.repeatResponses === true || input.cycle_responses === true || input.cycleResponses === true,
     required_hit_count: requiredHitCount,
-    required: input.required === false ? false : true,
+    max_hit_count: maxHitCount,
+    forbidden,
+    required,
     capture_request_body: requestBody.capture_request_body,
     request_body_contains: requestBody.request_body_contains,
     request_body_patterns: requestBody.request_body_patterns,
@@ -1431,8 +1449,9 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
   const events = evidence.network_mocks || [];
   const failed = [];
   const requiredMocks = mocks.filter((mock) => mock.required !== false);
+  const hitCountForMock = (mock) => events.filter((event) => event.label === mock.label && event.ok !== false).length;
   for (const mock of requiredMocks) {
-    const hits = events.filter((event) => event.label === mock.label && event.ok !== false).length;
+    const hits = hitCountForMock(mock);
     const requiredHitCount = requiredNetworkMockHitCount(mock);
     if (hits < requiredHitCount) {
       failed.push({
@@ -1445,6 +1464,20 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       });
     }
   }
+  for (const mock of mocks) {
+    if (mock.max_hit_count === void 0) continue;
+    const hits = hitCountForMock(mock);
+    if (hits > mock.max_hit_count) {
+      failed.push({
+        label: mock.label,
+        url: mock.url,
+        method: mock.method || null,
+        reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+        max_hit_count: mock.max_hit_count,
+        hit_count: hits
+      });
+    }
+  }
   for (const event of events) {
     if (event.ok === false) {
       failed.push({
@@ -1479,15 +1512,16 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
       hit_count: events.filter((event) => event.ok !== false).length,
       hits_by_label: Object.fromEntries(mocks.map((mock) => [
         mock.label,
-        events.filter((event) => event.label === mock.label && event.ok !== false).length
+        hitCountForMock(mock)
       ])),
       required_hits_by_label: Object.fromEntries(requiredMocks.map((mock) => [
         mock.label,
         requiredNetworkMockHitCount(mock)
       ])),
+      max_hits_by_label: Object.fromEntries(mocks.filter((mock) => mock.max_hit_count !== void 0).map((mock) => [mock.label, mock.max_hit_count ?? null])),
       failed
     },
-    message: failed.length ? `Network mocks failed or were not hit for ${failed.length} mock(s).` : void 0
+    message: failed.length ? `Network mocks failed or hit-count contracts failed for ${failed.length} mock(s).` : void 0
   };
 }
 function requiredNetworkMockHitCount(mock) {
@@ -1947,8 +1981,9 @@ function assessProfile(profile, evidence) {
     const events = evidence.network_mocks || [];
     const requiredMocks = profile.target.network_mocks.filter((mock) => mock && mock.required !== false);
     const failed = [];
+    const hitCountForMock = (mock) => events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
     for (const mock of requiredMocks) {
-      const hits = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      const hits = hitCountForMock(mock);
       const requiredHitCount = requiredNetworkMockHitCount(mock);
       if (hits < requiredHitCount) {
         failed.push({
@@ -1961,6 +1996,20 @@ function assessProfile(profile, evidence) {
         });
       }
     }
+    for (const mock of profile.target.network_mocks) {
+      if (!mock || mock.max_hit_count === undefined) continue;
+      const hits = hitCountForMock(mock);
+      if (hits > mock.max_hit_count) {
+        failed.push({
+          label: mock.label,
+          url: mock.url,
+          method: mock.method || null,
+          reason: mock.max_hit_count === 0 ? "forbidden_mock_hit" : "mock_hit_count_exceeded",
+          max_hit_count: mock.max_hit_count,
+          hit_count: hits,
+        });
+      }
+    }
     for (const event of events) {
       if (event && event.ok === false) {
         failed.push({
@@ -1987,9 +2036,11 @@ function assessProfile(profile, evidence) {
     }
     const hitsByLabel = {};
     const requiredHitsByLabel = {};
+    const maxHitsByLabel = {};
     for (const mock of profile.target.network_mocks) {
-      hitsByLabel[mock.label] = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      hitsByLabel[mock.label] = hitCountForMock(mock);
       if (mock && mock.required !== false) requiredHitsByLabel[mock.label] = requiredNetworkMockHitCount(mock);
+      if (mock && mock.max_hit_count !== undefined) maxHitsByLabel[mock.label] = mock.max_hit_count;
     }
     checks.push({
       type: "network_mocks_succeeded",
@@ -2001,9 +2052,10 @@ function assessProfile(profile, evidence) {
         hit_count: events.filter((event) => event && event.ok !== false).length,
         hits_by_label: hitsByLabel,
         required_hits_by_label: requiredHitsByLabel,
+        max_hits_by_label: maxHitsByLabel,
         failed,
       },
-      message: failed.length ? "Network mocks failed or were not hit for " + failed.length + " mock(s)." : undefined,
+      message: failed.length ? "Network mocks failed or hit-count contracts failed for " + failed.length + " mock(s)." : undefined,
     });
   }
   if (profile.target && Array.isArray(profile.target.setup_actions) && profile.target.setup_actions.length) {

package/dist/profile.d.cts

@@ -74,6 +74,8 @@ interface RiddleProofProfileNetworkMock extends RiddleProofProfileNetworkMockRes
     responses?: RiddleProofProfileNetworkMockResponse[];
     repeat_responses?: boolean;
     required_hit_count?: number;
+    max_hit_count?: number;
+    forbidden?: boolean;
     required?: boolean;
     capture_request_body?: boolean;
     request_body_contains?: string[];

package/dist/profile.d.ts

@@ -74,6 +74,8 @@ interface RiddleProofProfileNetworkMock extends RiddleProofProfileNetworkMockRes
     responses?: RiddleProofProfileNetworkMockResponse[];
     repeat_responses?: boolean;
     required_hit_count?: number;
+    max_hit_count?: number;
+    forbidden?: boolean;
     required?: boolean;
     capture_request_body?: boolean;
     request_body_contains?: string[];

package/dist/profile.js

@@ -19,7 +19,7 @@ import {
   resolveRiddleProofProfileTimeoutSec,
   slugifyRiddleProofProfileName,
   summarizeRiddleProofProfileResult
-} from "./chunk-DQU65Z65.js";
+} from "./chunk-376FPGFA.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.65",
+  "version": "0.7.67",
   "description": "Reusable Riddle Proof contracts and helpers for evidence-backed agent changes.",
   "license": "MIT",
   "author": "RiddleDC",