agent-inspect 6.19.0 → 6.20.0

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

@@ -1,4 +1,4 @@
-export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-Ca5yK8Cs.cjs';
+export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-C5ye_xcS.cjs';
 import { R as RedactionRule } from './log-config-CFlIJHTf.cjs';
 import { R as RedactionProfile, h as TraceEvent, E as ErrorInfo, b as RunStatus, e as StepStatus, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-UnrNaTo2.cjs';
 export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-UnrNaTo2.cjs';
@@ -8,7 +8,7 @@ import { P as PersistedInspectEvent } from './persisted-inspect-event-CVZWZldL.c
 import { Stats } from 'node:fs';
 import { b as ObservedOutcome } from './types-B562HgN_.cjs';
 export { O as ObservedOutcomeStatus } from './types-B562HgN_.cjs';
-import { b as TraceCheckResult, N as TraceCheckStatus } from './index-DCR816Yt.cjs';
+import { b as TraceCheckResult, N as TraceCheckStatus } from './index-rVpX5PPh.cjs';
 import './writers.cjs';
 import './index-vqr-g6ev.cjs';
 

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

@@ -1,4 +1,4 @@
-export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-D6cS4XIL.js';
+export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-CNsNSgE2.js';
 import { R as RedactionRule } from './log-config-OZRfpHED.js';
 import { R as RedactionProfile, h as TraceEvent, E as ErrorInfo, b as RunStatus, e as StepStatus, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types--ainI31J.js';
 export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types--ainI31J.js';
@@ -8,7 +8,7 @@ import { P as PersistedInspectEvent } from './persisted-inspect-event-BVucFVrP.j
 import { Stats } from 'node:fs';
 import { b as ObservedOutcome } from './types-B562HgN_.js';
 export { O as ObservedOutcomeStatus } from './types-B562HgN_.js';
-import { b as TraceCheckResult, N as TraceCheckStatus } from './index-DKwuGSe-.js';
+import { b as TraceCheckResult, N as TraceCheckStatus } from './index-Bg9ZdsdS.js';
 import './writers.js';
 import './index-AMAGuO_i.js';
 

package/packages/core/dist/advanced.mjs

@@ -1,14 +1,14 @@
-import { runTraceChecks, createRunStatusRule, createToolUsageRule, createRunDurationRule, createLlmUsageRule, createObservedOutcomeRule } from './chunk-NABMW5DX.mjs';
-export { MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, TERMINAL_INDENT, TraceDirectory, createInspector, createInspectorRuntime, formatTerminalName, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getIndent, getParentStepId, getTraceDirFromContext, getTraceSafetyFromContext, hasActiveContext, isAgentInspectEnabled, isSilentContext, maybeInspectRun, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, resolveTraceDir, runWithContext, runWithStepContext } from './chunk-ZWA5RWMV.mjs';
-import { buildRunTimeline, filterTraces, extractMetadata, buildRunSummary } from './chunk-SGL4JGCD.mjs';
-export { buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, formatStepLabel, renderRunWhat, renderTimeline, renderTraceStats } from './chunk-SGL4JGCD.mjs';
-import { extractOutcomesFromTraceEvents, parseObservationFilter, summarizeObservedOutcomes, extractOutcomesFromPersistedEvents, renderObservedOutcomesHtml } from './chunk-VFO76UH3.mjs';
-export { extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents } from './chunk-VFO76UH3.mjs';
+import { runTraceChecks, createRunStatusRule, createToolUsageRule, createRunDurationRule, createLlmUsageRule, createObservedOutcomeRule } from './chunk-G47KQB42.mjs';
+export { MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, TERMINAL_INDENT, TraceDirectory, createInspector, createInspectorRuntime, formatTerminalName, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getIndent, getParentStepId, getTraceDirFromContext, getTraceSafetyFromContext, hasActiveContext, isAgentInspectEnabled, isSilentContext, maybeInspectRun, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, resolveTraceDir, runWithContext, runWithStepContext } from './chunk-5YFJJFXU.mjs';
+import { buildRunTimeline, filterTraces, extractMetadata, buildRunSummary } from './chunk-JBNRJLIV.mjs';
+export { buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, formatStepLabel, renderRunWhat, renderTimeline, renderTraceStats } from './chunk-JBNRJLIV.mjs';
+import { extractOutcomesFromTraceEvents, parseObservationFilter, summarizeObservedOutcomes, extractOutcomesFromPersistedEvents, renderObservedOutcomesHtml } from './chunk-3XS5O4JI.mjs';
+export { extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents } from './chunk-3XS5O4JI.mjs';
 import { diffTraceEvents, renderRunDiff } from './chunk-F7STQ5JF.mjs';
 import './chunk-BT7CATSD.mjs';
 import { escapeHtml, flattenTree } from './chunk-CAWPF22J.mjs';
-import { resolveRedactionProfile, readTraceEventsFromFile } from './chunk-ULCGIRTC.mjs';
-export { DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, getRunIdFromTraceFileName, initializeTraceFile, listTraceFiles, prepareMetadataForDisk, prepareTraceEventForDisk, readTraceEvents, readTraceFile, resolveRedactionProfile, resolveTraceSafetyOptions, serializeEvent, validateEvent, writeTraceEvent } from './chunk-ULCGIRTC.mjs';
+import { resolveRedactionProfile, readTraceEventsFromFile } from './chunk-U25RHRSU.mjs';
+export { DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, getRunIdFromTraceFileName, initializeTraceFile, listTraceFiles, prepareMetadataForDisk, prepareTraceEventForDisk, readTraceEvents, readTraceFile, resolveRedactionProfile, resolveTraceSafetyOptions, serializeEvent, validateEvent, writeTraceEvent } from './chunk-U25RHRSU.mjs';
 import { Redactor } from './chunk-VU6O5QAH.mjs';
 import { openTrace } from './chunk-HT54OLPE.mjs';
 import './chunk-FWK3Q3OJ.mjs';

package/packages/core/dist/checks.cjs

@@ -928,6 +928,17 @@ function normalizeStatus(status) {
   if (status === "failed") return "error";
   return "error";
 }
+function cloneBody(body) {
+  return {
+    ...body.run ? { run: { ...body.run } } : {},
+    ...body.tools ? { tools: { ...body.tools } } : {},
+    ...body.llm ? { llm: { ...body.llm } } : {},
+    ...body.observations ? { observations: { ...body.observations } } : {}
+  };
+}
+function bodyHasRules(body) {
+  return body.run !== void 0 || body.tools !== void 0 || body.llm !== void 0 || body.observations !== void 0;
+}
 function contractToRules(contract) {
   const rules = [];
   const allowedStatuses = contract.run?.allowedStatuses ?? [];
@@ -1002,6 +1013,7 @@ function contractToRules(contract) {
   }
   if (contract.tools) {
     const order = contract.tools.requiredOrder ?? [];
+    const requiredOrderMode = contract.tools.requiredOrderMode ?? "first-occurrence";
     const required = [
       .../* @__PURE__ */ new Set([
         ...contract.tools.required ?? [],
@@ -1026,7 +1038,8 @@ function contractToRules(contract) {
         createToolOrderingRule({
           before: order[i],
           after: order[i + 1],
-          id: `contract.tool.order.${i}`
+          id: `contract.tool.order.${i}`,
+          mode: requiredOrderMode
         })
       );
     }
@@ -1076,24 +1089,318 @@ function contractToRules(contract) {
   }
   return rules;
 }
-function defineTraceContract(input) {
+function validateAlternativesShape(alternatives) {
+  const diagnostics = [];
+  if (alternatives === void 0) return diagnostics;
+  const branches = alternatives.anyOf ?? [];
+  if (branches.length === 0) {
+    diagnostics.push({
+      code: "contract.alternatives.empty",
+      severity: "error",
+      message: "alternatives.anyOf must contain at least one branch.",
+      path: "alternatives.anyOf"
+    });
+    return diagnostics;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, branch] of branches.entries()) {
+    const path3 = `alternatives.anyOf[${index}]`;
+    if (!branch?.id || branch.id.trim() === "") {
+      diagnostics.push({
+        code: "contract.alternatives.missing-id",
+        severity: "error",
+        message: "Each alternatives.anyOf branch requires a non-empty id.",
+        path: path3
+      });
+      continue;
+    }
+    if (seen.has(branch.id)) {
+      diagnostics.push({
+        code: "contract.alternatives.duplicate-id",
+        severity: "error",
+        message: `Duplicate alternatives.anyOf branch id: ${branch.id}`,
+        path: `${path3}.id`
+      });
+    }
+    seen.add(branch.id);
+    if (!bodyHasRules(branch.contract ?? {})) {
+      diagnostics.push({
+        code: "contract.alternatives.empty-branch",
+        severity: "error",
+        message: `Branch ${branch.id} must declare at least one run/tools/llm/observations rule.`,
+        path: `${path3}.contract`
+      });
+    }
+    const nested = branch.contract?.alternatives;
+    if (nested !== void 0) {
+      diagnostics.push({
+        code: "contract.alternatives.nested",
+        severity: "error",
+        message: "Nested alternatives.anyOf is not supported. Keep one alternatives level only.",
+        path: `${path3}.contract.alternatives`
+      });
+    }
+  }
+  return diagnostics;
+}
+function emptyPassResult(input, runId) {
   return {
-    ...input.run ? { run: { ...input.run } } : {},
-    ...input.tools ? { tools: { ...input.tools } } : {},
-    ...input.llm ? { llm: { ...input.llm } } : {},
-    ...input.observations ? { observations: { ...input.observations } } : {}
+    ok: true,
+    status: "pass",
+    format: input.read.format,
+    ...runId !== void 0 ? { runId } : {},
+    summary: { passed: 0, failed: 0, warnings: 0, errors: 0, rulesEvaluated: 0 },
+    findings: [],
+    diagnostics: [],
+    ruleExecutions: []
   };
 }
-function evaluateTraceContract(input, contract, options = {}) {
-  const rules = contractToRules(contract);
+function mergeContractResults(input, parts, extraFindings = []) {
+  const findings = [...parts.flatMap((part) => part.findings), ...extraFindings];
+  const diagnostics = parts.flatMap((part) => part.diagnostics);
+  const ruleExecutions = parts.flatMap((part) => part.ruleExecutions);
+  const failed = findings.filter(
+    (finding) => finding.status === "fail" && finding.severity === "error"
+  ).length;
+  const errors = diagnostics.filter((item) => item.severity === "error").length;
+  const status = errors > 0 ? "error" : failed > 0 ? "fail" : "pass";
+  const runId = parts.find((part) => part.runId !== void 0)?.runId;
+  return {
+    ok: status === "pass",
+    status,
+    format: input.read.format,
+    ...runId !== void 0 ? { runId } : {},
+    summary: {
+      passed: findings.filter((finding) => finding.status === "pass").length,
+      failed,
+      warnings: findings.filter(
+        (finding) => finding.status === "warning" || finding.severity === "warning"
+      ).length,
+      errors,
+      rulesEvaluated: ruleExecutions.length
+    },
+    findings,
+    diagnostics,
+    ruleExecutions
+  };
+}
+function evaluateBody(input, body, options = {}) {
+  const rules = contractToRules(body);
+  if (rules.length === 0) {
+    return emptyPassResult(input, options.runId);
+  }
   return runTraceChecks(input, {
     rules,
     ...options.runId !== void 0 ? { runId: options.runId } : {}
   });
 }
+function defineTraceContract(input) {
+  const shapeErrors = validateAlternativesShape(input.alternatives).filter(
+    (item) => item.severity === "error"
+  );
+  if (shapeErrors.length > 0) {
+    throw new TypeError(shapeErrors.map((item) => item.message).join(" "));
+  }
+  const body = cloneBody(input);
+  const alternatives = input.alternatives ? {
+    anyOf: input.alternatives.anyOf.map((branch) => ({
+      id: branch.id,
+      ...branch.description !== void 0 ? { description: branch.description } : {},
+      contract: cloneBody(branch.contract)
+    }))
+  } : void 0;
+  return {
+    ...body,
+    ...alternatives ? { alternatives } : {}
+  };
+}
+function evaluateTraceContract(input, contract, options = {}) {
+  const shapeErrors = validateAlternativesShape(contract.alternatives).filter(
+    (item) => item.severity === "error"
+  );
+  if (shapeErrors.length > 0) {
+    return {
+      ok: false,
+      status: "error",
+      format: input.read.format,
+      ...options.runId !== void 0 ? { runId: options.runId } : {},
+      summary: {
+        passed: 0,
+        failed: 0,
+        warnings: 0,
+        errors: shapeErrors.length,
+        rulesEvaluated: 0
+      },
+      findings: [],
+      diagnostics: shapeErrors.map((item) => ({
+        code: "AI_CHECK_INVALID_CONFIG",
+        message: item.message,
+        severity: "error",
+        ruleId: item.code
+      })),
+      ruleExecutions: []
+    };
+  }
+  const base = evaluateBody(input, contract, options);
+  const branches = contract.alternatives?.anyOf ?? [];
+  if (branches.length === 0) {
+    return base;
+  }
+  const branchEvaluations = branches.map((branch) => {
+    const result = evaluateBody(input, branch.contract, options);
+    return { branch, result };
+  });
+  const satisfied = branchEvaluations.filter((item) => item.result.ok && item.result.status === "pass").map((item) => item.branch.id);
+  const failedBranches = branchEvaluations.filter(
+    (item) => !(item.result.ok && item.result.status === "pass")
+  );
+  if (satisfied.length > 0) {
+    const passFinding = {
+      ruleId: "contract.alternatives.anyOf",
+      severity: "info",
+      status: "pass",
+      message: `Satisfied alternative branch(es): ${satisfied.join(", ")}.`,
+      expected: { anyOf: branches.map((branch) => branch.id) },
+      actual: {
+        satisfied,
+        failed: failedBranches.map((item) => item.branch.id)
+      },
+      evidence: []
+    };
+    return mergeContractResults(input, [base], [passFinding]);
+  }
+  const noneFinding = {
+    ruleId: "contract.alternatives.none-satisfied",
+    severity: "error",
+    status: "fail",
+    message: "No alternatives.anyOf branch fully satisfied its contract.",
+    expected: { anyOf: branches.map((branch) => branch.id) },
+    actual: {
+      branchFailures: Object.fromEntries(
+        failedBranches.map((item) => [
+          item.branch.id,
+          item.result.findings.filter((finding) => finding.status === "fail").map((finding) => ({
+            ruleId: finding.ruleId,
+            message: finding.message
+          }))
+        ])
+      )
+    },
+    evidence: []
+  };
+  const prefixedBranchFindings = failedBranches.flatMap(
+    (item) => item.result.findings.filter((finding) => finding.status === "fail").map((finding) => ({
+      ...finding,
+      ruleId: `contract.alternatives.${item.branch.id}.${finding.ruleId}`
+    }))
+  );
+  return mergeContractResults(input, [base], [noneFinding, ...prefixedBranchFindings]);
+}
 function evaluateTraceContractRead(read, contract, options = {}) {
   return evaluateTraceContract({ read }, contract, options);
 }
+function lintTraceContract(contract) {
+  const diagnostics = validateAlternativesShape(contract.alternatives);
+  const branches = contract.alternatives?.anyOf ?? [];
+  if (branches.length === 1) {
+    diagnostics.push({
+      code: "contract.alternatives.single-branch",
+      severity: "warning",
+      message: "alternatives.anyOf has a single branch. Prefer base rules unless a second valid path exists.",
+      path: "alternatives.anyOf"
+    });
+  }
+  const required = [
+    ...contract.tools?.required ?? [],
+    ...contract.tools?.requiredTools ?? []
+  ];
+  if (required.length > 0 && branches.length === 0) {
+    diagnostics.push({
+      code: "contract.brittle.unconditional-required",
+      severity: "info",
+      message: "tools.required is unconditional. Use alternatives.anyOf when a legitimate shortcut may skip a tool.",
+      path: "tools.required"
+    });
+  }
+  const order = contract.tools?.requiredOrder ?? [];
+  if (order.length >= 2 && contract.tools?.requiredOrderMode === void 0) {
+    diagnostics.push({
+      code: "contract.brittle.first-occurrence-default",
+      severity: "info",
+      message: "requiredOrder defaults to first-occurrence. Set requiredOrderMode when repeated calls must fail.",
+      path: "tools.requiredOrderMode"
+    });
+  }
+  return diagnostics;
+}
+function explainTraceContract(contract) {
+  const lines = [];
+  if (contract.run?.requireCompleted !== false) {
+    lines.push("Base: run must complete (no running events).");
+  }
+  if (contract.run?.allowedStatuses?.length) {
+    lines.push(`Base: run status in [${contract.run.allowedStatuses.join(", ")}].`);
+  }
+  if (contract.run?.maxDurationMs !== void 0) {
+    lines.push(`Base: run duration <= ${contract.run.maxDurationMs}ms.`);
+  }
+  if (contract.tools) {
+    const required = [
+      .../* @__PURE__ */ new Set([
+        ...contract.tools.required ?? [],
+        ...contract.tools.requiredTools ?? [],
+        ...contract.tools.requiredOrder ?? []
+      ])
+    ];
+    if (required.length > 0) {
+      lines.push(`Base: required tools [${required.join(", ")}].`);
+    }
+    const forbidden = [
+      ...contract.tools.forbidden ?? [],
+      ...contract.tools.forbiddenTools ?? []
+    ];
+    if (forbidden.length > 0) {
+      lines.push(`Base: forbidden tools [${forbidden.join(", ")}].`);
+    }
+    if ((contract.tools.requiredOrder?.length ?? 0) >= 2) {
+      const mode = contract.tools.requiredOrderMode ?? "first-occurrence";
+      lines.push(
+        `Base: requiredOrder [${contract.tools.requiredOrder.join(" \u2192 ")}] mode=${mode}.`
+      );
+    }
+  }
+  if (contract.llm) {
+    if (contract.llm.maxCalls !== void 0) {
+      lines.push(`Base: LLM maxCalls=${contract.llm.maxCalls}.`);
+    }
+    if (contract.llm.maxTotalTokens !== void 0) {
+      lines.push(`Base: LLM maxTotalTokens=${contract.llm.maxTotalTokens}.`);
+    }
+    if (contract.llm.allowedModels?.length) {
+      lines.push(`Base: LLM allowedModels [${contract.llm.allowedModels.join(", ")}].`);
+    }
+  }
+  if (contract.observations?.required?.length) {
+    lines.push(`Base: required observations [${contract.observations.required.join(", ")}].`);
+  }
+  if (contract.observations?.failOn?.length) {
+    lines.push(`Base: fail on observations [${contract.observations.failOn.join(", ")}].`);
+  }
+  const branches = contract.alternatives?.anyOf ?? [];
+  if (branches.length > 0) {
+    lines.push(
+      `Alternatives: at least one of [${branches.map((branch) => branch.id).join(", ")}] must fully pass.`
+    );
+    for (const branch of branches) {
+      const detail = branch.description ? ` \u2014 ${branch.description}` : "";
+      lines.push(`  branch ${branch.id}${detail}`);
+    }
+  }
+  if (lines.length === 0) {
+    lines.push("Empty contract: no base rules and no alternatives.");
+  }
+  return lines;
+}
 
 // packages/core/src/checks/index.ts
 var SEVERITY_RANK = {
@@ -1977,6 +2284,7 @@ function createToolUsageRule(options) {
 }
 function createToolOrderingRule(options) {
   const ruleId = options.id ?? "tool.order";
+  const mode = options.mode ?? "first-occurrence";
   return {
     id: ruleId,
     category: "tool",
@@ -1989,7 +2297,7 @@ function createToolOrderingRule(options) {
       if (beforeIndex === void 0 || afterIndex === void 0) {
         return [];
       }
-      if (beforeIndex >= afterIndex) {
+      if (mode === "first-occurrence" && beforeIndex >= afterIndex) {
         return [
           failFinding(
             ruleId,
@@ -2004,6 +2312,130 @@ function createToolOrderingRule(options) {
       const afterEvent = tools[afterIndex];
       const beforeEnd = eventEndMs(beforeEvent);
       const afterStart = eventStartMs(afterEvent);
+      if (mode === "happens-before") {
+        const expected = {
+          before: options.before,
+          after: options.after,
+          mode,
+          relation: "before.end <= after.start"
+        };
+        if (options.before === options.after) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool ${options.before} cannot causally happen before itself.`,
+              [eventEvidence(beforeEvent)],
+              expected,
+              { code: "tool.order.same-tool" }
+            )
+          ];
+        }
+        if (beforeEnd === void 0 || afterStart === void 0) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool order ${options.before} before ${options.after} could not establish causal timing.`,
+              [eventEvidence(beforeEvent), eventEvidence(afterEvent)],
+              expected,
+              {
+                code: "tool.order.interval-unresolved",
+                beforeEndResolved: beforeEnd !== void 0,
+                afterStartResolved: afterStart !== void 0
+              }
+            )
+          ];
+        }
+        if (beforeEnd > afterStart) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool ${options.before} must finish before ${options.after} starts.`,
+              [eventEvidence(beforeEvent), eventEvidence(afterEvent)],
+              expected,
+              {
+                beforeEndedAt: new Date(beforeEnd).toISOString(),
+                afterStartedAt: new Date(afterStart).toISOString()
+              }
+            )
+          ];
+        }
+        return [];
+      }
+      if (mode === "all-occurrences") {
+        const beforeEvents = tools.filter((event) => toolName(event) === options.before);
+        const afterEvents = tools.filter((event) => toolName(event) === options.after);
+        const expected = {
+          before: options.before,
+          after: options.after,
+          mode,
+          relation: "max(before.end) <= min(after.start)"
+        };
+        if (options.before === options.after) {
+          return [
+            failFinding(
+              ruleId,
+              `Tool ${options.before} cannot causally happen before itself.`,
+              [eventEvidence(beforeEvent)],
+              expected,
+              { code: "tool.order.same-tool" }
+            )
+          ];
+        }
+        let latestBefore;
+        let earliestAfter;
+        let missingBeforeEnds = 0;
+        let missingAfterStarts = 0;
+        let firstMissingBefore;
+        let firstMissingAfter;
+        for (const event of beforeEvents) {
+          const end = eventEndMs(event);
+          if (end === void 0) {
+            missingBeforeEnds += 1;
+            firstMissingBefore ??= event;
+          } else if (latestBefore === void 0 || end > latestBefore.end) {
+            latestBefore = { event, end };
+          }
+        }
+        for (const event of afterEvents) {
+          const start = eventStartMs(event);
+          if (start === void 0) {
+            missingAfterStarts += 1;
+            firstMissingAfter ??= event;
+          } else if (earliestAfter === void 0 || start < earliestAfter.start) {
+            earliestAfter = { event, start };
+          }
+        }
+        if (missingBeforeEnds > 0 || missingAfterStarts > 0 || latestBefore === void 0 || earliestAfter === void 0) {
+          return [
+            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)),
+              expected,
+              {
+                code: "tool.order.interval-unresolved",
+                missingBeforeEnds,
+                missingAfterStarts
+              }
+            )
+          ];
+        }
+        if (latestBefore.end > earliestAfter.start) {
+          return [
+            failFinding(
+              ruleId,
+              `Every ${options.before} tool call must finish before any ${options.after} tool call starts.`,
+              [eventEvidence(latestBefore.event), eventEvidence(earliestAfter.event)],
+              expected,
+              {
+                latestBeforeEndedAt: new Date(latestBefore.end).toISOString(),
+                earliestAfterStartedAt: new Date(earliestAfter.start).toISOString()
+              }
+            )
+          ];
+        }
+        return [];
+      }
       if (beforeEnd !== void 0 && afterStart !== void 0 && beforeEnd > afterStart) {
         return [
           {
@@ -2967,7 +3399,9 @@ exports.defineTraceContract = defineTraceContract;
 exports.deriveFailureFacts = deriveFailureFacts;
 exports.evaluateTraceContract = evaluateTraceContract;
 exports.evaluateTraceContractRead = evaluateTraceContractRead;
+exports.explainTraceContract = explainTraceContract;
 exports.formatProgrammaticDiagnostic = formatProgrammaticDiagnostic;
+exports.lintTraceContract = lintTraceContract;
 exports.projectLogicalEvents = projectLogicalEvents;
 exports.resolveCanonicalToolName = resolveCanonicalToolName;
 exports.runTraceChecks = runTraceChecks;