agent-inspect 6.26.0 → 6.27.0

package/packages/core/dist/checks.d.cts

@@ -272,6 +272,61 @@ interface TraceContractControlRules {
     }>;
 }
 
+/**
+ * Bounded safe recovery operation contracts (6.27).
+ *
+ * Additive `retry.operations[]` rules for read-first recovery oracles.
+ * AgentInspect evaluates traces; it does not perform retries.
+ *
+ * @experimental
+ */
+
+/** How same-argument evidence may be compared across attempts. */
+type RecoverySameArgumentsMode = "structured-or-digest";
+/**
+ * Side-effect class for conservative write recovery semantics.
+ * Read-only tools may recover without write idempotency proof.
+ * Write tools treat timeout/unknown completion as fail/unevaluable
+ * unless authoritative idempotency evidence is present.
+ */
+type RecoverySideEffectClass = "read" | "write";
+interface TraceContractRecoveryRetryableErrors {
+    /** Allowed error codes on failed attempts that precede a retry. */
+    codes?: readonly string[];
+}
+interface TraceContractRecoverySuccessfulResultDependency {
+    /** Consumer kind that must observe the successful tool result. */
+    consumerKind: "LLM";
+    /**
+     * When true, an LLM event must explicitly reference the successful tool
+     * event id (attributes / workflow metadata), not merely follow it in time.
+     */
+    requireExplicitReference?: boolean;
+}
+/**
+ * Per-tool bounded recovery oracle (additive under `retry.operations`).
+ *
+ * @experimental Additive in 6.27.
+ */
+interface TraceContractRecoveryOperation {
+    tool: string;
+    maxAttempts?: number;
+    retryableErrors?: TraceContractRecoveryRetryableErrors;
+    requireFailureBeforeRetry?: boolean;
+    /**
+     * When true or `"structured-or-digest"`, retries must share structured
+     * arguments or matching digests. Missing evidence fails closed.
+     */
+    requireSameArguments?: boolean | RecoverySameArgumentsMode;
+    requireTerminalSuccess?: boolean;
+    requireRecoveredFailureVisible?: boolean;
+    successfulResultDependency?: TraceContractRecoverySuccessfulResultDependency;
+    /**
+     * Defaults to `"read"`. Write tools apply conservative timeout/unknown rules.
+     */
+    sideEffectClass?: RecoverySideEffectClass;
+}
+
 /**
  * Retry / side-effect safety checks for TraceContract (6.23+; corrected in 6.25.1).
  *
@@ -313,6 +368,12 @@ interface TraceContractRetryRules {
      * same operation/retry chain (not merely coexistence of ok+error).
      */
     requireRecoveredFailureVisible?: boolean;
+    /**
+     * Per-tool bounded recovery oracles (read-first; write timeout/unknown fails closed).
+     *
+     * @experimental Additive in 6.27.
+     */
+    operations?: readonly TraceContractRecoveryOperation[];
 }
 
 /**
@@ -518,8 +579,9 @@ type TraceContractBody = {
     controls?: TraceContractControlRules;
     /**
      * Retry / side-effect safety using explicit attempt identity.
+     * Additive `retry.operations[]` recovery oracles land in 6.27.
      *
-     * @experimental Additive in 6.23.
+     * @experimental Additive in 6.23; operations in 6.27.
      */
     retry?: TraceContractRetryRules;
 };
@@ -590,4 +652,4 @@ declare function lintTraceContract(contract: TraceContract): TraceContractLintDi
  */
 declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };
+export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type RecoverySameArgumentsMode, type RecoverySideEffectClass, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRecoveryOperation, type TraceContractRecoveryRetryableErrors, type TraceContractRecoverySuccessfulResultDependency, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };

package/packages/core/dist/checks.d.ts

@@ -272,6 +272,61 @@ interface TraceContractControlRules {
     }>;
 }
 
+/**
+ * Bounded safe recovery operation contracts (6.27).
+ *
+ * Additive `retry.operations[]` rules for read-first recovery oracles.
+ * AgentInspect evaluates traces; it does not perform retries.
+ *
+ * @experimental
+ */
+
+/** How same-argument evidence may be compared across attempts. */
+type RecoverySameArgumentsMode = "structured-or-digest";
+/**
+ * Side-effect class for conservative write recovery semantics.
+ * Read-only tools may recover without write idempotency proof.
+ * Write tools treat timeout/unknown completion as fail/unevaluable
+ * unless authoritative idempotency evidence is present.
+ */
+type RecoverySideEffectClass = "read" | "write";
+interface TraceContractRecoveryRetryableErrors {
+    /** Allowed error codes on failed attempts that precede a retry. */
+    codes?: readonly string[];
+}
+interface TraceContractRecoverySuccessfulResultDependency {
+    /** Consumer kind that must observe the successful tool result. */
+    consumerKind: "LLM";
+    /**
+     * When true, an LLM event must explicitly reference the successful tool
+     * event id (attributes / workflow metadata), not merely follow it in time.
+     */
+    requireExplicitReference?: boolean;
+}
+/**
+ * Per-tool bounded recovery oracle (additive under `retry.operations`).
+ *
+ * @experimental Additive in 6.27.
+ */
+interface TraceContractRecoveryOperation {
+    tool: string;
+    maxAttempts?: number;
+    retryableErrors?: TraceContractRecoveryRetryableErrors;
+    requireFailureBeforeRetry?: boolean;
+    /**
+     * When true or `"structured-or-digest"`, retries must share structured
+     * arguments or matching digests. Missing evidence fails closed.
+     */
+    requireSameArguments?: boolean | RecoverySameArgumentsMode;
+    requireTerminalSuccess?: boolean;
+    requireRecoveredFailureVisible?: boolean;
+    successfulResultDependency?: TraceContractRecoverySuccessfulResultDependency;
+    /**
+     * Defaults to `"read"`. Write tools apply conservative timeout/unknown rules.
+     */
+    sideEffectClass?: RecoverySideEffectClass;
+}
+
 /**
  * Retry / side-effect safety checks for TraceContract (6.23+; corrected in 6.25.1).
  *
@@ -313,6 +368,12 @@ interface TraceContractRetryRules {
      * same operation/retry chain (not merely coexistence of ok+error).
      */
     requireRecoveredFailureVisible?: boolean;
+    /**
+     * Per-tool bounded recovery oracles (read-first; write timeout/unknown fails closed).
+     *
+     * @experimental Additive in 6.27.
+     */
+    operations?: readonly TraceContractRecoveryOperation[];
 }
 
 /**
@@ -518,8 +579,9 @@ type TraceContractBody = {
     controls?: TraceContractControlRules;
     /**
      * Retry / side-effect safety using explicit attempt identity.
+     * Additive `retry.operations[]` recovery oracles land in 6.27.
      *
-     * @experimental Additive in 6.23.
+     * @experimental Additive in 6.23; operations in 6.27.
      */
     retry?: TraceContractRetryRules;
 };
@@ -590,4 +652,4 @@ declare function lintTraceContract(contract: TraceContract): TraceContractLintDi
  */
 declare function explainTraceContract(contract: TraceContract): string[];
 
-export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };
+export { type ControlStage, type DerivedFailureConfidence, type DerivedFailureFact, type DerivedFailureRole, type FailureRoleCounts, LogicalProjectionDiagnostic, LogicalTraceEvent, type RecoverySameArgumentsMode, type RecoverySideEffectClass, type SemanticParitySummary, type ToolArgumentCheck, type ToolArgumentOccurrence, type ToolArgumentOperator, TraceCheckDiagnostic, TraceCheckInput, TraceCheckResult, type TraceContract, type TraceContractAlternativeBranch, type TraceContractAlternatives, type TraceContractBody, type TraceContractControlRules, type TraceContractInput, type TraceContractLintDiagnostic, type TraceContractLlmRules, type TraceContractObservationProvenance, type TraceContractObservationRules, type TraceContractRecoveryOperation, type TraceContractRecoveryRetryableErrors, type TraceContractRecoverySuccessfulResultDependency, type TraceContractRetryRules, type TraceContractRunRules, type TraceContractScope, type TraceContractToolRules, type TraceFacts, type TraceRelationship, type TraceRelationshipConfidence, type TraceRelationshipDiagnostic, type TraceRelationshipType, buildTraceFacts, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, resolveJsonPointer, resolveTraceContractScope, summarizeSemanticParity, workflowMetadataForRun };

package/packages/core/dist/checks.mjs

@@ -1,4 +1,4 @@
-export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveJsonPointer, resolveTraceContractScope, runTraceChecks, summarizeSemanticParity, workflowMetadataForRun } from './chunk-LHSXRIYU.mjs';
+export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractToolArgumentPayload, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveJsonPointer, resolveTraceContractScope, runTraceChecks, summarizeSemanticParity, workflowMetadataForRun } from './chunk-B6PH7A24.mjs';
 import './chunk-R4SSYU6D.mjs';
 import './chunk-U25RHRSU.mjs';
 import './chunk-VU6O5QAH.mjs';

package/packages/core/dist/{chunk-LHSXRIYU.mjs → chunk-B6PH7A24.mjs}

@@ -3750,6 +3750,368 @@ function evaluateRetrySafetyRules(events, rules, _runEvidence) {
   return findings;
 }
 
+// packages/core/src/checks/recovery-operations.ts
+function fail3(ruleId, message, evidence, expected, actual) {
+  return {
+    ruleId,
+    severity: "error",
+    status: "fail",
+    message,
+    ...expected !== void 0 ? { expected } : {},
+    ...actual !== void 0 ? { actual } : {},
+    evidence: [...evidence]
+  };
+}
+function workflowFor2(event) {
+  const attrs2 = event.attributes;
+  if (!attrs2 || typeof attrs2 !== "object") return {};
+  const direct = extractSessionWorkflowMetadata(attrs2);
+  const nested = attrs2.metadata && typeof attrs2.metadata === "object" ? extractSessionWorkflowMetadata(attrs2.metadata) : void 0;
+  return { ...nested, ...direct };
+}
+function eventEvidence3(event) {
+  return {
+    runId: event.runId,
+    eventId: event.eventId,
+    kind: event.kind,
+    name: event.name,
+    status: event.status
+  };
+}
+function eventTime2(event) {
+  return event.startedAt ?? event.timestamp ?? "";
+}
+function sortByTime2(events) {
+  return [...events].sort((a, b) => eventTime2(a).localeCompare(eventTime2(b)));
+}
+function hasIdempotencyEvidence2(event) {
+  const workflow = workflowFor2(event);
+  if (typeof workflow.idempotencyKey === "string" && workflow.idempotencyKey.trim() !== "") {
+    return true;
+  }
+  const attrs2 = event.attributes ?? {};
+  if (attrs2.noSideEffect === true) return true;
+  if (attrs2.sideEffect === false) return true;
+  return false;
+}
+function errorCodeOf(event) {
+  if (typeof event.error?.code === "string" && event.error.code.trim() !== "") {
+    return event.error.code.trim();
+  }
+  const attrs2 = event.attributes ?? {};
+  for (const key of ["errorCode", "code"]) {
+    const value = attrs2[key];
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
+  }
+  const nested = attrs2.error;
+  if (nested && typeof nested === "object") {
+    const code = nested.code;
+    if (typeof code === "string" && code.trim() !== "") return code.trim();
+  }
+  return void 0;
+}
+function argumentDigestOf(event) {
+  const attrs2 = event.attributes ?? {};
+  for (const key of ["argumentsDigest", "inputDigest", "toolArgumentsDigest"]) {
+    const value = attrs2[key];
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
+  }
+  const commitment = attrs2.omittedPayloadCommitment;
+  if (commitment && typeof commitment === "object") {
+    const digest = commitment.digest;
+    if (typeof digest === "string" && digest.trim() !== "") return digest.trim();
+  }
+  return void 0;
+}
+function argumentFingerprint(event) {
+  const payload = extractToolArgumentPayload(event);
+  if (payload.present) {
+    try {
+      return { kind: "structured", value: JSON.stringify(payload.value) };
+    } catch {
+      return { kind: "missing" };
+    }
+  }
+  const digest = argumentDigestOf(event);
+  if (digest) return { kind: "digest", value: digest };
+  return { kind: "missing" };
+}
+function sameArguments(left, right) {
+  const a = argumentFingerprint(left);
+  const b = argumentFingerprint(right);
+  if (a.kind === "missing" || b.kind === "missing") {
+    return {
+      ok: false,
+      reason: "Structured or digest argument evidence unavailable for same-arguments check.",
+      code: "AI_CHECK_RECOVERY_ARGUMENT_EVIDENCE_UNAVAILABLE"
+    };
+  }
+  if (a.kind !== b.kind) {
+    return {
+      ok: false,
+      reason: "Argument evidence kinds differ across attempts (structured vs digest).",
+      code: "AI_CHECK_RECOVERY_ARGUMENT_EVIDENCE_MISMATCH"
+    };
+  }
+  if (a.value !== b.value) {
+    return {
+      ok: false,
+      reason: "Retry arguments do not match prior attempt.",
+      code: "AI_CHECK_RECOVERY_ARGUMENTS_DIFFER"
+    };
+  }
+  return { ok: true };
+}
+function isUnevaluableWriteCompletion(event) {
+  if (event.status === "running" || event.status === "unknown") return true;
+  const attrs2 = event.attributes ?? {};
+  if (attrs2.timeout === true) return true;
+  if (attrs2.completionState === "unknown" || attrs2.completionState === "timeout") return true;
+  const code = errorCodeOf(event)?.toUpperCase();
+  if (code === "TIMEOUT" || code === "UNKNOWN_COMPLETION" || code === "DEADLINE_EXCEEDED") {
+    return true;
+  }
+  return false;
+}
+function collectExplicitReferences(event) {
+  const refs = /* @__PURE__ */ new Set();
+  const attrs2 = event.attributes ?? {};
+  const candidates = [
+    attrs2.referencedEventId,
+    attrs2.referencedEventIds,
+    attrs2.toolResultEventId,
+    attrs2.toolResultEventIds,
+    attrs2.inputEventIds,
+    attrs2.dependsOnEventIds,
+    attrs2.evidence,
+    workflowFor2(event).toolCallId
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim() !== "") {
+      refs.add(candidate.trim());
+      continue;
+    }
+    if (Array.isArray(candidate)) {
+      for (const item of candidate) {
+        if (typeof item === "string" && item.trim() !== "") refs.add(item.trim());
+        if (item && typeof item === "object") {
+          const id = item.eventId;
+          if (typeof id === "string" && id.trim() !== "") refs.add(id.trim());
+        }
+      }
+      continue;
+    }
+    if (candidate && typeof candidate === "object") {
+      const obj = candidate;
+      if (typeof obj.eventId === "string" && obj.eventId.trim() !== "") {
+        refs.add(obj.eventId.trim());
+      }
+      if (Array.isArray(obj.eventIds)) {
+        for (const id of obj.eventIds) {
+          if (typeof id === "string" && id.trim() !== "") refs.add(id.trim());
+        }
+      }
+    }
+  }
+  return refs;
+}
+function llmReferencesTool(llm, toolEvent, requireExplicit) {
+  if (!requireExplicit) {
+    return eventTime2(llm) >= eventTime2(toolEvent);
+  }
+  const refs = collectExplicitReferences(llm);
+  if (refs.has(toolEvent.eventId)) return true;
+  const toolCallId = workflowFor2(toolEvent).toolCallId;
+  if (toolCallId && refs.has(toolCallId)) return true;
+  return false;
+}
+function groupToolAttempts(events, toolName2) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.kind !== "TOOL") continue;
+    if (resolveCanonicalToolName(event) !== toolName2) continue;
+    const workflow = workflowFor2(event);
+    const key = workflow.operationId ?? `__tool__:${toolName2}`;
+    const list = groups.get(key) ?? [];
+    list.push(event);
+    groups.set(key, list);
+  }
+  return groups;
+}
+function evaluateRecoveryOperations(events, operations) {
+  const findings = [];
+  const llmEvents = events.filter((event) => event.kind === "LLM");
+  for (const operation of operations) {
+    const sideEffectClass = operation.sideEffectClass ?? "read";
+    const groups = groupToolAttempts(events, operation.tool);
+    if (groups.size === 0) {
+      if (operation.requireTerminalSuccess) {
+        findings.push(
+          fail3(
+            "contract.retry.operations.terminal-success",
+            `Recovery operation for tool ${operation.tool} requires a terminal success but no attempts were observed.`,
+            [],
+            "ok",
+            "missing"
+          )
+        );
+      }
+      continue;
+    }
+    for (const [operationKey, members] of groups) {
+      const ordered = sortByTime2(members);
+      if (operation.maxAttempts !== void 0) {
+        const count = countOperationAttempts(members);
+        if (count > operation.maxAttempts) {
+          findings.push(
+            fail3(
+              "contract.retry.operations.max-attempts",
+              `Tool ${operation.tool} operation ${operationKey} exceeded maxAttempts ${operation.maxAttempts}.`,
+              members.slice(0, 4).map(eventEvidence3),
+              operation.maxAttempts,
+              count
+            )
+          );
+        }
+      }
+      if (sideEffectClass === "write") {
+        for (const event of ordered) {
+          if (isUnevaluableWriteCompletion(event) && !hasIdempotencyEvidence2(event)) {
+            findings.push(
+              fail3(
+                "contract.retry.operations.write-completion-unevaluable",
+                `Write tool ${operation.tool} has timeout/unknown completion without authoritative idempotency evidence.`,
+                [eventEvidence3(event)],
+                "idempotencyKey|authoritative completion",
+                {
+                  code: "AI_CHECK_RECOVERY_WRITE_COMPLETION_UNAVAILABLE",
+                  status: event.status
+                }
+              )
+            );
+          }
+        }
+      }
+      const prior = [];
+      let sawEarlierError = false;
+      let sawLaterOkAfterError = false;
+      let lastOk;
+      for (const event of ordered) {
+        const classification = classifyRetryAttempt(event, prior, members);
+        const isRetry = classification.kind === "retry";
+        if (isRetry && operation.requireFailureBeforeRetry) {
+          const earlierFailure = prior.some(
+            (candidate) => candidate.status === "error" && eventTime2(candidate) !== "" && eventTime2(event) !== "" && eventTime2(candidate) < eventTime2(event)
+          );
+          if (!earlierFailure) {
+            findings.push(
+              fail3(
+                "contract.retry.operations.failure-before-retry",
+                `Retry of tool ${operation.tool} appeared without an earlier failure in the same operation.`,
+                [eventEvidence3(event)],
+                "earlier error attempt",
+                { operationKey }
+              )
+            );
+          }
+        }
+        if (isRetry && operation.retryableErrors?.codes && operation.retryableErrors.codes.length > 0) {
+          const allowed = new Set(operation.retryableErrors.codes);
+          const priorErrors = prior.filter((candidate) => candidate.status === "error");
+          const lastError = priorErrors[priorErrors.length - 1];
+          if (lastError) {
+            const code = errorCodeOf(lastError);
+            if (!code || !allowed.has(code)) {
+              findings.push(
+                fail3(
+                  "contract.retry.operations.retryable-error",
+                  `Retry of tool ${operation.tool} followed a non-retryable or missing error code.`,
+                  [eventEvidence3(event), eventEvidence3(lastError)],
+                  [...allowed],
+                  code ?? null
+                )
+              );
+            }
+          }
+        }
+        if (isRetry && (operation.requireSameArguments === true || operation.requireSameArguments === "structured-or-digest")) {
+          const baseline = prior[0] ?? prior[prior.length - 1];
+          if (baseline) {
+            const comparison = sameArguments(baseline, event);
+            if (!comparison.ok) {
+              findings.push(
+                fail3(
+                  "contract.retry.operations.same-arguments",
+                  comparison.reason,
+                  [eventEvidence3(baseline), eventEvidence3(event)],
+                  "matching structured args or digests",
+                  { code: comparison.code }
+                )
+              );
+            }
+          }
+        }
+        if (event.status === "error") {
+          sawEarlierError = true;
+        } else if (event.status === "ok" && sawEarlierError) {
+          sawLaterOkAfterError = true;
+        }
+        if (event.status === "ok") {
+          lastOk = event;
+        }
+        prior.push(event);
+      }
+      if (operation.requireTerminalSuccess) {
+        const hasOk = ordered.some((event) => event.status === "ok");
+        if (!hasOk) {
+          findings.push(
+            fail3(
+              "contract.retry.operations.terminal-success",
+              `Tool ${operation.tool} operation ${operationKey} has no terminal ok success.`,
+              ordered.slice(0, 4).map(eventEvidence3),
+              "ok",
+              ordered.map((event) => event.status)
+            )
+          );
+        }
+      }
+      if (operation.requireRecoveredFailureVisible) {
+        const hasOk = ordered.some((event) => event.status === "ok");
+        if (ordered.length > 1 && hasOk && !sawLaterOkAfterError) {
+          findings.push(
+            fail3(
+              "contract.retry.operations.recovered-failure-visible",
+              `Tool ${operation.tool} operation ${operationKey} does not show an earlier error before later success.`,
+              ordered.slice(0, 4).map(eventEvidence3),
+              "earlier error then later ok",
+              { sawEarlierError }
+            )
+          );
+        }
+      }
+      const dependency = operation.successfulResultDependency;
+      if (dependency?.consumerKind === "LLM" && lastOk) {
+        const requireExplicit = dependency.requireExplicitReference === true;
+        const referenced = llmEvents.some(
+          (llmEvent) => llmReferencesTool(llmEvent, lastOk, requireExplicit)
+        );
+        if (!referenced) {
+          findings.push(
+            fail3(
+              "contract.retry.operations.successful-result-dependency",
+              requireExplicit ? `Successful ${operation.tool} result is not explicitly referenced by a later LLM event.` : `Successful ${operation.tool} result has no later LLM consumer.`,
+              [eventEvidence3(lastOk)],
+              "LLM reference to successful tool event",
+              { code: "AI_CHECK_RECOVERY_RESULT_DEPENDENCY_MISSING" }
+            )
+          );
+        }
+      }
+    }
+  }
+  return findings;
+}
+
 // packages/core/src/checks/contract.ts
 function contractFailFinding(ruleId, message, evidence, expected, actual) {
   return {
@@ -3796,7 +4158,23 @@ function cloneBody(body) {
     ...body.retry ? {
       retry: {
         ...body.retry,
-        ...body.retry.nonIdempotentTools ? { nonIdempotentTools: [...body.retry.nonIdempotentTools] } : {}
+        ...body.retry.nonIdempotentTools ? { nonIdempotentTools: [...body.retry.nonIdempotentTools] } : {},
+        ...body.retry.operations ? {
+          operations: body.retry.operations.map((operation) => ({
+            ...operation,
+            ...operation.retryableErrors ? {
+              retryableErrors: {
+                ...operation.retryableErrors,
+                ...operation.retryableErrors.codes ? { codes: [...operation.retryableErrors.codes] } : {}
+              }
+            } : {},
+            ...operation.successfulResultDependency ? {
+              successfulResultDependency: {
+                ...operation.successfulResultDependency
+              }
+            } : {}
+          }))
+        } : {}
       }
     } : {}
   };
@@ -4231,7 +4609,11 @@ function contractToRules(contract) {
             name: context.selectedRun.name
           }
         ] : [];
-        return evaluateRetrySafetyRules(events, retry);
+        const base = evaluateRetrySafetyRules(events, retry);
+        if (!retry.operations || retry.operations.length === 0) {
+          return base;
+        }
+        return [...base, ...evaluateRecoveryOperations(events, retry.operations)];
       }
     });
   }
@@ -4716,7 +5098,10 @@ function explainTraceContract(contract) {
     lines.push("Base: declared-versus-enforced control checks enabled.");
   }
   if (contract.retry) {
-    lines.push("Base: retry/side-effect safety checks enabled.");
+    const opCount = contract.retry.operations?.length ?? 0;
+    lines.push(
+      opCount > 0 ? `Base: retry/side-effect safety checks enabled (${opCount} recovery operation oracle(s)).` : "Base: retry/side-effect safety checks enabled."
+    );
   }
   const branches = contract.alternatives?.anyOf ?? [];
   if (branches.length > 0) {
@@ -4735,5 +5120,5 @@ function explainTraceContract(contract) {
 }
 
 export { buildTraceFacts, createBaselineRegressionRule, createDecisionRule, createGuardrailRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRetrievalRule, createRunDepthRule, createRunDurationRule, createRunEventCountRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureIncompleteRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolFailureRule, createToolOrderingRule, createToolUsageRule, defineTraceContract, deriveFailureFacts, deriveRelationshipFacts, evaluateToolArgumentValue, evaluateTraceContract, evaluateTraceContractRead, explainTraceContract, extractSessionWorkflowMetadata, extractToolArgumentPayload, lintTraceContract, projectLogicalEvents, resolveCanonicalToolName, resolveJsonPointer, resolveTraceContractScope, runTraceChecks, sessionKeyForRun, summarizeSemanticParity, workflowMetadataForRun };
-//# sourceMappingURL=chunk-LHSXRIYU.mjs.map
-//# sourceMappingURL=chunk-LHSXRIYU.mjs.map
+//# sourceMappingURL=chunk-B6PH7A24.mjs.map
+//# sourceMappingURL=chunk-B6PH7A24.mjs.map