agent-inspect 6.22.0 → 6.23.0

package/packages/core/dist/checks.cjs

@@ -1320,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 {
@@ -1341,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);
@@ -1553,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 = [
@@ -1582,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(
@@ -1642,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) {
@@ -1728,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`
       });
     }
@@ -2001,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) {
@@ -2044,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) {
@@ -2074,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(
@@ -2423,7 +3096,7 @@ function stripPrefix(name, prefixes) {
   }
   return name;
 }
-function eventEvidence(event, path3) {
+function eventEvidence2(event, path3) {
   return {
     runId: event.runId,
     eventId: event.eventId,
@@ -2693,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);
@@ -2726,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
             )
@@ -2772,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,
@@ -2798,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
           )
@@ -2813,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
             )
@@ -2849,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
           )
@@ -2947,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)
           );
         }
       }
@@ -2963,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;
@@ -2990,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)
           )
@@ -3012,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" }
             )
@@ -3023,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",
@@ -3038,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(),
@@ -3063,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" }
             )
@@ -3098,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",
@@ -3113,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(),
@@ -3137,7 +3810,7 @@ function createToolOrderingRule(options) {
               beforeEndedAt: beforeEvent.endedAt,
               afterStartedAt: afterEvent.startedAt ?? afterEvent.timestamp
             },
-            evidence: [eventEvidence(beforeEvent), eventEvidence(afterEvent)]
+            evidence: [eventEvidence2(beforeEvent), eventEvidence2(afterEvent)]
           }
         ];
       }
@@ -3160,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
           )
@@ -3173,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 }))
             )
@@ -3200,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
           )
@@ -3212,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")
           );
         }
       }
@@ -3247,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]
             )
@@ -3272,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
             )
@@ -3288,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
             )
@@ -3316,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
         )
@@ -3348,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()
                 )
@@ -3380,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
             )
@@ -3392,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"
             )
@@ -3409,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 }
               )
@@ -3423,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"
               )
@@ -3452,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,
@@ -3500,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
             )
@@ -3543,7 +4216,7 @@ function createSignalRule(ruleId, label, options, selectEvents, nameForEvent) {
             failFinding(
               ruleId,
               `Forbidden ${label} ${name} appeared.`,
-              [eventEvidence(event)],
+              [eventEvidence2(event)],
               `${label} absent`,
               name
             )
@@ -3554,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
             )
@@ -3577,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
           )
@@ -3631,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) },
               {
@@ -3665,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) },
               {
@@ -3703,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 },
                 {
@@ -3736,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 },
                 {
@@ -3753,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 },
                 {
@@ -3770,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 },
                 {
@@ -3789,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 },
                   {
@@ -3916,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) {
@@ -4086,13 +4759,16 @@ 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;