@agent-inspect/jest 6.19.1 → 6.20.0

package/dist/index.d.cts

@@ -182,7 +182,8 @@ interface TraceContractToolRules {
     /**
      * Unconditional tool presence invariant. Every named tool must appear at least
      * once. Do not use for cache-hit or alternate-path shortcuts — prefer
-     * `observations.required` until `alternatives.anyOf` ships (planned 6.20.0).
+     * `alternatives.anyOf` or `observations.required` when a legitimate path may
+     * skip the tool.
      *
      * @see docs/TRACE-CONTRACTS.md
      */
@@ -195,25 +196,34 @@ interface TraceContractToolRules {
     allowed?: string[];
     maxCalls?: number;
     /**
-     * Required tool order as adjacent first-occurrence pairs (start/encounter order).
+     * Required tool order expanded into adjacent pairs.
      *
      * `[A, B, C]` expands to “A before B” and “B before C”, each comparing the
-     * first occurrence of the named tool. Unlisted intermediate tools are
-     * allowed. Later repetitions do not invalidate an earlier valid order.
+     * selected `requiredOrderMode` to every pair. Unlisted intermediate tools
+     * are allowed.
      *
      * TraceContract `requiredOrder` **implies presence**: every listed name is
      * added to the effective required-tool set. Low-level `createToolOrderingRule`
      * alone may still pass vacuously when an endpoint is missing.
      *
-     * This is **not** causal happens-before. Overlapping intervals emit a
-     * non-failing overlap warning. Planned modes (6.20.0, GitHub #308):
-     * `happens-before`, `all-occurrences`.
+     * The default `first-occurrence` mode preserves first-occurrence encounter
+     * ordering; overlapping intervals emit a non-failing warning. `happens-before`
+     * requires the first before event to finish before the first after event starts.
+     * `all-occurrences` applies that causal boundary to every occurrence.
      *
      * @see docs/TRACE-CONTRACTS.md
      * @beta Available through `agent-inspect/checks`. Additive changes may ship
      * in minor releases; breaking changes require a future major.
      */
     requiredOrder?: string[];
+    /**
+     * Ordering semantics applied to every adjacent pair in `requiredOrder`.
+     * Causal modes fail closed when a required interval boundary is unavailable.
+     *
+     * @defaultValue `"first-occurrence"`
+     * @beta Available through `agent-inspect/checks`.
+     */
+    requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
@@ -224,11 +234,40 @@ interface TraceContractObservationRules {
     required?: string[];
     failOn?: Array<"failed" | "unknown" | "skipped">;
 }
-interface TraceContractInput {
+/**
+ * One deterministic alternate path. Branch contracts are one level only —
+ * nested `alternatives` are rejected.
+ *
+ * @experimental
+ */
+interface TraceContractAlternativeBranch {
+    /** Unique branch id within `alternatives.anyOf`. */
+    id: string;
+    description?: string;
+    /** Branch body: run/tools/llm/observations only (no nested alternatives). */
+    contract: TraceContractBody;
+}
+/**
+ * Bounded alternative valid paths for legitimate shortcuts (GitHub #309).
+ *
+ * @experimental
+ */
+interface TraceContractAlternatives {
+    /**
+     * One level of named branches. The overall contract passes when the base
+     * rules pass and **at least one** complete branch passes.
+     */
+    anyOf: TraceContractAlternativeBranch[];
+}
+/** Contract body without alternatives (base or branch). */
+type TraceContractBody = {
     run?: TraceContractRunRules;
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+};
+interface TraceContractInput extends TraceContractBody {
+    alternatives?: TraceContractAlternatives;
 }
 
 /**

package/dist/index.d.ts

@@ -182,7 +182,8 @@ interface TraceContractToolRules {
     /**
      * Unconditional tool presence invariant. Every named tool must appear at least
      * once. Do not use for cache-hit or alternate-path shortcuts — prefer
-     * `observations.required` until `alternatives.anyOf` ships (planned 6.20.0).
+     * `alternatives.anyOf` or `observations.required` when a legitimate path may
+     * skip the tool.
      *
      * @see docs/TRACE-CONTRACTS.md
      */
@@ -195,25 +196,34 @@ interface TraceContractToolRules {
     allowed?: string[];
     maxCalls?: number;
     /**
-     * Required tool order as adjacent first-occurrence pairs (start/encounter order).
+     * Required tool order expanded into adjacent pairs.
      *
      * `[A, B, C]` expands to “A before B” and “B before C”, each comparing the
-     * first occurrence of the named tool. Unlisted intermediate tools are
-     * allowed. Later repetitions do not invalidate an earlier valid order.
+     * selected `requiredOrderMode` to every pair. Unlisted intermediate tools
+     * are allowed.
      *
      * TraceContract `requiredOrder` **implies presence**: every listed name is
      * added to the effective required-tool set. Low-level `createToolOrderingRule`
      * alone may still pass vacuously when an endpoint is missing.
      *
-     * This is **not** causal happens-before. Overlapping intervals emit a
-     * non-failing overlap warning. Planned modes (6.20.0, GitHub #308):
-     * `happens-before`, `all-occurrences`.
+     * The default `first-occurrence` mode preserves first-occurrence encounter
+     * ordering; overlapping intervals emit a non-failing warning. `happens-before`
+     * requires the first before event to finish before the first after event starts.
+     * `all-occurrences` applies that causal boundary to every occurrence.
      *
      * @see docs/TRACE-CONTRACTS.md
      * @beta Available through `agent-inspect/checks`. Additive changes may ship
      * in minor releases; breaking changes require a future major.
      */
     requiredOrder?: string[];
+    /**
+     * Ordering semantics applied to every adjacent pair in `requiredOrder`.
+     * Causal modes fail closed when a required interval boundary is unavailable.
+     *
+     * @defaultValue `"first-occurrence"`
+     * @beta Available through `agent-inspect/checks`.
+     */
+    requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
@@ -224,11 +234,40 @@ interface TraceContractObservationRules {
     required?: string[];
     failOn?: Array<"failed" | "unknown" | "skipped">;
 }
-interface TraceContractInput {
+/**
+ * One deterministic alternate path. Branch contracts are one level only —
+ * nested `alternatives` are rejected.
+ *
+ * @experimental
+ */
+interface TraceContractAlternativeBranch {
+    /** Unique branch id within `alternatives.anyOf`. */
+    id: string;
+    description?: string;
+    /** Branch body: run/tools/llm/observations only (no nested alternatives). */
+    contract: TraceContractBody;
+}
+/**
+ * Bounded alternative valid paths for legitimate shortcuts (GitHub #309).
+ *
+ * @experimental
+ */
+interface TraceContractAlternatives {
+    /**
+     * One level of named branches. The overall contract passes when the base
+     * rules pass and **at least one** complete branch passes.
+     */
+    anyOf: TraceContractAlternativeBranch[];
+}
+/** Contract body without alternatives (base or branch). */
+type TraceContractBody = {
     run?: TraceContractRunRules;
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+};
+interface TraceContractInput extends TraceContractBody {
+    alternatives?: TraceContractAlternatives;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-inspect/jest",
-  "version": "6.19.1",
+  "version": "6.20.0",
   "license": "MIT",
   "type": "module",
   "description": "Jest reporter and experimental TraceContract matchers for AgentInspect local evidence",
@@ -42,7 +42,7 @@
     }
   },
   "dependencies": {
-    "agent-inspect": "6.19.1"
+    "agent-inspect": "6.20.0"
   },
   "devDependencies": {
     "jest": "^30.2.0"