agent-inspect 6.21.0 → 6.23.0

package/packages/core/dist/checks.cjs

@@ -96,11 +96,11 @@ function parseMethod(value) {
 }
 function fromPersistedOutcome(event) {
   if (event.kind !== "OUTCOME") return void 0;
-  const attrs = event.attributes ?? {};
-  const statusRaw = attrs[OUTCOME_ATTRIBUTE_STATUS_KEY];
+  const attrs2 = event.attributes ?? {};
+  const statusRaw = attrs2[OUTCOME_ATTRIBUTE_STATUS_KEY];
   if (!isOutcomeStatus(statusRaw)) return void 0;
-  const expectation = typeof attrs[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] === "string" ? attrs[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] : event.name;
-  const observedAtRaw = attrs[OUTCOME_ATTRIBUTE_OBSERVED_AT_KEY];
+  const expectation = typeof attrs2[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] === "string" ? attrs2[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] : event.name;
+  const observedAtRaw = attrs2[OUTCOME_ATTRIBUTE_OBSERVED_AT_KEY];
   const observedAt = typeof observedAtRaw === "string" ? Date.parse(observedAtRaw) : typeof observedAtRaw === "number" && Number.isFinite(observedAtRaw) ? observedAtRaw : Date.parse(event.timestamp);
   return {
     outcomeId: event.eventId,
@@ -109,9 +109,9 @@ function fromPersistedOutcome(event) {
     name: event.name,
     expectation,
     status: statusRaw,
-    ...parseMethod(attrs[OUTCOME_ATTRIBUTE_METHOD_KEY]) !== void 0 ? { method: parseMethod(attrs[OUTCOME_ATTRIBUTE_METHOD_KEY]) } : {},
+    ...parseMethod(attrs2[OUTCOME_ATTRIBUTE_METHOD_KEY]) !== void 0 ? { method: parseMethod(attrs2[OUTCOME_ATTRIBUTE_METHOD_KEY]) } : {},
     ...event.outputSummary !== void 0 ? { actual: event.outputSummary } : {},
-    ...attrs.evidence !== void 0 ? { evidence: attrs.evidence } : {},
+    ...attrs2.evidence !== void 0 ? { evidence: attrs2.evidence } : {},
     observedAt: Number.isFinite(observedAt) ? observedAt : Date.parse(event.timestamp)
   };
 }
@@ -477,10 +477,10 @@ function projectLogicalEvents(events) {
   };
 }
 function resolveCanonicalToolName(event) {
-  const attrs = event.attributes;
-  const direct = pickString(attrs, ["toolName", "tool"]);
+  const attrs2 = event.attributes;
+  const direct = pickString(attrs2, ["toolName", "tool"]);
   if (direct) return direct;
-  const metadata = attrs?.metadata;
+  const metadata = attrs2?.metadata;
   if (isRecord(metadata)) {
     const nested = pickString(metadata, ["toolName", "tool"]);
     if (nested) return nested;
@@ -522,10 +522,10 @@ function pickNumber(record, keys) {
   return void 0;
 }
 function eventMetadata(event) {
-  const attrs = isRecord2(event.attributes) ? event.attributes : void 0;
-  const nested = attrs !== void 0 && isRecord2(attrs.metadata) ? attrs.metadata : void 0;
+  const attrs2 = isRecord2(event.attributes) ? event.attributes : void 0;
+  const nested = attrs2 !== void 0 && isRecord2(attrs2.metadata) ? attrs2.metadata : void 0;
   return {
-    ...attrs ?? {},
+    ...attrs2 ?? {},
     ...nested ?? {}
   };
 }
@@ -818,6 +818,208 @@ function deriveFailureFacts(logicalEvents) {
   };
 }
 
+// packages/core/src/sessions/metadata.ts
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finitePositiveInt(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return void 0;
+  }
+  return Math.trunc(value);
+}
+function extractSessionWorkflowMetadata(record) {
+  if (!record) return void 0;
+  const out = {};
+  let found = false;
+  const assignString = (key, value) => {
+    if (isNonEmptyString(value)) {
+      out[key] = value.trim();
+      found = true;
+    }
+  };
+  assignString("sessionId", record.sessionId);
+  assignString("conversationId", record.conversationId);
+  assignString("groupId", record.groupId);
+  assignString("parentGroupId", record.parentGroupId);
+  assignString("retryOf", record.retryOf);
+  assignString("retryReason", record.retryReason);
+  assignString("handoffFrom", record.handoffFrom);
+  assignString("handoffTo", record.handoffTo);
+  assignString("subAgentId", record.subAgentId);
+  assignString("subAgentName", record.subAgentName);
+  assignString("jobId", record.jobId);
+  assignString("queueName", record.queueName);
+  assignString("workflowName", record.workflowName);
+  assignString("workflowStep", record.workflowStep);
+  assignString("toolCallId", record.toolCallId);
+  assignString("mcpToolCallId", record.mcpToolCallId);
+  assignString("linkedStepId", record.linkedStepId);
+  assignString("operationId", record.operationId);
+  assignString("attemptId", record.attemptId);
+  assignString("fallbackOf", record.fallbackOf);
+  assignString("idempotencyKey", record.idempotencyKey);
+  assignString("correlationId", record.correlationId);
+  assignString("requestId", record.requestId);
+  assignString("decisionId", record.decisionId);
+  const attempt = finitePositiveInt(record.attempt);
+  if (attempt !== void 0) {
+    out.attempt = attempt;
+    found = true;
+  }
+  const attemptNumber = finitePositiveInt(record.attemptNumber);
+  if (attemptNumber !== void 0) {
+    out.attemptNumber = attemptNumber;
+    found = true;
+  }
+  return found ? out : void 0;
+}
+
+// packages/core/src/checks/relationship-facts.ts
+function attrs(event) {
+  return event.attributes && typeof event.attributes === "object" ? event.attributes : {};
+}
+function stringAttr(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+}
+function deriveRelationshipFacts(events) {
+  const relationships = [];
+  const diagnostics = [];
+  const byId = new Map(events.map((event) => [event.eventId, event]));
+  const seen = /* @__PURE__ */ new Set();
+  const push = (edge) => {
+    const key = `${edge.type}:${edge.fromEventId}:${edge.toEventId ?? ""}:${edge.externalRef ?? ""}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    relationships.push(edge);
+  };
+  for (const event of events) {
+    if (event.parentId) {
+      push({
+        type: "parent-child",
+        fromEventId: event.parentId,
+        toEventId: event.eventId,
+        confidence: byId.has(event.parentId) ? "explicit" : "unknown",
+        basis: ["persisted.parentId"]
+      });
+      if (!byId.has(event.parentId)) {
+        diagnostics.push({
+          code: "AI_RELATIONSHIP_PARENT_MISSING",
+          message: `parentId ${event.parentId} is not present in the event set.`,
+          eventId: event.eventId
+        });
+      }
+    }
+    const bag = attrs(event);
+    const meta = extractSessionWorkflowMetadata(bag) ?? {};
+    const nested = bag.metadata && typeof bag.metadata === "object" ? extractSessionWorkflowMetadata(bag.metadata) : void 0;
+    const workflow = { ...meta, ...nested };
+    if (workflow.retryOf) {
+      const target = events.find((candidate) => candidate.runId === workflow.retryOf);
+      push({
+        type: "retry-of",
+        fromEventId: event.eventId,
+        ...target ? { toEventId: target.eventId } : {},
+        externalRef: workflow.retryOf,
+        confidence: target ? "explicit" : "correlated",
+        basis: ["attributes.retryOf"]
+      });
+    }
+    const attemptOf = stringAttr(bag, "attemptOf") ?? stringAttr(bag, "operationId");
+    if (attemptOf && workflow.attempt !== void 0) {
+      push({
+        type: "attempt-of",
+        fromEventId: event.eventId,
+        externalRef: attemptOf,
+        confidence: "explicit",
+        basis: workflow.attempt !== void 0 ? ["attributes.attempt", "attributes.operationId"] : ["attributes.operationId"]
+      });
+    }
+    const fallbackOf = stringAttr(bag, "fallbackOf");
+    if (fallbackOf) {
+      push({
+        type: "fallback-of",
+        fromEventId: event.eventId,
+        externalRef: fallbackOf,
+        confidence: "explicit",
+        basis: ["attributes.fallbackOf"]
+      });
+    }
+    const remediationOf = stringAttr(bag, "remediationOf");
+    if (remediationOf) {
+      push({
+        type: "remediation-of",
+        fromEventId: event.eventId,
+        externalRef: remediationOf,
+        confidence: "explicit",
+        basis: ["attributes.remediationOf"]
+      });
+    }
+    const evidenceFor = stringAttr(bag, "evidenceFor");
+    if (evidenceFor) {
+      push({
+        type: "evidence-for",
+        fromEventId: event.eventId,
+        ...byId.has(evidenceFor) ? { toEventId: evidenceFor } : { externalRef: evidenceFor },
+        confidence: byId.has(evidenceFor) ? "explicit" : "correlated",
+        basis: ["attributes.evidenceFor"]
+      });
+    }
+    const acceptedBy = stringAttr(bag, "acceptedBy");
+    if (acceptedBy) {
+      push({
+        type: "accepted-by",
+        fromEventId: event.eventId,
+        ...byId.has(acceptedBy) ? { toEventId: acceptedBy } : { externalRef: acceptedBy },
+        confidence: byId.has(acceptedBy) ? "explicit" : "correlated",
+        basis: ["attributes.acceptedBy"]
+      });
+    }
+    const supersedes = stringAttr(bag, "supersedes");
+    if (supersedes) {
+      push({
+        type: "supersedes",
+        fromEventId: event.eventId,
+        ...byId.has(supersedes) ? { toEventId: supersedes } : { externalRef: supersedes },
+        confidence: byId.has(supersedes) ? "explicit" : "correlated",
+        basis: ["attributes.supersedes"]
+      });
+    }
+    const sourceLineage = stringAttr(bag, "sourceLineage") ?? stringAttr(bag, "sourceEventId");
+    if (sourceLineage) {
+      push({
+        type: "source-lineage",
+        fromEventId: event.eventId,
+        externalRef: sourceLineage,
+        confidence: "explicit",
+        basis: ["attributes.sourceLineage"]
+      });
+    }
+    const unsupported = stringAttr(bag, "relationshipType");
+    if (unsupported && unsupported !== "parent-child" && ![
+      "source-lineage",
+      "attempt-of",
+      "retry-of",
+      "fallback-of",
+      "remediation-of",
+      "evidence-for",
+      "accepted-by",
+      "supersedes"
+    ].includes(unsupported)) {
+      diagnostics.push({
+        code: "AI_RELATIONSHIP_UNSUPPORTED_TYPE",
+        message: `Unsupported relationshipType ${unsupported} was reported without flattening.`,
+        eventId: event.eventId
+      });
+    }
+  }
+  return {
+    relationships: Object.freeze(relationships),
+    diagnostics: Object.freeze(diagnostics)
+  };
+}
+
 // packages/core/src/checks/trace-facts.ts
 function summarizeSemanticParity(events) {
   const projection = projectLogicalEvents(events);
@@ -904,6 +1106,7 @@ function buildTraceFacts(input) {
     toolsByName.set(name, Object.freeze([...list]));
   }
   const derived = deriveFailureFacts(projection.logicalEvents);
+  const relationship = deriveRelationshipFacts(events);
   const summary = summarizeSemanticParity(events);
   return {
     rawEvents: Object.freeze([...events]),
@@ -917,56 +1120,10 @@ function buildTraceFacts(input) {
       failureRoleCounts: derived.failureRoleCounts
     },
     failureFacts: derived.failureFacts,
-    failuresByRole: derived.failuresByRole
-  };
-}
-
-// packages/core/src/sessions/metadata.ts
-function isNonEmptyString(value) {
-  return typeof value === "string" && value.trim() !== "";
-}
-function finitePositiveInt(value) {
-  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
-    return void 0;
-  }
-  return Math.trunc(value);
-}
-function extractSessionWorkflowMetadata(record) {
-  if (!record) return void 0;
-  const out = {};
-  let found = false;
-  const assignString = (key, value) => {
-    if (isNonEmptyString(value)) {
-      out[key] = value.trim();
-      found = true;
-    }
+    failuresByRole: derived.failuresByRole,
+    relationships: relationship.relationships,
+    relationshipDiagnostics: relationship.diagnostics
   };
-  assignString("sessionId", record.sessionId);
-  assignString("conversationId", record.conversationId);
-  assignString("groupId", record.groupId);
-  assignString("parentGroupId", record.parentGroupId);
-  assignString("retryOf", record.retryOf);
-  assignString("retryReason", record.retryReason);
-  assignString("handoffFrom", record.handoffFrom);
-  assignString("handoffTo", record.handoffTo);
-  assignString("subAgentId", record.subAgentId);
-  assignString("subAgentName", record.subAgentName);
-  assignString("jobId", record.jobId);
-  assignString("queueName", record.queueName);
-  assignString("workflowName", record.workflowName);
-  assignString("workflowStep", record.workflowStep);
-  assignString("toolCallId", record.toolCallId);
-  assignString("mcpToolCallId", record.mcpToolCallId);
-  assignString("linkedStepId", record.linkedStepId);
-  assignString("correlationId", record.correlationId);
-  assignString("requestId", record.requestId);
-  assignString("decisionId", record.decisionId);
-  const attempt = finitePositiveInt(record.attempt);
-  if (attempt !== void 0) {
-    out.attempt = attempt;
-    found = true;
-  }
-  return found ? out : void 0;
 }
 
 // packages/core/src/checks/contract-scope.ts
@@ -1008,10 +1165,10 @@ function workflowMetadataForRun(events, runId) {
   const fallback = {};
   for (const event of events) {
     if (event.runId !== runId) continue;
-    const attrs = event.attributes;
-    if (!attrs || typeof attrs !== "object") continue;
-    const direct = extractSessionWorkflowMetadata(attrs);
-    const nested = attrs.metadata && typeof attrs.metadata === "object" ? extractSessionWorkflowMetadata(attrs.metadata) : void 0;
+    const attrs2 = event.attributes;
+    if (!attrs2 || typeof attrs2 !== "object") continue;
+    const direct = extractSessionWorkflowMetadata(attrs2);
+    const nested = attrs2.metadata && typeof attrs2.metadata === "object" ? extractSessionWorkflowMetadata(attrs2.metadata) : void 0;
     const bag = {};
     mergeWorkflowMeta(bag, direct);
     mergeWorkflowMeta(bag, nested);
@@ -1163,6 +1320,465 @@ function resolveTraceContractScope(input, scope) {
   };
 }
 
+// packages/core/src/checks/control-rules.ts
+function asStringList(value) {
+  if (!Array.isArray(value)) return void 0;
+  const out = [];
+  for (const item of value) {
+    if (typeof item !== "string" || item.trim() === "") return void 0;
+    out.push(item.trim());
+  }
+  return out;
+}
+function attributeList(events, attribute) {
+  if (!attribute) return void 0;
+  for (const event of events) {
+    const attrs2 = event.attributes;
+    if (!attrs2 || typeof attrs2 !== "object") continue;
+    const direct = asStringList(attrs2[attribute]);
+    if (direct) return direct;
+    const nested = attrs2.metadata && typeof attrs2.metadata === "object" ? asStringList(attrs2.metadata[attribute]) : void 0;
+    if (nested) return nested;
+  }
+  return void 0;
+}
+function fail(ruleId, message, evidence, expected, actual) {
+  return {
+    ruleId,
+    severity: "error",
+    status: "fail",
+    message,
+    ...expected !== void 0 ? { expected } : {},
+    ...actual !== void 0 ? { actual } : {},
+    evidence: [...evidence]
+  };
+}
+function sortedUnique(values) {
+  return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+function setEqual(left, right) {
+  const a = sortedUnique(left);
+  const b = sortedUnique(right);
+  return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+function evaluateControlRules(events, rules, runEvidence2, observationNames) {
+  const findings = [];
+  const declared = rules.declaredTools ?? attributeList(events, rules.declaredToolsAttribute);
+  const enforced = rules.enforcedTools ?? attributeList(events, rules.enforcedToolsAttribute);
+  if (rules.requireDeclaredMatchesEnforced) {
+    if (declared === void 0 || enforced === void 0) {
+      findings.push(
+        fail(
+          "contract.controls.declared-matches-enforced",
+          "Declared and enforced tool sets could not both be resolved.",
+          runEvidence2,
+          { declaredDefined: declared !== void 0, enforcedDefined: enforced !== void 0 },
+          { code: "AI_CHECK_CONTROL_EVIDENCE_UNAVAILABLE" }
+        )
+      );
+    } else if (!setEqual(declared, enforced)) {
+      findings.push(
+        fail(
+          "contract.controls.declared-matches-enforced",
+          "Declared tools differ from enforced tools.",
+          runEvidence2,
+          sortedUnique(declared),
+          sortedUnique(enforced)
+        )
+      );
+    }
+  }
+  const observedTools = sortedUnique(
+    events.filter((event) => event.kind === "TOOL" && event.status !== "running").map((event) => resolveCanonicalToolName(event))
+  );
+  if (rules.requireObservedWithinEnforced) {
+    if (enforced === void 0) {
+      findings.push(
+        fail(
+          "contract.controls.observed-within-enforced",
+          "Enforced tool set unavailable for observed-within-enforced check.",
+          runEvidence2,
+          void 0,
+          { code: "AI_CHECK_CONTROL_EVIDENCE_UNAVAILABLE" }
+        )
+      );
+    } else {
+      const enforcedSet = new Set(enforced);
+      const outside = observedTools.filter((name) => !enforcedSet.has(name));
+      if (outside.length > 0) {
+        findings.push(
+          fail(
+            "contract.controls.observed-within-enforced",
+            `Observed tools outside enforced allowlist: ${outside.join(", ")}.`,
+            runEvidence2,
+            sortedUnique(enforced),
+            outside
+          )
+        );
+      }
+    }
+  }
+  if (rules.requireObservedWithinDeclared) {
+    if (declared === void 0) {
+      findings.push(
+        fail(
+          "contract.controls.observed-within-declared",
+          "Declared tool set unavailable for observed-within-declared check.",
+          runEvidence2,
+          void 0,
+          { code: "AI_CHECK_CONTROL_EVIDENCE_UNAVAILABLE" }
+        )
+      );
+    } else {
+      const declaredSet = new Set(declared);
+      const outside = observedTools.filter((name) => !declaredSet.has(name));
+      if (outside.length > 0) {
+        findings.push(
+          fail(
+            "contract.controls.observed-within-declared",
+            `Observed tools outside declared set: ${outside.join(", ")}.`,
+            runEvidence2,
+            sortedUnique(declared),
+            outside
+          )
+        );
+      }
+    }
+  }
+  for (const stage of rules.requiredStages ?? []) {
+    const observation = stage.observation ?? `control.${stage.stage}`;
+    if (!observationNames.has(observation)) {
+      findings.push(
+        fail(
+          `contract.controls.stage.${stage.stage}`,
+          `Required control stage observation missing: ${observation}.`,
+          runEvidence2,
+          observation,
+          [...observationNames]
+        )
+      );
+    }
+  }
+  return findings;
+}
+
+// packages/core/src/checks/retry-safety.ts
+function fail2(ruleId, message, evidence, expected, actual) {
+  return {
+    ruleId,
+    severity: "error",
+    status: "fail",
+    message,
+    ...expected !== void 0 ? { expected } : {},
+    ...actual !== void 0 ? { actual } : {},
+    evidence: [...evidence]
+  };
+}
+function workflowFor(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 hasIdempotencyEvidence(event) {
+  const workflow = workflowFor(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 eventEvidence(event) {
+  return {
+    runId: event.runId,
+    eventId: event.eventId,
+    kind: event.kind,
+    name: event.name,
+    status: event.status
+  };
+}
+function evaluateRetrySafetyRules(events, rules, _runEvidence) {
+  const findings = [];
+  const byOperation = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const workflow = workflowFor(event);
+    const operationId = workflow.operationId;
+    if (!operationId) continue;
+    const list = byOperation.get(operationId) ?? [];
+    list.push(event);
+    byOperation.set(operationId, list);
+  }
+  if (rules.maxAttempts !== void 0) {
+    for (const [operationId, members] of byOperation) {
+      const attemptIds = new Set(
+        members.map((event) => workflowFor(event).attemptId).filter((value) => typeof value === "string" && value.trim() !== "")
+      );
+      const attemptNumbers = members.map((event) => workflowFor(event).attemptNumber ?? workflowFor(event).attempt).filter((value) => typeof value === "number" && Number.isFinite(value));
+      const count = attemptIds.size > 0 ? attemptIds.size : attemptNumbers.length > 0 ? Math.max(...attemptNumbers) : members.filter((event) => event.kind === "TOOL" || event.kind === "LLM").length;
+      if (count > rules.maxAttempts) {
+        findings.push(
+          fail2(
+            "contract.retry.max-attempts",
+            `Operation ${operationId} exceeded maxAttempts ${rules.maxAttempts}.`,
+            members.slice(0, 4).map(eventEvidence),
+            rules.maxAttempts,
+            count
+          )
+        );
+      }
+    }
+  }
+  if (rules.requireTerminalResult) {
+    for (const [operationId, members] of byOperation) {
+      const hasTerminal = members.some((event) => event.status === "ok" || event.status === "error");
+      if (!hasTerminal) {
+        findings.push(
+          fail2(
+            "contract.retry.terminal-result",
+            `Operation ${operationId} has no terminal ok/error result.`,
+            members.slice(0, 4).map(eventEvidence),
+            "ok|error",
+            members.map((event) => event.status)
+          )
+        );
+      }
+    }
+  }
+  if (rules.fallbackOnlyAfterFailure) {
+    for (const event of events) {
+      const workflow = workflowFor(event);
+      const fallbackOf = workflow.fallbackOf;
+      if (!fallbackOf) continue;
+      const prior = byOperation.get(fallbackOf) ?? events.filter((candidate) => {
+        const meta = workflowFor(candidate);
+        return meta.operationId === fallbackOf || candidate.runId === fallbackOf;
+      });
+      const priorFailure = prior.some((candidate) => candidate.status === "error");
+      if (!priorFailure) {
+        findings.push(
+          fail2(
+            "contract.retry.fallback-after-failure",
+            `Fallback for ${fallbackOf} appeared without a prior failure.`,
+            [eventEvidence(event)],
+            "prior error attempt",
+            { fallbackOf }
+          )
+        );
+      }
+    }
+  }
+  const nonIdempotent = new Set(rules.nonIdempotentTools ?? []);
+  if (nonIdempotent.size > 0 || rules.requireIdempotencyEvidenceForRetry) {
+    const toolEvents = events.filter(
+      (event) => event.kind === "TOOL" && event.status !== "running"
+    );
+    const byToolOp = /* @__PURE__ */ new Map();
+    for (const event of toolEvents) {
+      const name = resolveCanonicalToolName(event);
+      const workflow = workflowFor(event);
+      const key = `${workflow.operationId ?? name}::${name}`;
+      const list = byToolOp.get(key) ?? [];
+      list.push(event);
+      byToolOp.set(key, list);
+    }
+    for (const [, members] of byToolOp) {
+      const ordered = [...members].sort((a, b) => {
+        const aTime = a.startedAt ?? a.timestamp ?? "";
+        const bTime = b.startedAt ?? b.timestamp ?? "";
+        return aTime.localeCompare(bTime);
+      });
+      let sawOk = false;
+      let sawSideEffectOk = false;
+      for (const event of ordered) {
+        const name = resolveCanonicalToolName(event);
+        const isRetry = sawOk;
+        if (isRetry) {
+          if (rules.requireIdempotencyEvidenceForRetry && !hasIdempotencyEvidence(event)) {
+            findings.push(
+              fail2(
+                "contract.retry.idempotency-evidence",
+                `Retry of tool ${name} lacks idempotencyKey / noSideEffect evidence.`,
+                [eventEvidence(event)],
+                "idempotencyKey|noSideEffect",
+                { code: "AI_CHECK_RETRY_EVIDENCE_UNAVAILABLE" }
+              )
+            );
+          }
+          if (nonIdempotent.has(name) && sawSideEffectOk && !hasIdempotencyEvidence(event)) {
+            findings.push(
+              fail2(
+                "contract.retry.non-idempotent-side-effect",
+                `Retry of non-idempotent tool ${name} after a confirmed ok side effect.`,
+                [eventEvidence(event)],
+                "no retry after side effect",
+                name
+              )
+            );
+          }
+        }
+        if (event.status === "ok") {
+          sawOk = true;
+          if (nonIdempotent.has(name) && !hasIdempotencyEvidence(event)) {
+            sawSideEffectOk = true;
+          }
+        }
+      }
+    }
+  }
+  if (rules.requireRecoveredFailureVisible) {
+    for (const [operationId, members] of byOperation) {
+      const hasOk = members.some((event) => event.status === "ok");
+      const hasError = members.some((event) => event.status === "error");
+      const attemptish = members.some((event) => {
+        const meta = workflowFor(event);
+        return meta.attemptId !== void 0 || meta.attemptNumber !== void 0 || meta.attempt !== void 0;
+      }) || members.length > 1;
+      if (hasOk && attemptish && !hasError) {
+        findings.push(
+          fail2(
+            "contract.retry.recovered-failure-visible",
+            `Operation ${operationId} recovered without retaining a visible failure attempt.`,
+            members.slice(0, 4).map(eventEvidence),
+            "error attempt retained",
+            { hasOk, hasError }
+          )
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+// packages/core/src/checks/tool-arguments.ts
+function decodeToken(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function resolveJsonPointer(document, pointer) {
+  if (pointer === "") {
+    return { found: true, value: document };
+  }
+  if (!pointer.startsWith("/")) {
+    return { found: false };
+  }
+  const tokens = pointer.slice(1).split("/").map(decodeToken);
+  let current = document;
+  for (const token of tokens) {
+    if (current === null || current === void 0) {
+      return { found: false };
+    }
+    if (Array.isArray(current)) {
+      if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+        return { found: false };
+      }
+      const index = Number(token);
+      if (index >= current.length) {
+        return { found: false };
+      }
+      current = current[index];
+      continue;
+    }
+    if (typeof current !== "object") {
+      return { found: false };
+    }
+    const record = current;
+    if (!Object.prototype.hasOwnProperty.call(record, token)) {
+      return { found: false };
+    }
+    current = record[token];
+  }
+  return { found: true, value: current };
+}
+function jsonType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function valuesEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function extractToolArgumentPayload(event) {
+  const attrs2 = event.attributes ?? {};
+  for (const key of ["arguments", "input", "toolArguments"]) {
+    const candidate = attrs2[key];
+    if (candidate !== void 0 && candidate !== null && typeof candidate === "object") {
+      return { present: true, value: candidate };
+    }
+  }
+  if (event.inputSummary !== void 0 && event.inputSummary !== null && typeof event.inputSummary === "object") {
+    return { present: true, value: event.inputSummary };
+  }
+  return { present: false, value: void 0 };
+}
+function evaluateToolArgumentValue(value, check, evidencePresent) {
+  if (!evidencePresent) {
+    return {
+      status: "unavailable",
+      code: "AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE",
+      message: `Structured argument evidence unavailable for tool ${check.tool} at ${check.path}.`
+    };
+  }
+  const resolved = resolveJsonPointer(value, check.path);
+  if (check.operator === "exists") {
+    return resolved.found ? { status: "pass" } : {
+      status: "fail",
+      code: "AI_CHECK_TOOL_ARGUMENT_MISSING",
+      message: `Expected path ${check.path} to exist on tool ${check.tool}.`
+    };
+  }
+  if (!resolved.found) {
+    return {
+      status: "unavailable",
+      code: "AI_CHECK_TOOL_ARGUMENT_EVIDENCE_UNAVAILABLE",
+      message: `Path ${check.path} missing for tool ${check.tool}.`
+    };
+  }
+  if (check.operator === "type") {
+    const actual = jsonType(resolved.value);
+    if (check.type === void 0) {
+      return {
+        status: "fail",
+        code: "AI_CHECK_TOOL_ARGUMENT_INVALID_CONFIG",
+        message: "type operator requires check.type"
+      };
+    }
+    return actual === check.type ? { status: "pass" } : {
+      status: "fail",
+      code: "AI_CHECK_TOOL_ARGUMENT_TYPE",
+      message: `Expected type ${check.type} at ${check.path} for tool ${check.tool}; found ${actual}.`
+    };
+  }
+  if (check.operator === "equals") {
+    return valuesEqual(resolved.value, check.expected) ? { status: "pass" } : {
+      status: "fail",
+      code: "AI_CHECK_TOOL_ARGUMENT_EQUALS",
+      message: `Value at ${check.path} for tool ${check.tool} did not equal expected (bounded comparison).`
+    };
+  }
+  if (check.operator === "oneOf") {
+    const options = check.oneOf ?? [];
+    if (options.length === 0) {
+      return {
+        status: "fail",
+        code: "AI_CHECK_TOOL_ARGUMENT_INVALID_CONFIG",
+        message: "oneOf operator requires a non-empty oneOf array"
+      };
+    }
+    return options.some((option) => valuesEqual(resolved.value, option)) ? { status: "pass" } : {
+      status: "fail",
+      code: "AI_CHECK_TOOL_ARGUMENT_ONE_OF",
+      message: `Value at ${check.path} for tool ${check.tool} was not in the allowed oneOf set.`
+    };
+  }
+  return {
+    status: "fail",
+    code: "AI_CHECK_TOOL_ARGUMENT_INVALID_CONFIG",
+    message: `Unsupported operator.`
+  };
+}
+
 // packages/core/src/checks/contract.ts
 function contractFailFinding(ruleId, message, evidence, expected, actual) {
   return {
@@ -1184,18 +1800,38 @@ function normalizeStatus(status) {
 function cloneBody(body) {
   return {
     ...body.run ? { run: { ...body.run } } : {},
-    ...body.tools ? { tools: { ...body.tools } } : {},
+    ...body.tools ? {
+      tools: {
+        ...body.tools,
+        ...body.tools.arguments ? { arguments: body.tools.arguments.map((item) => ({ ...item })) } : {},
+        ...body.tools.orderRules ? { orderRules: body.tools.orderRules.map((item) => ({ ...item })) } : {}
+      }
+    } : {},
     ...body.llm ? { llm: { ...body.llm } } : {},
     ...body.observations ? {
       observations: {
         ...body.observations,
         ...body.observations.requireProvenance ? { requireProvenance: { ...body.observations.requireProvenance } } : {}
       }
+    } : {},
+    ...body.controls ? {
+      controls: {
+        ...body.controls,
+        ...body.controls.declaredTools ? { declaredTools: [...body.controls.declaredTools] } : {},
+        ...body.controls.enforcedTools ? { enforcedTools: [...body.controls.enforcedTools] } : {},
+        ...body.controls.requiredStages ? { requiredStages: body.controls.requiredStages.map((item) => ({ ...item })) } : {}
+      }
+    } : {},
+    ...body.retry ? {
+      retry: {
+        ...body.retry,
+        ...body.retry.nonIdempotentTools ? { nonIdempotentTools: [...body.retry.nonIdempotentTools] } : {}
+      }
     } : {}
   };
 }
 function bodyHasRules(body) {
-  return body.run !== void 0 || body.tools !== void 0 || body.llm !== void 0 || body.observations !== void 0;
+  return body.run !== void 0 || body.tools !== void 0 || body.llm !== void 0 || body.observations !== void 0 || body.controls !== void 0 || body.retry !== void 0;
 }
 var MAX_EVIDENCE_EVENT_IDS = 16;
 var METHOD_VOCABULARY = new Set(OBSERVED_OUTCOME_METHODS);
@@ -1396,11 +2032,14 @@ function contractToRules(contract) {
   if (contract.tools) {
     const order = contract.tools.requiredOrder ?? [];
     const requiredOrderMode = contract.tools.requiredOrderMode ?? "first-occurrence";
+    const orderRules = contract.tools.orderRules ?? [];
+    const endpointRequired = orderRules.filter((rule) => rule.requireEndpoints !== false).flatMap((rule) => [rule.before, rule.after]);
     const required = [
       .../* @__PURE__ */ new Set([
         ...contract.tools.required ?? [],
         ...contract.tools.requiredTools ?? [],
-        ...order
+        ...order,
+        ...endpointRequired
       ])
     ];
     const forbidden = [
@@ -1425,6 +2064,106 @@ function contractToRules(contract) {
         })
       );
     }
+    const defaultOccurrenceMode = contract.tools.defaultOccurrenceMode ?? requiredOrderMode;
+    for (const [index, rule] of orderRules.entries()) {
+      rules.push(
+        createToolOrderingRule({
+          before: rule.before,
+          after: rule.after,
+          id: `contract.tool.orderRule.${index}`,
+          mode: rule.occurrenceMode ?? defaultOccurrenceMode
+        })
+      );
+    }
+    const argumentChecks = contract.tools.arguments ?? [];
+    if (argumentChecks.length > 0) {
+      rules.push({
+        id: "contract.tool.arguments",
+        category: "tool",
+        defaultSeverity: "error",
+        evaluate(context) {
+          const tools = (context.logicalEvents ?? context.events).filter(
+            (event) => event.kind === "TOOL" && event.status !== "running"
+          );
+          const findings = [];
+          for (const [index, check] of argumentChecks.entries()) {
+            const matches = tools.filter(
+              (event) => resolveCanonicalToolName(event) === check.tool
+            );
+            if (matches.length === 0) {
+              findings.push(
+                contractFailFinding(
+                  `contract.tool.arguments.${index}`,
+                  `No finished tool named ${check.tool} for argument check.`,
+                  context.selectedRun ? [
+                    {
+                      runId: context.selectedRun.runId,
+                      kind: "RUN",
+                      name: context.selectedRun.name
+                    }
+                  ] : [],
+                  { tool: check.tool, path: check.path },
+                  { toolCount: 0 }
+                )
+              );
+              continue;
+            }
+            const occurrence = check.occurrence ?? "all";
+            const selected = occurrence === "first" ? [matches[0]] : occurrence === "last" ? [matches[matches.length - 1]] : matches;
+            const results = selected.map((event) => {
+              const payload = extractToolArgumentPayload(event);
+              return evaluateToolArgumentValue(
+                payload.value,
+                check,
+                payload.present
+              );
+            });
+            if (occurrence === "any") {
+              if (results.some((result) => result.status === "pass")) continue;
+              const firstFail = results.find((result) => result.status !== "pass");
+              findings.push(
+                contractFailFinding(
+                  `contract.tool.arguments.${index}`,
+                  firstFail.message,
+                  selected.slice(0, 1).map((event) => ({
+                    runId: event.runId,
+                    eventId: event.eventId,
+                    kind: event.kind,
+                    name: event.name,
+                    path: `tool.${check.tool}${check.path}`
+                  })),
+                  { tool: check.tool, path: check.path, operator: check.operator },
+                  { code: firstFail.code }
+                )
+              );
+              continue;
+            }
+            for (const [selIndex, result] of results.entries()) {
+              if (result.status === "pass") continue;
+              const event = selected[selIndex];
+              findings.push(
+                contractFailFinding(
+                  `contract.tool.arguments.${index}`,
+                  result.message,
+                  [
+                    {
+                      runId: event.runId,
+                      eventId: event.eventId,
+                      kind: event.kind,
+                      name: event.name,
+                      path: `tool.${check.tool}${check.path}`
+                    }
+                  ],
+                  { tool: check.tool, path: check.path, operator: check.operator },
+                  { code: result.code }
+                )
+              );
+            }
+          }
+          return findings;
+        }
+      });
+    }
   }
   if (contract.llm) {
     rules.push(
@@ -1485,6 +2224,46 @@ function contractToRules(contract) {
       });
     }
   }
+  if (contract.controls) {
+    const controls = contract.controls;
+    rules.push({
+      id: "contract.controls",
+      category: "run",
+      defaultSeverity: "error",
+      evaluate(context) {
+        const events = context.logicalEvents ?? context.events;
+        const outcomes = extractOutcomesFromPersistedEvents(context.events);
+        const observationNames = new Set(outcomes.map((item) => item.name));
+        const runEvidence2 = context.selectedRun ? [
+          {
+            runId: context.selectedRun.runId,
+            kind: "RUN",
+            name: context.selectedRun.name
+          }
+        ] : [];
+        return evaluateControlRules(events, controls, runEvidence2, observationNames);
+      }
+    });
+  }
+  if (contract.retry) {
+    const retry = contract.retry;
+    rules.push({
+      id: "contract.retry",
+      category: "run",
+      defaultSeverity: "error",
+      evaluate(context) {
+        const events = context.logicalEvents ?? context.events;
+        context.selectedRun ? [
+          {
+            runId: context.selectedRun.runId,
+            kind: "RUN",
+            name: context.selectedRun.name
+          }
+        ] : [];
+        return evaluateRetrySafetyRules(events, retry);
+      }
+    });
+  }
   return rules;
 }
 function validateScopeShape(scope) {
@@ -1571,7 +2350,7 @@ function validateAlternativesShape(alternatives) {
       diagnostics.push({
         code: "contract.alternatives.empty-branch",
         severity: "error",
-        message: `Branch ${branch.id} must declare at least one run/tools/llm/observations rule.`,
+        message: `Branch ${branch.id} must declare at least one run/tools/llm/observations/controls/retry rule.`,
         path: `${path3}.contract`
       });
     }
@@ -1844,6 +2623,40 @@ function lintTraceContract(contract) {
       path: "tools.requiredOrderMode"
     });
   }
+  const orderRules = contract.tools?.orderRules ?? [];
+  const seenPairs = /* @__PURE__ */ new Set();
+  for (const [index, rule] of orderRules.entries()) {
+    const key = `${rule.before}\0${rule.after}`;
+    if (seenPairs.has(key)) {
+      diagnostics.push({
+        code: "contract.tools.orderRules.duplicate",
+        severity: "warning",
+        message: `Duplicate orderRules pair ${rule.before} \u2192 ${rule.after}.`,
+        path: `tools.orderRules[${index}]`
+      });
+    }
+    seenPairs.add(key);
+    if (rule.before === rule.after) {
+      diagnostics.push({
+        code: "contract.tools.orderRules.self",
+        severity: "error",
+        message: "orderRules before and after must differ.",
+        path: `tools.orderRules[${index}]`
+      });
+    }
+  }
+  if ((contract.tools?.arguments?.length ?? 0) > 0) {
+    for (const [index, check] of (contract.tools?.arguments ?? []).entries()) {
+      if (!check.path.startsWith("/") && check.path !== "") {
+        diagnostics.push({
+          code: "contract.tools.arguments.path",
+          severity: "error",
+          message: 'tools.arguments path must be a JSON Pointer ("" or start with "/").',
+          path: `tools.arguments[${index}].path`
+        });
+      }
+    }
+  }
   return diagnostics;
 }
 function explainTraceContract(contract) {
@@ -1887,6 +2700,17 @@ function explainTraceContract(contract) {
         `Base: requiredOrder [${contract.tools.requiredOrder.join(" \u2192 ")}] mode=${mode}.`
       );
     }
+    if ((contract.tools.orderRules?.length ?? 0) > 0) {
+      const defaultMode = contract.tools.defaultOccurrenceMode ?? "first-occurrence";
+      lines.push(
+        `Base: ${contract.tools.orderRules.length} orderRules (defaultOccurrenceMode=${defaultMode}).`
+      );
+    }
+    if ((contract.tools.arguments?.length ?? 0) > 0) {
+      lines.push(
+        `Base: ${contract.tools.arguments.length} structured tool-argument check(s).`
+      );
+    }
   }
   if (contract.llm) {
     if (contract.llm.maxCalls !== void 0) {
@@ -1917,6 +2741,12 @@ function explainTraceContract(contract) {
       );
     }
   }
+  if (contract.controls) {
+    lines.push("Base: declared-versus-enforced control checks enabled.");
+  }
+  if (contract.retry) {
+    lines.push("Base: retry/side-effect safety checks enabled.");
+  }
   const branches = contract.alternatives?.anyOf ?? [];
   if (branches.length > 0) {
     lines.push(
@@ -2227,7 +3057,7 @@ function classifyRuleExecution(findings, threw) {
   }
   return "pass";
 }
-function stringAttr(event, keys) {
+function stringAttr2(event, keys) {
   for (const key of keys) {
     const value = event.attributes?.[key];
     if (typeof value === "string" && value.trim() !== "") return value;
@@ -2266,7 +3096,7 @@ function stripPrefix(name, prefixes) {
   }
   return name;
 }
-function eventEvidence(event, path3) {
+function eventEvidence2(event, path3) {
   return {
     runId: event.runId,
     eventId: event.eventId,
@@ -2305,15 +3135,15 @@ function semanticEvents(context) {
 }
 function llmModel(event) {
   const keys = ["model", "modelId", "responseModelId", "modelName", "model_name"];
-  return stringAttr(event, keys) ?? metadataStringAttr(event, keys) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
+  return stringAttr2(event, keys) ?? metadataStringAttr(event, keys) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
 }
 function llmProvider(event) {
   const keys = ["provider", "providerName", "provider_name"];
-  return stringAttr(event, keys) ?? metadataStringAttr(event, keys);
+  return stringAttr2(event, keys) ?? metadataStringAttr(event, keys);
 }
 function llmFinishReason(event) {
   const keys = ["finishReason", "rawFinishReason", "finish_reason"];
-  return stringAttr(event, keys) ?? metadataStringAttr(event, keys);
+  return stringAttr2(event, keys) ?? metadataStringAttr(event, keys);
 }
 function retryCount(event) {
   return numericAttr(event, ["retryCount", "retryAttempt", "retry_attempt", "attempt"]);
@@ -2455,7 +3285,7 @@ function parentMarkedUnresolved(event) {
   ]) === true) {
     return true;
   }
-  const resolution = stringAttr(event, [
+  const resolution = stringAttr2(event, [
     "parentResolution",
     "relationshipResolution",
     "relationshipStatus"
@@ -2463,13 +3293,13 @@ function parentMarkedUnresolved(event) {
   return resolution === "unresolved" || resolution === "missing-parent";
 }
 function signalName(event, attributeKeys, prefixes) {
-  return stringAttr(event, attributeKeys) ?? stripPrefix(event.name, prefixes);
+  return stringAttr2(event, attributeKeys) ?? stripPrefix(event.name, prefixes);
 }
 function guardrailEvents(context) {
   return finishedEvents(context).filter((event) => {
     const name = event.name.toLowerCase();
     if (name.startsWith("guardrail:") || name.includes(".guardrail.")) return true;
-    return stringAttr(event, ["guardrailName", "guardrail", "guardrailId"]) !== void 0;
+    return stringAttr2(event, ["guardrailName", "guardrail", "guardrailId"]) !== void 0;
   });
 }
 function retryValue(event) {
@@ -2536,7 +3366,7 @@ function guardrailShape(context) {
 }
 function firstEvidenceForKind(context, kind, path3) {
   const event = semanticEvents(context).find((candidate) => candidate.kind === kind);
-  return event ? [eventEvidence(event, path3)] : runEvidence(context.selectedRun);
+  return event ? [eventEvidence2(event, path3)] : runEvidence(context.selectedRun);
 }
 function baselineDiffFinding(message, evidence, expected, actual) {
   return failFinding("baseline.regression", message, evidence, expected, actual);
@@ -2569,7 +3399,7 @@ function createRunStatusRule(options = {}) {
             failFinding(
               "run.status",
               "Run contains incomplete running events.",
-              running.map((event) => eventEvidence(event)),
+              running.map((event) => eventEvidence2(event)),
               "no running events",
               running.length
             )
@@ -2615,7 +3445,7 @@ function createMaxStepDurationRule(options) {
         failFinding(
           "run.maxStepDuration",
           `${over.length} step(s) exceeded max duration ${options.maxDurationMs}ms.`,
-          over.map((event) => eventEvidence(event, "durationMs")),
+          over.map((event) => eventEvidence2(event, "durationMs")),
           { maxDurationMs: options.maxDurationMs },
           over.map((event) => ({
             eventId: event.eventId,
@@ -2641,7 +3471,7 @@ function createStallDetectionRule(options = {}) {
           failFinding(
             "run.stall",
             `Found ${running.length} event(s) still running (possible stall).`,
-            running.map((event) => eventEvidence(event, "status")),
+            running.map((event) => eventEvidence2(event, "status")),
             "no running events",
             running.length
           )
@@ -2656,7 +3486,7 @@ function createStallDetectionRule(options = {}) {
             failFinding(
               "run.stall",
               `Found ${incomplete.length} started event(s) without endedAt.`,
-              incomplete.map((event) => eventEvidence(event, "endedAt")),
+              incomplete.map((event) => eventEvidence2(event, "endedAt")),
               "endedAt for started events",
               incomplete.length
             )
@@ -2692,7 +3522,7 @@ function createRequireCompletedRule() {
           failFinding(
             "run.requireCompleted",
             `Run has ${running.length} incomplete running event(s).`,
-            running.map((event) => eventEvidence(event, "status")),
+            running.map((event) => eventEvidence2(event, "status")),
             "no running events",
             running.length
           )
@@ -2790,12 +3620,12 @@ function createToolUsageRule(options) {
         const name = toolName(event);
         if (forbidden.has(name)) {
           findings.push(
-            failFinding("tool.usage", `Forbidden tool ${name} appeared.`, [eventEvidence(event)], "tool absent", name)
+            failFinding("tool.usage", `Forbidden tool ${name} appeared.`, [eventEvidence2(event)], "tool absent", name)
           );
         }
         if (allowed && !allowed.has(name)) {
           findings.push(
-            failFinding("tool.usage", `Tool ${name} is not in the allowed tool set.`, [eventEvidence(event)], [...allowed].sort(), name)
+            failFinding("tool.usage", `Tool ${name} is not in the allowed tool set.`, [eventEvidence2(event)], [...allowed].sort(), name)
           );
         }
       }
@@ -2806,7 +3636,7 @@ function createToolUsageRule(options) {
       }
       if (options.maxCount !== void 0 && tools.length > options.maxCount) {
         findings.push(
-          failFinding("tool.usage", `Tool count ${tools.length} exceeded maximum ${options.maxCount}.`, tools.map((event) => eventEvidence(event)), { maxCount: options.maxCount }, tools.length)
+          failFinding("tool.usage", `Tool count ${tools.length} exceeded maximum ${options.maxCount}.`, tools.map((event) => eventEvidence2(event)), { maxCount: options.maxCount }, tools.length)
         );
       }
       return findings;
@@ -2833,7 +3663,7 @@ function createToolOrderingRule(options) {
           failFinding(
             ruleId,
             `Tool ${options.before} must appear before ${options.after}.`,
-            [eventEvidence(tools[beforeIndex]), eventEvidence(tools[afterIndex])],
+            [eventEvidence2(tools[beforeIndex]), eventEvidence2(tools[afterIndex])],
             { before: options.before, after: options.after },
             tools.map(toolName)
           )
@@ -2855,7 +3685,7 @@ function createToolOrderingRule(options) {
             failFinding(
               ruleId,
               `Tool ${options.before} cannot causally happen before itself.`,
-              [eventEvidence(beforeEvent)],
+              [eventEvidence2(beforeEvent)],
               expected,
               { code: "tool.order.same-tool" }
             )
@@ -2866,7 +3696,7 @@ function createToolOrderingRule(options) {
             failFinding(
               ruleId,
               `Tool order ${options.before} before ${options.after} could not establish causal timing.`,
-              [eventEvidence(beforeEvent), eventEvidence(afterEvent)],
+              [eventEvidence2(beforeEvent), eventEvidence2(afterEvent)],
               expected,
               {
                 code: "tool.order.interval-unresolved",
@@ -2881,7 +3711,7 @@ function createToolOrderingRule(options) {
             failFinding(
               ruleId,
               `Tool ${options.before} must finish before ${options.after} starts.`,
-              [eventEvidence(beforeEvent), eventEvidence(afterEvent)],
+              [eventEvidence2(beforeEvent), eventEvidence2(afterEvent)],
               expected,
               {
                 beforeEndedAt: new Date(beforeEnd).toISOString(),
@@ -2906,7 +3736,7 @@ function createToolOrderingRule(options) {
             failFinding(
               ruleId,
               `Tool ${options.before} cannot causally happen before itself.`,
-              [eventEvidence(beforeEvent)],
+              [eventEvidence2(beforeEvent)],
               expected,
               { code: "tool.order.same-tool" }
             )
@@ -2941,7 +3771,7 @@ function createToolOrderingRule(options) {
             failFinding(
               ruleId,
               `Tool order ${options.before} before ${options.after} could not establish all causal intervals.`,
-              [firstMissingBefore, firstMissingAfter].filter((event) => event !== void 0).map((event) => eventEvidence(event)),
+              [firstMissingBefore, firstMissingAfter].filter((event) => event !== void 0).map((event) => eventEvidence2(event)),
               expected,
               {
                 code: "tool.order.interval-unresolved",
@@ -2956,7 +3786,7 @@ function createToolOrderingRule(options) {
             failFinding(
               ruleId,
               `Every ${options.before} tool call must finish before any ${options.after} tool call starts.`,
-              [eventEvidence(latestBefore.event), eventEvidence(earliestAfter.event)],
+              [eventEvidence2(latestBefore.event), eventEvidence2(earliestAfter.event)],
               expected,
               {
                 latestBeforeEndedAt: new Date(latestBefore.end).toISOString(),
@@ -2980,7 +3810,7 @@ function createToolOrderingRule(options) {
               beforeEndedAt: beforeEvent.endedAt,
               afterStartedAt: afterEvent.startedAt ?? afterEvent.timestamp
             },
-            evidence: [eventEvidence(beforeEvent), eventEvidence(afterEvent)]
+            evidence: [eventEvidence2(beforeEvent), eventEvidence2(afterEvent)]
           }
         ];
       }
@@ -3003,7 +3833,7 @@ function createToolFailureRule(options) {
           failFinding(
             "tool.failures",
             `Tool failure count ${failures.length} exceeded ${options.maxFailures}.`,
-            failures.map((event) => eventEvidence(event)),
+            failures.map((event) => eventEvidence2(event)),
             { maxFailures: options.maxFailures },
             failures.length
           )
@@ -3016,7 +3846,7 @@ function createToolFailureRule(options) {
             failFinding(
               "tool.failures",
               `Tool retry count exceeded ${options.maxRetries}.`,
-              excessiveRetries.map((item) => eventEvidence(item.event, "attributes.retryCount")),
+              excessiveRetries.map((item) => eventEvidence2(item.event, "attributes.retryCount")),
               { maxRetries: options.maxRetries },
               excessiveRetries.map((item) => ({ tool: toolName(item.event), retries: item.count }))
             )
@@ -3043,7 +3873,7 @@ function createLlmUsageRule(options) {
           failFinding(
             "llm.usage",
             `LLM call count ${llms.length} exceeded ${options.maxCalls}.`,
-            llms.map((event) => eventEvidence(event)),
+            llms.map((event) => eventEvidence2(event)),
             { maxCalls: options.maxCalls },
             llms.length
           )
@@ -3055,17 +3885,17 @@ function createLlmUsageRule(options) {
         const finishReason = llmFinishReason(event);
         if (allowedModels && (!model || !allowedModels.has(model))) {
           findings.push(
-            failFinding("llm.usage", `LLM model ${model ?? "unknown"} is not allowed.`, [eventEvidence(event, "attributes.model")], [...allowedModels].sort(), model ?? "unknown")
+            failFinding("llm.usage", `LLM model ${model ?? "unknown"} is not allowed.`, [eventEvidence2(event, "attributes.model")], [...allowedModels].sort(), model ?? "unknown")
           );
         }
         if (allowedProviders && (!provider || !allowedProviders.has(provider))) {
           findings.push(
-            failFinding("llm.usage", `LLM provider ${provider ?? "unknown"} is not allowed.`, [eventEvidence(event, "attributes.provider")], [...allowedProviders].sort(), provider ?? "unknown")
+            failFinding("llm.usage", `LLM provider ${provider ?? "unknown"} is not allowed.`, [eventEvidence2(event, "attributes.provider")], [...allowedProviders].sort(), provider ?? "unknown")
           );
         }
         if (finishReasons && (!finishReason || !finishReasons.has(finishReason))) {
           findings.push(
-            failFinding("llm.usage", `LLM finish reason ${finishReason ?? "unknown"} is not allowed.`, [eventEvidence(event, "attributes.finishReason")], [...finishReasons].sort(), finishReason ?? "unknown")
+            failFinding("llm.usage", `LLM finish reason ${finishReason ?? "unknown"} is not allowed.`, [eventEvidence2(event, "attributes.finishReason")], [...finishReasons].sort(), finishReason ?? "unknown")
           );
         }
       }
@@ -3090,7 +3920,7 @@ function createLlmUsageRule(options) {
             failFinding(
               "llm.usage",
               `LLM ${key} token count ${tokenTotals[key]} exceeded ${limit}.`,
-              llms.map((event) => eventEvidence(event, `tokenUsage.${key}`)),
+              llms.map((event) => eventEvidence2(event, `tokenUsage.${key}`)),
               { [`max${key[0].toUpperCase()}${key.slice(1)}Tokens`]: limit },
               tokenTotals[key]
             )
@@ -3115,7 +3945,7 @@ function createStructureIncompleteRule(options = {}) {
             failFinding(
               "structure.incomplete",
               "Trace contains incomplete running events.",
-              running.map((event) => eventEvidence(event, "status")),
+              running.map((event) => eventEvidence2(event, "status")),
               "no running events",
               running.length
             )
@@ -3131,7 +3961,7 @@ function createStructureIncompleteRule(options = {}) {
             failFinding(
               "structure.incomplete",
               "Trace contains events with startedAt but no endedAt.",
-              missingEndedAt.map((event) => eventEvidence(event, "endedAt")),
+              missingEndedAt.map((event) => eventEvidence2(event, "endedAt")),
               "endedAt for started events",
               missingEndedAt.length
             )
@@ -3159,7 +3989,7 @@ function createStructureOrphanRule(options = {}) {
         failFinding(
           "structure.orphan",
           "Trace contains events whose parentId is not present in the selected run.",
-          orphans.map((event) => eventEvidence(event, "parentId")),
+          orphans.map((event) => eventEvidence2(event, "parentId")),
           "parentId resolves to an event in the selected run",
           orphans.length
         )
@@ -3191,7 +4021,7 @@ function createStructureCycleRule() {
                 failFinding(
                   "structure.cycle",
                   formatProgrammaticDiagnostic("AI_TRACE_RELATIONSHIP_CYCLE"),
-                  cycle.map((item) => eventEvidence(item, "parentId")),
+                  cycle.map((item) => eventEvidence2(item, "parentId")),
                   "acyclic parentId graph",
                   cycle.map((item) => item.eventId).sort()
                 )
@@ -3223,7 +4053,7 @@ function createStructureRelationshipRule(options = {}) {
             failFinding(
               "structure.relationship",
               `Event confidence ${event.confidence} is below ${minConfidence}.`,
-              [eventEvidence(event, "confidence")],
+              [eventEvidence2(event, "confidence")],
               { minConfidence },
               event.confidence
             )
@@ -3235,7 +4065,7 @@ function createStructureRelationshipRule(options = {}) {
             failFinding(
               "structure.relationship",
               "Event parentId points to itself.",
-              [eventEvidence(event, "parentId")],
+              [eventEvidence2(event, "parentId")],
               "parentId references a distinct event",
               "self"
             )
@@ -3252,7 +4082,7 @@ function createStructureRelationshipRule(options = {}) {
               failFinding(
                 "structure.relationship",
                 "Parent event starts after child event.",
-                [eventEvidence(parent), eventEvidence(event, "parentId")],
+                [eventEvidence2(parent), eventEvidence2(event, "parentId")],
                 "parent start <= child start",
                 { parentEventId: parent.eventId, childEventId: event.eventId }
               )
@@ -3266,7 +4096,7 @@ function createStructureRelationshipRule(options = {}) {
               failFinding(
                 "structure.relationship",
                 "Trace parentSpanId does not match parent spanId.",
-                [eventEvidence(event, "trace.parentSpanId")],
+                [eventEvidence2(event, "trace.parentSpanId")],
                 { parentSpanId: parent.trace.spanId },
                 actual ?? "missing"
               )
@@ -3295,7 +4125,7 @@ function createStructureParallelWidthRule(options) {
               "structure.parallelWidth",
               `Parent ${parentId} has ${children.length} children, exceeding ${options.maxChildren}.`,
               [
-                ...parent ? [eventEvidence(parent)] : [{ runId: context.selectedRun?.runId, eventId: parentId }],
+                ...parent ? [eventEvidence2(parent)] : [{ runId: context.selectedRun?.runId, eventId: parentId }],
                 ...children.map((child) => ({
                   runId: child.event.runId,
                   eventId: child.event.eventId,
@@ -3343,7 +4173,7 @@ function createStructureParallelWidthRule(options) {
             failFinding(
               "structure.parallelWidth",
               `Concurrent event width ${maxActive.length} exceeded ${options.maxConcurrent}.`,
-              maxActive.map((event) => eventEvidence(event)),
+              maxActive.map((event) => eventEvidence2(event)),
               { maxConcurrent: options.maxConcurrent },
               maxActive.length
             )
@@ -3386,7 +4216,7 @@ function createSignalRule(ruleId, label, options, selectEvents, nameForEvent) {
             failFinding(
               ruleId,
               `Forbidden ${label} ${name} appeared.`,
-              [eventEvidence(event)],
+              [eventEvidence2(event)],
               `${label} absent`,
               name
             )
@@ -3397,7 +4227,7 @@ function createSignalRule(ruleId, label, options, selectEvents, nameForEvent) {
             failFinding(
               ruleId,
               `${label[0].toUpperCase()}${label.slice(1)} ${name} is not in the allowed set.`,
-              [eventEvidence(event)],
+              [eventEvidence2(event)],
               [...allowed].sort(),
               name
             )
@@ -3420,7 +4250,7 @@ function createSignalRule(ruleId, label, options, selectEvents, nameForEvent) {
           failFinding(
             ruleId,
             `${label[0].toUpperCase()}${label.slice(1)} count ${events.length} exceeded maximum ${options.maxCount}.`,
-            events.map((event) => eventEvidence(event)),
+            events.map((event) => eventEvidence2(event)),
             { maxCount: options.maxCount },
             events.length
           )
@@ -3474,7 +4304,7 @@ function createSafetyRedactionRule(options = {}) {
             failFinding(
               "safety.redaction",
               `Sensitive-looking field at ${entry.path} is not redacted.`,
-              [eventEvidence(event, entry.path)],
+              [eventEvidence2(event, entry.path)],
               "redaction marker",
               { path: entry.path, valueType: valueType(entry.value) },
               {
@@ -3508,7 +4338,7 @@ function createSafetyRawContentRule(options = {}) {
             failFinding(
               "safety.rawPrompt",
               `Raw content-like field ${entry.path} is present.`,
-              [eventEvidence(event, entry.path)],
+              [eventEvidence2(event, entry.path)],
               "metadata-only trace fields",
               { path: entry.path, valueType: valueType(entry.value) },
               {
@@ -3546,7 +4376,7 @@ function createSafetySecretPatternRule(options = {}) {
               failFinding(
                 "safety.secretPattern",
                 `Secret-like pattern ${pattern.id} matched at ${entry.path}.`,
-                [eventEvidence(event, entry.path)],
+                [eventEvidence2(event, entry.path)],
                 "no secret-like strings",
                 { pattern: pattern.id, path: entry.path },
                 {
@@ -3579,7 +4409,7 @@ function createSafetyOversizedAttributeRule(options) {
               failFinding(
                 "safety.oversizedAttribute",
                 `String at ${entry.path} exceeds ${options.maxStringLength} characters.`,
-                [eventEvidence(event, entry.path)],
+                [eventEvidence2(event, entry.path)],
                 { maxStringLength: options.maxStringLength },
                 { path: entry.path, length: entry.value.length },
                 {
@@ -3596,7 +4426,7 @@ function createSafetyOversizedAttributeRule(options) {
               failFinding(
                 "safety.oversizedAttribute",
                 `Array at ${entry.path} exceeds ${options.maxArrayLength} items.`,
-                [eventEvidence(event, entry.path)],
+                [eventEvidence2(event, entry.path)],
                 { maxArrayLength: options.maxArrayLength },
                 { path: entry.path, length: entry.value.length },
                 {
@@ -3613,7 +4443,7 @@ function createSafetyOversizedAttributeRule(options) {
               failFinding(
                 "safety.oversizedAttribute",
                 `Object at ${entry.path} exceeds ${options.maxObjectKeys} keys.`,
-                [eventEvidence(event, entry.path)],
+                [eventEvidence2(event, entry.path)],
                 { maxObjectKeys: options.maxObjectKeys },
                 { path: entry.path, keys: Object.keys(entry.value).length },
                 {
@@ -3632,7 +4462,7 @@ function createSafetyOversizedAttributeRule(options) {
                 failFinding(
                   "safety.oversizedAttribute",
                   `Value at ${entry.path} exceeds ${options.maxSerializedBytes} serialized bytes.`,
-                  [eventEvidence(event, entry.path)],
+                  [eventEvidence2(event, entry.path)],
                   { maxSerializedBytes: options.maxSerializedBytes },
                   { path: entry.path, bytes },
                   {
@@ -3759,7 +4589,7 @@ function createBaselineRegressionRule(options) {
           path: "guardrail",
           expected: guardrailShape(baselineContext),
           actual: guardrailShape(context),
-          evidence: guardrailEvents(context)[0] ? [eventEvidence(guardrailEvents(context)[0], "guardrail")] : runEvidence(context.selectedRun)
+          evidence: guardrailEvents(context)[0] ? [eventEvidence2(guardrailEvents(context)[0], "guardrail")] : runEvidence(context.selectedRun)
         }
       ];
       for (const comparison of comparisons) {
@@ -3928,13 +4758,17 @@ exports.createToolOrderingRule = createToolOrderingRule;
 exports.createToolUsageRule = createToolUsageRule;
 exports.defineTraceContract = defineTraceContract;
 exports.deriveFailureFacts = deriveFailureFacts;
+exports.deriveRelationshipFacts = deriveRelationshipFacts;
+exports.evaluateToolArgumentValue = evaluateToolArgumentValue;
 exports.evaluateTraceContract = evaluateTraceContract;
 exports.evaluateTraceContractRead = evaluateTraceContractRead;
 exports.explainTraceContract = explainTraceContract;
+exports.extractToolArgumentPayload = extractToolArgumentPayload;
 exports.formatProgrammaticDiagnostic = formatProgrammaticDiagnostic;
 exports.lintTraceContract = lintTraceContract;
 exports.projectLogicalEvents = projectLogicalEvents;
 exports.resolveCanonicalToolName = resolveCanonicalToolName;
+exports.resolveJsonPointer = resolveJsonPointer;
 exports.resolveTraceContractScope = resolveTraceContractScope;
 exports.runTraceChecks = runTraceChecks;
 exports.summarizeSemanticParity = summarizeSemanticParity;