agent-inspect 6.17.4 → 6.17.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 6.17.5
+
+### Patch Changes
+
+- 093811b: Harden deterministic TraceContract / check gates against fail-open empty configs (rule execution evidence, unique order IDs, requiredOrder implies presence, tool policy includes running invocations, ObservedOutcome requireAny), map #308–#311 release ownership, and make demo:verify / pack:smoke validation cross-platform without unnecessary shell invocation.
+
 ## 6.17.4
 
 ### Patch Changes

package/README.md

@@ -210,7 +210,7 @@ The root package is enough for custom capture, the CLI, checks, and Evidence wor
 
 ## Status and documentation
 
-**Current published baseline:** **6.17.3** · persisted schema `1.0` · Node.js `>=20` · MIT.
+**Current published baseline:** **6.17.5** · persisted schema `1.0` · Node.js `>=20` · MIT.
 
 Legacy v0.1 and v0.2 traces remain readable. Check the npm badge and [changelog](CHANGELOG.md) for the current published version.
 

package/docs/ADAPTERS.md

@@ -22,7 +22,7 @@ Reporters (`@agent-inspect/vitest` and `@agent-inspect/jest`) are public package
 
 **Status:** experimental adapter — optional package published in the aligned v2.2.0 package set and hardened in the v2.3 adapter train.
 
-The adapter has hardened lifecycle identity and parallel integration isolation. It remains metadata-only: `capture: "preview"` and preview-only redaction options emit diagnostics and fall back to metadata-only capture until bounded free-text previews are implemented.
+The adapter has hardened lifecycle identity and parallel integration isolation. It remains metadata-only: `capture: "preview"` and preview-only redaction options emit diagnostics **and one visible** `AI_ADAPTER_PREVIEW_NOT_AVAILABLE` warning per adapter instance, then fall back to metadata-only capture. Bounded free-text preview capture is planned for a later train; it is not implemented here.
 
 ### Install
 
@@ -59,7 +59,7 @@ const result = await generateText({
 - **Metadata-only by default** — records model, finish reason, token usage, timing, and safe counts/summaries.
 - **Required safe telemetry settings** — set `recordInputs: false` and `recordOutputs: false` on every AI SDK call using this adapter.
 - **No raw payload capture by default** — prompts, messages, generated text, stream chunks, tool inputs/outputs, headers, request bodies, and response bodies are not persisted.
-- **Preview capture is not enabled yet** — `capture: "preview"`, `redactionProfile`, and `maxPreviewChars` are diagnosed through `getDiagnostics()` and do not persist raw previews.
+- **Preview capture is not enabled yet** — requesting `capture: "preview"` emits one console warning with code `AI_ADAPTER_PREVIEW_NOT_AVAILABLE`, records diagnostics via `getDiagnostics()`, and does not persist raw previews. Effective capture remains metadata-only.
 
 ### Local no-network recipe
 
@@ -375,7 +375,7 @@ Integration modes:
 - **No upload behavior** — the processor writes only to an explicit local writer or `traceDir`.
 - **Metadata-only by default** — records trace/span IDs, parentage, names, timing, status, errors, safe model/tool names, token counts, and bounded summaries.
 - **No raw payload capture by default** — prompts, messages, generated text, function inputs/outputs, arbitrary custom data, trace exporter credentials, headers, request bodies, response bodies, and hosted tool payloads are not persisted.
-- **Preview capture is not enabled yet** — `capture: "preview"`, `redactionProfile`, and `maxPreviewChars` are diagnosed through `getDiagnostics()` and do not persist raw previews.
+- **Preview capture is not enabled yet** — requesting `capture: "preview"` emits one console warning with code `AI_ADAPTER_PREVIEW_NOT_AVAILABLE`, records diagnostics via `getDiagnostics()`, and does not persist raw previews. Effective capture remains metadata-only.
 - **Fixture-backed lifecycle coverage** — local tests and the recipe cover agent, generation, function tool, handoff, guardrail, response, MCP tools, custom, transcription, and speech span shapes without provider calls.
 
 Full API: [API.md](./API.md) §14.

package/docs/API.md

@@ -180,7 +180,11 @@ Diff is local and read-only. Programmatic diff surfaces are experimental until t
   - In-memory **`getEvents()`** / **`clear()`** unchanged when `persist` is false
 - Metadata helpers: `extractModelName`, `extractTokenUsage`, `safePreview`, `toPlainMetadata`
 
-Rationale: v1.x includes one official adapter and **zero production sinks**, so adapter surfaces remain experimental.
+Rationale: one official adapter and **zero production sinks** keep adapter surfaces experimental; they remain additive in minors.
+
+### TraceContract `requiredOrder`
+
+When defining `tools.requiredOrder`, the array expands into adjacent first-occurrence pair checks. Unlisted intermediate tools are allowed; later repetitions do not invalidate an earlier valid first-occurrence order. Missing tools are handled by required-tool rules, not ordering alone. See [TRACE-CONTRACTS.md](./TRACE-CONTRACTS.md).
 
 ## 10. Experimental `@agent-inspect/tui` APIs
 
@@ -249,7 +253,7 @@ The manifest records framework, generation time, bounded test results, artifact
 
 ## 12. Experimental `@agent-inspect/vitest` APIs
 
-`@agent-inspect/vitest` is an optional experimental workspace package for local Vitest failure artifacts. It remains private/unpublished pending maintainer first-publication setup. It does not add a Vitest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+`@agent-inspect/vitest` is an optional experimental workspace package for local Vitest failure artifacts. It is published with the fixed release group. It does not add a Vitest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
 
 Import from `@agent-inspect/vitest`:
 
@@ -282,7 +286,7 @@ Artifacts are safe structural summaries. The reporter writes a shared `schemaVer
 
 ## 13. Experimental `@agent-inspect/jest` APIs
 
-`@agent-inspect/jest` is an optional experimental workspace package for local Jest failure artifacts. It remains private/unpublished pending maintainer first-publication setup. It does not add a Jest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
+`@agent-inspect/jest` is an optional experimental workspace package for local Jest failure artifacts. It is published with the fixed release group. It does not add a Jest dependency to root/core, does not upload artifacts, and does not infer trace relationships by timestamp.
 
 Import from `@agent-inspect/jest`:
 
@@ -423,8 +427,8 @@ import type {
 ```
 
 - **`TraceWriter`**: async `write(event)`, optional `flush()`, optional `close()`, optional `getStats()`.
-- **`fileWriter({ dir?, filePath? })`**: appends `PersistedInspectEvent` JSONL rows to local disk. `createInspector()` emits schema 1.0 rows by default; compatibility adapters may still pass readable v0.2 rows. By default it derives one file per `event.runId`; `filePath` writes all events to an explicit local file. Filesystem and serialization failures are reflected in writer stats instead of being thrown into application code.
-- **`bufferedFileWriter({ dir?, filePath?, maxQueueSize?, flushIntervalMs?, maxBatchSize?, overflow? })`**: buffers local JSONL writes with bounded queue behavior. Overflow supports `drop-oldest` and `drop-newest`; neither mode throws into application code.
+- **`fileWriter({ dir?, filePath? })`**: appends `PersistedInspectEvent` JSONL rows to local disk. `createInspector()` emits schema 1.0 rows by default; compatibility adapters may still pass readable v0.2 rows. By default it derives one file per `event.runId`; `filePath` writes all events to an explicit local file. Filesystem and serialization failures are reflected in writer stats instead of being thrown into application code. Append-only local JSONL is diagnostic persistence — not a write-ahead log or fsync-guaranteed durable-before-effect journal.
+- **`bufferedFileWriter({ dir?, filePath?, maxQueueSize?, flushIntervalMs?, maxBatchSize?, overflow? })`**: buffers local JSONL writes with bounded queue behavior. Overflow supports `drop-oldest` and `drop-newest`; neither mode throws into application code. On abrupt process exit, a bounded unflushed tail may be lost.
 - **`compositeWriter([...writers])`**: fans out events to multiple explicit local/custom writers. A failing child writer does not prevent other children from receiving events; failures are reflected in composite stats.
 - **`memoryWriter()`**: stores cloned `PersistedInspectEvent` rows in memory for tests, adapter fixtures, and eval harnesses.
 - **`nullWriter()`**: accepts events without retaining them for disabled mode, overhead comparisons, and no-output tests.
@@ -433,7 +437,7 @@ No network writer or vendor sink exists in this package.
 
 ## 19. Experimental inspector API/runtime (v1.6)
 
-`createInspector()` is the public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records schema 1.0 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks.
+`createInspector()` is the public instance API for local-first tracing with explicit writers. It owns an instance-specific runtime context, records schema 1.0 persisted inspect events, preserves application return values/errors, and exposes diagnostics plus deterministic `flush()`/`close()` lifecycle hooks (`flush`/`close` drain writer queues idempotently — they do not claim crash durability or fsync).
 
 Import from `agent-inspect`:
 
@@ -537,7 +541,9 @@ import type { TraceCheckRule, TraceCheckResult, TraceFacts } from "agent-inspect
 - **`TraceCheckRule`**: synchronous pure rule contract.
 - **`TraceCheckResult`**: deterministic aggregate result with findings, evidence, summary counts, and execution diagnostics.
 
-The checks API is experimental in v1.x. The `agent-inspect check` CLI uses this API for local reader-backed checks and deterministic JSON output; `agent-inspect artifacts` reuses the same safe findings for local CI artifact bundles and optional step-summary file output. Built-in rules operate on normalized event metadata, tree relationships, bounded summaries, token counts, and normalized baseline facts; safety and baseline findings identify event IDs and field paths rather than emitting raw prompts, outputs, secrets, headers, request/response bodies, or full tool payloads.
+The checks API is experimental. The `agent-inspect check` CLI uses this API for local reader-backed checks and deterministic JSON output; `agent-inspect artifacts` reuses the same safe findings for local CI artifact bundles and optional step-summary file output. Built-in rules operate on normalized event metadata, tree relationships, bounded summaries, token counts, and normalized baseline facts; safety and baseline findings identify event IDs and field paths rather than emitting raw prompts, outputs, secrets, headers, request/response bodies, or full tool payloads.
+
+@beta Available through `agent-inspect/checks`. Additive changes may ship in minor releases; breaking changes require a future major.
 
 Recipes: [deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md) for check/baseline/artifact workflows, and [test-reporter-artifacts](../examples/recipes/test-reporter-artifacts/README.md) for Vitest/Jest reporter configuration patterns.
 

package/docs/CLI.md

@@ -204,6 +204,8 @@ Options:
 - `--refresh <ms>`: minimum time between renders
 - `--json`: newline-delimited JSON updates
 
+**Truncation recovery:** when a watched `--file` shrinks below the last read offset (for example a truncate-and-rewrite), `tail` resets the offset, discards any buffered partial line, and continues the same session from the start of the current file contents. Full inode-aware rename/recreate rotation is **not** claimed unless separately implemented and tested.
+
 Important: `tail` is a local developer tool, not a production monitor.
 
 ### 6.6 `export`

package/docs/LIMITATIONS.md

@@ -23,6 +23,7 @@ This document states what AgentInspect **does not** provide today. It complement
 
 - **Subpath APIs:** `agent-inspect/writers`, `agent-inspect/readers`, and advanced helpers are available for local adoption from their owning subpaths. `createInspector()` is part of the small root API.
 - **Explicit writer ownership:** `createInspector()` does not print terminal lifecycle output or implicitly choose a disk writer. Use `fileWriter()` / `bufferedFileWriter()` / custom writers when persistence is desired.
+- **Diagnostic evidence, not an event-sourced runtime:** AgentInspect traces are local diagnostic evidence of what an agent did. They are **not** a write-ahead log, durable-before-effect journal, or application event-sourcing runtime. Buffered writers may lose a bounded tail of events on abrupt process termination. Call `flush()` / `close()` according to writer docs when you need the queue drained before exit; that lifecycle is deterministic and idempotent, but it is **not** an fsync / crash-durability guarantee.
 - **No standards upload:** OpenInference and OTLP JSON support is local read/export compatibility only. There is no OTLP gRPC/HTTP streaming sink, collector client, or hosted ingestion behavior.
 - **Conservative detection:** `agent-inspect open` does not silently accept arbitrary JSON. Unsupported or ambiguous inputs produce errors/warnings rather than guessed traces.
 - **Large inputs:** reader inputs are bounded and read into local memory. This is not a database index or production log warehouse.

package/docs/TRACE-CONTRACTS.md

@@ -14,6 +14,36 @@ Contracts compile to deterministic check rules for common cases:
 - evidence-bearing findings on failures
 - evaluation over **logical** TraceFacts (raw events remain available)
 
+## `tools.requiredOrder` semantics
+
+`requiredOrder` is expanded into **adjacent pair** ordering rules with unique ids:
+
+```text
+[A, B, C]
+→ contract.tool.order.0: A before B
+→ contract.tool.order.1: B before C
+```
+
+Each pair compares the **first occurrence** (start/encounter order in the evaluated event stream):
+
+- unlisted intermediate tools are allowed;
+- later repetitions do not invalidate an earlier valid first-occurrence order;
+- TraceContract `requiredOrder` **implies presence** — every listed name is added to the effective required-tool set;
+- this is **not** causal happens-before; overlapping intervals emit a non-failing `tool.order.overlap` warning;
+- combine ordering with `maxCalls` or custom rules when repeated calls matter.
+
+Examples for `requiredOrder: ["retrieve", "generate"]`:
+
+| Trajectory | Result |
+| --- | --- |
+| `retrieve → generate` | PASS |
+| `retrieve → rerank → generate` | PASS |
+| `retrieve → generate → retrieve` | PASS (first-occurrence) |
+| `generate → retrieve` | FAIL (order) |
+| `cache_lookup → generate` | FAIL (missing `retrieve` via implied presence) |
+
+Low-level `createToolOrderingRule({ before, after })` alone may still pass when an endpoint is missing (compositional). TraceContract `requiredOrder` does not.
+
 ### Experimental Vitest / Jest matchers (shipped)
 
 | Package | Export | Matchers |
@@ -25,6 +55,66 @@ These are **Experimental** — API names may evolve. There is no `expectTrace(..
 
 See [API.md](./API.md), [TRACE-FACTS.md](./TRACE-FACTS.md), and `packages/core/src/checks/contract.ts`.
 
+## Rule kinds (shipped vs planned)
+
+TraceContract rules fall into distinct categories. Mixing them incorrectly is a common source of false failures (see GitHub #308 and #309).
+
+### `tools.required` (shipped)
+
+Unconditional path invariant: every named tool must appear **at least once** in the trace.
+
+- Use when the tool is always part of a valid execution path.
+- **Do not** use for steps that legitimate shortcuts may skip (for example cache hits that bypass `retrieve`).
+- When a shortcut is valid but you still need evidence of the outcome, prefer `observations.required` until `alternatives.anyOf` ships (6.20.0).
+
+### `tools.requiredOrder` (shipped — first-occurrence / start-encounter)
+
+Legacy first-start / encounter ordering. The evaluator walks the trace and checks that each listed tool's **first occurrence** appears after the previous tool's first occurrence.
+
+- TraceContract `requiredOrder` **implies presence** of every listed tool (unioned into `tools.required`).
+- Default mode is **first-occurrence** start/encounter order — **not** causal happens-before.
+- Overlapping intervals that still satisfy start order emit a non-failing overlap warning.
+- **Planned (6.20.0, GitHub #308):**
+  - `requiredOrderMode: "happens-before"` — first before must **end** before first after **starts**
+  - `requiredOrderMode: "all-occurrences"` — every before must end before every after starts
+
+### `observations.required` (shipped)
+
+Requires externally observed or effect evidence (for example HTTP status, file write, cache key) rather than a specific tool call. Prefer this when the invariant is about **outcome** rather than **which tool ran**.
+
+### Planned (6.20.0 — not shipped)
+
+Document only; **do not** use these fields in contracts today:
+
+| Planned field | Purpose | GitHub |
+|---------------|---------|--------|
+| `alternatives.anyOf` | One of several deterministic valid paths (one level, no nested groups, no predicates) | #309 |
+| `requiredOrderMode: "happens-before"` | Causal completion-before-start ordering | #308 |
+| `requiredOrderMode: "all-occurrences"` | Strict ordering across all tool occurrences | #308 |
+
+API shape for both requires maintainer approval before external PR lands. @HsienW volunteered on #308 for `requiredOrderMode` implementation.
+
+## Workaround until 6.20.0
+
+When a legitimate shortcut skips a tool you would otherwise require:
+
+1. **Remove** unconditional `tools.required` for that step.
+2. **Express** the verified outcome via `observations.required` when possible.
+3. **Document** the cache-hit or alternate path in contract comments for reviewers.
+
+Example matching GitHub #309 (cache hit skips second `retrieve`):
+
+```yaml
+contract:
+  tools:
+    required: [generate] # not retrieve — cache may skip it
+    requiredOrder: [generate] # ordering only among tools that ran
+  observations:
+    required: [cache_hit_or_retrieve_evidence]
+```
+
+With first-occurrence ordering, `retrieve → generate → retrieve` still **passes** when both retrieves are present (see worked example below).
+
 ## What is not shipped (yet)
 
 Do **not** document these as available:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "6.17.4",
+  "version": "6.17.5",
   "license": "MIT",
   "type": "module",
   "description": "Local evidence debugger and trajectory-test toolkit for TypeScript AI agents — execution trees, TraceContract checks, Evidence v2, and read-only MCP",
@@ -239,10 +239,12 @@
     "linked-versions:check": "node scripts/check-linked-versions.mjs",
     "docs:commands": "node scripts/validate-doc-commands.mjs",
     "docs:links": "node scripts/validate-doc-links.mjs",
+    "public-truth:sync": "node scripts/sync-public-truth.mjs",
     "public-truth:check": "node scripts/validate-public-truth.mjs",
     "ai-assets:check": "node scripts/validate-ai-assets.mjs",
     "package-readmes:check": "node scripts/validate-package-readmes.mjs",
-    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run package-readmes:check && pnpm run repo:health && pnpm run demo:verify",
+    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run package-readmes:check && pnpm run repo:health && pnpm run build:cli && pnpm run demo:verify",
+    "build:cli": "pnpm exec tsup --config tsup.cli.config.ts",
     "repo:health": "node scripts/validate-repo-health.mjs",
     "demo:generate": "node scripts/demo-generate.mjs",
     "demo:verify": "node scripts/demo-verify.mjs",
@@ -252,6 +254,7 @@
     "perf:baseline": "node scripts/performance-baseline.mjs",
     "examples:check": "pnpm install && pnpm --filter agent-inspect-example-01-basic run start",
     "changeset": "changeset",
+    "version:packages": "changeset version && pnpm public-truth:sync && pnpm public-truth:check",
     "release": "changeset publish",
     "website:dev": "pnpm --filter @agent-inspect/website dev",
     "website:build": "pnpm --filter @agent-inspect/website build",

package/packages/cli/dist/{chunk-YX6RFLV5.mjs → chunk-GOHYSE7W.mjs}

@@ -3230,14 +3230,15 @@ function enrichSessionSummary(summary, runs, options = {}) {
 
 // packages/core/src/sessions/checks.ts
 function emptySummary() {
-  return { passed: 0, failed: 0, warnings: 0, errors: 0 };
+  return { passed: 0, failed: 0, warnings: 0, errors: 0, rulesEvaluated: 0 };
 }
 function mergeSummary(target, source) {
   return {
     passed: target.passed + source.passed,
     failed: target.failed + source.failed,
     warnings: target.warnings + source.warnings,
-    errors: target.errors + source.errors
+    errors: target.errors + source.errors,
+    rulesEvaluated: target.rulesEvaluated + source.rulesEvaluated
   };
 }
 function sessionDiagnostic(code, message) {
@@ -3261,6 +3262,7 @@ function aggregateSessionCheckResults(perRun, scope) {
           `${scope.scopeKind} not found: ${scope.scopeLabel}`
         )
       ],
+      ruleExecutions: [],
       ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
     };
   }
@@ -3281,17 +3283,20 @@ function aggregateSessionCheckResults(perRun, scope) {
           `No readable traces in ${scope.scopeKind}: ${scope.scopeLabel}`
         )
       ],
+      ruleExecutions: [],
       ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
     };
   }
   let summary = emptySummary();
   const findings = [];
   const diagnostics = [];
+  const ruleExecutions = [];
   const runResults = [];
   for (const result of perRun) {
     summary = mergeSummary(summary, result.summary);
     findings.push(...result.findings);
     diagnostics.push(...result.diagnostics);
+    ruleExecutions.push(...result.ruleExecutions ?? []);
     if (result.runId) {
       runResults.push({ runId: result.runId, status: result.status });
     }
@@ -3304,6 +3309,11 @@ function aggregateSessionCheckResults(perRun, scope) {
     if (runCmp !== 0) return runCmp;
     return a.ruleId.localeCompare(b.ruleId);
   });
+  ruleExecutions.sort((a, b) => {
+    const runCmp = (a.runId ?? "").localeCompare(b.runId ?? "");
+    if (runCmp !== 0) return runCmp;
+    return a.ruleId.localeCompare(b.ruleId);
+  });
   const hasErrors = diagnostics.some((item) => item.severity === "error");
   const status = hasErrors ? "error" : summary.failed > 0 ? "fail" : "pass";
   return {
@@ -3317,6 +3327,7 @@ function aggregateSessionCheckResults(perRun, scope) {
     summary,
     findings,
     diagnostics,
+    ruleExecutions,
     ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
   };
 }
@@ -6401,10 +6412,11 @@ function emptySummary2() {
     passed: 0,
     failed: 0,
     warnings: 0,
-    errors: 0
+    errors: 0,
+    rulesEvaluated: 0
   };
 }
-function errorResult(input, diagnostics, selectedRun) {
+function errorResult(input, diagnostics, selectedRun, ruleExecutions = []) {
   return {
     ok: false,
     status: "error",
@@ -6412,10 +6424,12 @@ function errorResult(input, diagnostics, selectedRun) {
     ...selectedRun ? { runId: selectedRun.runId } : {},
     summary: {
       ...emptySummary2(),
-      errors: diagnostics.filter((item) => item.severity === "error").length
+      errors: diagnostics.filter((item) => item.severity === "error").length,
+      rulesEvaluated: ruleExecutions.length
     },
     findings: [],
-    diagnostics: [...diagnostics]
+    diagnostics: [...diagnostics],
+    ruleExecutions: [...ruleExecutions]
   };
 }
 function flattenNodes(nodes) {
@@ -6571,7 +6585,7 @@ function normalizeFinding(rule, finding) {
     ...finding.action !== void 0 ? { action: finding.action } : {}
   };
 }
-function summarize(findings, diagnostics) {
+function summarize(findings, diagnostics, rulesEvaluated) {
   return {
     passed: findings.filter((finding) => finding.status === "pass").length,
     failed: findings.filter(
@@ -6580,9 +6594,21 @@ function summarize(findings, diagnostics) {
     warnings: findings.filter(
       (finding) => finding.status === "warning" || finding.severity === "warning"
     ).length,
-    errors: diagnostics.filter((item) => item.severity === "error").length
+    errors: diagnostics.filter((item) => item.severity === "error").length,
+    rulesEvaluated
   };
 }
+function classifyRuleExecution(findings, threw) {
+  if (findings.some((finding) => finding.status === "fail" && finding.severity === "error")) {
+    return "fail";
+  }
+  if (findings.some(
+    (finding) => finding.status === "warning" || finding.severity === "warning"
+  )) {
+    return "warning";
+  }
+  return "pass";
+}
 function stringAttr(event, keys) {
   for (const key of keys) {
     const value = event.attributes?.[key];
@@ -6679,6 +6705,9 @@ function finishedEvents(context, kind) {
     (event) => (kind === void 0 || event.kind === kind) && event.status !== "running"
   );
 }
+function toolInvocationEvents(context) {
+  return semanticEvents(context).filter((event) => event.kind === "TOOL");
+}
 function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -7079,7 +7108,7 @@ function createToolUsageRule(options) {
     category: "tool",
     defaultSeverity: "error",
     evaluate(context) {
-      const tools = finishedEvents(context, "TOOL");
+      const tools = toolInvocationEvents(context);
       const names = tools.map(toolName);
       const nameSet = new Set(names);
       const findings = [];
@@ -7729,12 +7758,24 @@ function createBaselineRegressionRule(options) {
 }
 function createObservedOutcomeRule(options = {}) {
   const failOn = options.failOn ?? ["failed"];
+  const requireAny = options.requireAny === true;
   return {
     id: "outcome.status",
     category: "run",
     defaultSeverity: "error",
     evaluate(context) {
       const outcomes = extractOutcomesFromPersistedEvents(context.events);
+      if (requireAny && outcomes.length === 0) {
+        return [
+          failFinding(
+            "outcome.status",
+            "Expected at least one observed outcome.",
+            runEvidence(context.selectedRun),
+            { requireAny: true, expected: "at least one observed outcome" },
+            { code: "outcome.missing", actual: 0 }
+          )
+        ];
+      }
       const matching = outcomesMatchingStatus(outcomes, failOn);
       if (matching.length === 0) return [];
       return [
@@ -7770,6 +7811,18 @@ function runTraceChecks(input, options = {}) {
   if (rules.diagnostics.length > 0) {
     return errorResult(input, rules.diagnostics, selected.run);
   }
+  if (rules.rules.length === 0) {
+    return errorResult(
+      input,
+      [
+        diagnostic3(
+          "AI_CHECK_NO_RULES_EVALUATED",
+          "No trace check rules were evaluated. Configure at least one rule, contract, or CLI check option."
+        )
+      ],
+      selected.run
+    );
+  }
   const facts = buildFacts2(input, selected.run);
   const context = {
     ...facts,
@@ -7778,22 +7831,38 @@ function runTraceChecks(input, options = {}) {
   };
   const diagnostics = [];
   const findings = [];
+  const ruleExecutions = [];
   for (const rule of rules.rules) {
     try {
-      findings.push(...rule.evaluate(context).map((finding) => normalizeFinding(rule, finding)));
+      const ruleFindings = rule.evaluate(context).map((finding) => normalizeFinding(rule, finding));
+      findings.push(...ruleFindings);
+      ruleExecutions.push({
+        ruleId: rule.id,
+        category: rule.category,
+        status: classifyRuleExecution(ruleFindings, false),
+        findingCount: ruleFindings.length,
+        ...selected.run ? { runId: selected.run.runId } : {}
+      });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       diagnostics.push(
         diagnostic3("AI_CHECK_INTERNAL_ERROR", `Rule ${rule.id} failed: ${message}`, rule.id)
       );
+      ruleExecutions.push({
+        ruleId: rule.id,
+        category: rule.category,
+        status: "error",
+        findingCount: 0,
+        ...selected.run ? { runId: selected.run.runId } : {}
+      });
     }
   }
   if (diagnostics.length > 0) {
-    return errorResult(input, diagnostics, selected.run);
+    return errorResult(input, diagnostics, selected.run, ruleExecutions);
   }
   const eventById = new Map(input.read.events.map((event) => [event.eventId, event]));
   const sortedFindings = findings.sort(compareFindings(eventById));
-  const summary = summarize(sortedFindings, diagnostics);
+  const summary = summarize(sortedFindings, diagnostics, ruleExecutions.length);
   const status = summary.failed > 0 ? "fail" : "pass";
   return {
     ok: status === "pass",
@@ -7802,7 +7871,8 @@ function runTraceChecks(input, options = {}) {
     ...selected.run ? { runId: selected.run.runId } : {},
     summary,
     findings: sortedFindings,
-    diagnostics
+    diagnostics,
+    ruleExecutions
   };
 }
 
@@ -10166,8 +10236,7 @@ async function runSuiteCase(suiteCase, config, options) {
     status: "pass",
     format: read.format,
     findings: [],
-    diagnostics: []
-  };
+    diagnostics: []};
   const observationResult = validateExpectedObservations(suiteCase, read);
   const diagnostics = [
     ...checkResult.diagnostics.map(
@@ -11346,5 +11415,5 @@ function renderGateReport(result, options = {}) {
 }
 
 export { COHORT_METRIC_IDS, DEFAULT_SUITE_ARTIFACTS_DIR, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, Redactor, TraceDirectory, TraceReadError, TreeBuilder, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, applyProfileMetadataCaps, assertBundlePathContained, assertEvidenceRelativePath, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceHtmlShell, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectTraceSchemaVersions, compactAttributes, createBaselineRegressionRule, createLlmUsageRule, createMaxStepDurationRule, createObservedOutcomeRule, createRequireCompletedRule, createRunDepthRule, createRunDurationRule, createRunStatusRule, createSafetyOversizedAttributeRule, createSafetyRawContentRule, createSafetyRedactionRule, createSafetySecretPatternRule, createStallDetectionRule, createStructureCycleRule, createStructureOrphanRule, createStructureParallelWidthRule, createStructureRelationshipRule, createToolUsageRule, defaultBundleOutputPath, defaultSuiteConfigTemplate, diffRuns, diffTraceEvents, enrichSessionRunRecord, escapeHtml, escapeMarkdown, extractMetadata, extractOutcomesFromTraceEvents, filterMetasBySessionScope, filterTraces, flattenTree, formatDuration2 as formatDuration, formatStepLabel, formatTimestamp, gateHasThresholds, getIndent, getTraceFilePath, inferEvidenceFileRole, isAgentInspectTrace, isPersistedInspectEvent, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, manualTraceEventsToComparableRun, nanoid, normalizeBundleOutputPath, openTrace, parseCohortMetricList, parseDuration, parseDurationFilter, parseGateList, parseTraceJsonl, persistedInspectEventsToTraceEvents, renderActivitySummaryHuman, renderCohortReport, renderErrorLine, renderGateReport, renderObservedOutcomesHtml, renderObservedOutcomesMarkdown, renderRunDiff, renderRunWhat, renderStepLine, renderSuiteReport, renderTimeline, renderTraceStats, resolveBundleRunIds, resolveRedactionProfile, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, runTraceChecks, safeString, sanitizeBundleRunId, searchTraces, serializeEvidenceManifest, sha256Hex, stableJson, summarizeObservedOutcomes, summarizeSemanticParity, traceEventToPersistedInspectEvent, truncateName, truncateStringForProfile, validateEvent, validateSuiteConfig, verifyEvidenceDirectory, zeroKinds };
-//# sourceMappingURL=chunk-YX6RFLV5.mjs.map
-//# sourceMappingURL=chunk-YX6RFLV5.mjs.map
+//# sourceMappingURL=chunk-GOHYSE7W.mjs.map
+//# sourceMappingURL=chunk-GOHYSE7W.mjs.map