agent-inspect 6.17.3 → 6.17.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- c4b0f03: Fix camelCase / kebab / dot compound credential key redaction (`userPassword`, `clientSecret`) while keeping token-config keys and camelCase topic fields (`emailNote`) un-key-redacted.
+
 ## 6.17.3
 
 ### 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.2** · 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/ADAPTER-CONFORMANCE.md

@@ -58,6 +58,30 @@ This is an internal official-adapter gate, not a third-party certification progr
 
 An adapter can be documented as supported only after no-network fixtures cover run, step, tool, LLM, error, streaming, and metadata-bound expectations for that framework path.
 
+## Third-party adapter conformance CI
+
+The gate above is the internal official-adapter gate, not a third-party certification program. Third-party adapter authors run the **public** conformance helper from [`@agent-inspect/adapter-sdk`](https://www.npmjs.com/package/@agent-inspect/adapter-sdk) in their own CI:
+
+```ts
+import { runAdapterConformance } from "@agent-inspect/adapter-sdk";
+
+const result = await runAdapterConformance({
+  adapterId: "my-adapter",
+  events, // PersistedInspectEvent[] your adapter emits
+  expectedKinds: ["RUN", "LLM"],
+  forbiddenRawStrings: ["super-secret-key"], // must not leak into events
+});
+// assert result.ok in your test runner
+```
+
+A copyable GitHub Actions template lives at [`examples/adapter-sdk/third-party-conformance-ci.yml`](../examples/adapter-sdk/third-party-conformance-ci.yml). Copy it to `.github/workflows/agent-inspect-conformance.yml` in your adapter repo and adjust the install/build/test commands. The template:
+
+- runs on a Node LTS matrix (18 / 20 / 22),
+- requires **no provider keys** and makes **no network calls** (conformance is metadata-only),
+- keeps the framework SDK as a peer dependency of your adapter, never of AgentInspect core.
+
+See the runnable examples under [`examples/adapter-sdk/`](../examples/adapter-sdk/) for adapters that call `runAdapterConformance` end to end.
+
 ## v3.2 adoption evidence refresh
 
 - [AI-SDK-ADOPTION.md](./AI-SDK-ADOPTION.md) — blessed AI SDK path (`generateText`, `streamText`, Next.js recipe, troubleshooting)

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/CI-ARTIFACTS.md

@@ -86,8 +86,9 @@ Recipes:
 
 - [examples/recipes/deterministic-ci-checks](../examples/recipes/deterministic-ci-checks/README.md) for v1.8 `check`, baseline, safe artifact, and step-summary workflows.
 - [examples/recipes/github-actions-artifact](../examples/recipes/github-actions-artifact/README.md) for share-safe trace exports and reporter manifest summaries.
+- [examples/recipes/github-actions-gate](../examples/recipes/github-actions-gate/README.md) for a retained broken-to-fixed suite/gate pilot with separate Evidence v2 artifacts.
 
-Sample workflows: [deterministic checks workflow](../examples/recipes/deterministic-ci-checks/workflow-example.yml), [share-safe export workflow](../examples/recipes/github-actions-artifact/workflow-example.yml)
+Sample workflows: [deterministic checks workflow](../examples/recipes/deterministic-ci-checks/workflow-example.yml), [share-safe export workflow](../examples/recipes/github-actions-artifact/workflow-example.yml), [retained gate workflow](../examples/recipes/github-actions-gate/workflow-example.yml)
 
 ```yaml
 - uses: actions/upload-artifact@v4

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/OPENAI-AGENTS-LOCAL.md

@@ -41,6 +41,20 @@ setTraceProcessors([
 
 - [openai-agents-local-processor](../../examples/recipes/openai-agents-local-processor/)
 
+## No-key packed consumer check
+
+The repository includes a packed-consumer check that installs the root and
+OpenAI Agents adapter tarballs into a temporary project. It drives deterministic
+tracing fixtures without `OPENAI_API_KEY` or a live provider call, writes a local
+trace, and inspects it through the packed AgentInspect CLI.
+
+```bash
+pnpm build
+node scripts/packed-openai-agents-e2e.mjs
+```
+
+The check is also included in `pnpm pack:smoke`.
+
 ## Troubleshooting
 
 | Symptom | Check |

package/docs/SAFE-TRACE-SHARING.md

@@ -36,6 +36,7 @@ When a maintainer or support responder needs reproducible evidence, follow the [
 - Inspect manual metadata passed to `inspectRun()`, `step()`, `step.tool()`, `step.llm()`, or `observe()`.
 - Inspect log-derived fields from `logs` / `tail` ingest configs, including custom `run-id`, `event`, `parent`, timestamp, and attribute mappings.
 - Avoid posting raw prompts, completions, tool inputs, or tool outputs in public threads unless the content is approved for public disclosure.
+- For cross-system correlation, retain a bounded identifier instead of copying the external record or payload. Follow [External reference metadata](./EXTERNAL-REFERENCES.md), and expect `share` / `strict` profiles to redact the named correlation fields.
 - Prefer Markdown export for issue or PR sharing when a summarized tree is enough.
 
 ## Remove or replace sensitive values

package/docs/SELF-HOSTING.md

@@ -125,6 +125,8 @@ Postgres URLs are reserved for team deployments and are **not required** for loc
 
 ## Related docs
 
+- [STUDIO-IMPORT-BUNDLE.md](./STUDIO-IMPORT-BUNDLE.md) — walkthrough: share-safe bundle → local Studio
+- [STUDIO-IMPORT-GITHUB-ARTIFACT.md](./STUDIO-IMPORT-GITHUB-ARTIFACT.md) — walkthrough: GitHub Actions artifact → local Studio
 - [SELF-HOSTED-STUDIO-V6.0.md](./proposals/SELF-HOSTED-STUDIO-V6.0.md)
 - [CLIENT-HOSTED-INGESTION-V6.1.md](./proposals/CLIENT-HOSTED-INGESTION-V6.1.md)
 - [LOCAL-TRACE-WORKSPACE.md](./proposals/LOCAL-TRACE-WORKSPACE.md)

package/docs/STANDARDS.md

@@ -21,6 +21,8 @@ Shape validation is **compatible**; semantic checks add field-level warnings for
 
 Fixture: [fixtures/standards/openinference-basic.json](../fixtures/standards/openinference-basic.json)
 
+The fixture's top-level `version` is an **AgentInspect reference fixture revision**, not an upstream OpenInference version.
+
 ## OTLP JSON (experimental)
 
 ```bash
@@ -31,10 +33,23 @@ GenAI attribute mapping follows `OTEL_GEN_AI_SEMCONV_PIN` (see exporters API). N
 
 Fixture: [fixtures/standards/otlp-basic.json](../fixtures/standards/otlp-basic.json)
 
+The fixture's `scope.version` is an **AgentInspect test-scope fixture revision**, not the `OTEL_GEN_AI_SEMCONV_PIN` and not an upstream OpenTelemetry version.
+
 ## Graduation guide
 
 Full path from local export through review to optional customer-owned import: [STANDARDS-GRADUATION.md](./STANDARDS-GRADUATION.md).
 
+That guide is the canonical source for standards known-loss boundaries, including kind degradation, bounded metadata, no chain-of-thought capture, and snapshot limitations.
+
+## Maintaining tested provenance
+
+- When the OTLP mapping changes, update `OTEL_GEN_AI_SEMCONV_PIN` in [`packages/core/src/exporters/semconv.ts`](../packages/core/src/exporters/semconv.ts) and any explicit tested-version claims together.
+- When the OTLP reference shape changes, update its test-scope fixture revision in [`fixtures/standards/otlp-basic.json`](../fixtures/standards/otlp-basic.json) and any repeated fixture revision together.
+- When the OpenInference reference shape changes, update the top-level fixture revision in [`fixtures/standards/openinference-basic.json`](../fixtures/standards/openinference-basic.json) and any repeated fixture revision together. The value remains an AgentInspect fixture revision, not an upstream version.
+- Keep known-loss behavior canonical in [`STANDARDS-GRADUATION.md`](./STANDARDS-GRADUATION.md) and update its validation alongside any intentional exporter behavior change.
+
+Run `pnpm public-truth:check` and `pnpm docs:check` after changing these sources.
+
 ## Import recipes
 
 - [Phoenix / OpenInference](../examples/recipes/phoenix-openinference-import/)

package/docs/SUPPORT-LEVELS.md

@@ -37,6 +37,29 @@ Canonical maturity labels for AgentInspect public packages and major surfaces (6
 
 Part of the fixed AgentInspect release line — see the npm badge for the current version.
 
+> Every level in this matrix must be one of the Definitions levels above, and `docs/product/PUBLIC-PRODUCT-FACTS.json` `matchers.status` must match the matchers row here. `pnpm public-truth:check` enforces both; update the doc and the facts file together.
+
+## Changing a level
+
+A level is stated in two places, and they must not disagree: the row above, and
+the `**Support level:**` line in the package's own README (which is what npm
+shows). `pnpm package-readmes:check` enforces the agreement and runs as part of
+`pnpm docs:check`.
+
+To promote or demote a surface:
+
+1. Edit the row in the matrix above.
+2. Edit the `**Support level:**` line in each affected `packages/*/README.md`.
+3. Run `pnpm package-readmes:check`.
+
+The check also reports packages whose level is **unenforced** — those the matrix
+above does not name, so the README is their only source. Adding a row that names
+the package (in backticks) puts it under enforcement.
+
+It rejects an absolute "no network" claim from any surface
+[NETWORK-BEHAVIOR.md](./NETWORK-BEHAVIOR.md) records as making network calls, so
+a promotion that changes network behavior cannot leave a stale guarantee on npm.
+
 ## Public package groups (presentation only)
 
 Physical packages stay the fixed group of 18. Outreach/install kits group them as:

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.3",
+  "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",
@@ -235,13 +235,16 @@
     "test:all": "pnpm run typecheck && pnpm run linked-versions:check && pnpm run build && pnpm run test && pnpm run size",
     "prepublish:checks": "pnpm run typecheck && pnpm run test && pnpm run test:coverage && pnpm run build && pnpm run fixtures:check && pnpm run recipes:check && pnpm run size && pnpm run linked-versions:check && pnpm run repo:health && pnpm run pack:smoke",
     "pack:dry-run": "pnpm run build && npm pack --dry-run",
-    "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-quickstart-e2e.mjs && node scripts/packed-semantic-loop-e2e.mjs && node scripts/packed-swarm-loop-e2e.mjs && node scripts/evidence-ci-golden-paths.mjs",
+    "pack:smoke": "pnpm run build && node scripts/package-smoke.mjs && node scripts/packed-openai-agents-e2e.mjs && node scripts/packed-quickstart-e2e.mjs && node scripts/packed-semantic-loop-e2e.mjs && node scripts/packed-swarm-loop-e2e.mjs && node scripts/evidence-ci-golden-paths.mjs",
     "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",
-    "docs:check": "pnpm run docs:commands && pnpm run docs:links && pnpm run public-truth:check && pnpm run ai-assets:check && pnpm run repo:health && pnpm run demo:verify",
+    "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 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",
@@ -251,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",