@agent-inspect/vitest 6.19.1 → 6.21.0

package/dist/index.d.cts

@@ -170,6 +170,24 @@ interface TraceReadResult {
     sourceFiles: string[];
 }
 
+/**
+ * Explicit actor/run projection for TraceContract evaluation (#320).
+ *
+ * Selectors use only declared metadata (or explicit event ids). Zero matches
+ * and singular-actor ambiguity fail closed. No timestamp or display-name
+ * inference.
+ *
+ * @experimental
+ */
+interface TraceContractScope {
+    runId?: string;
+    subAgentId?: string;
+    groupId?: string;
+    workflowStep?: string;
+    /** Explicit root event id; evaluation projects to that event and descendants. */
+    rootEventId?: string;
+}
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -182,7 +200,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,40 +214,110 @@ 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;
     maxTotalTokens?: number;
     allowedModels?: string[];
 }
+/**
+ * Structural provenance requirements for named observed outcomes (#321).
+ *
+ * These checks prove method/evidence linkage was recorded. They do **not**
+ * prove the claim is semantically true, authorized, complete, or externally
+ * trusted.
+ *
+ * @experimental
+ */
+interface TraceContractObservationProvenance {
+    /** Require a non-empty method from the bounded ObservedOutcomeMethod vocabulary. */
+    method?: boolean;
+    /**
+     * Require bounded evidence references. Supported shapes:
+     * `string` event id, `{ eventId }`, or `{ eventIds: string[] }` (max 16 ids).
+     */
+    evidence?: boolean;
+    /** When true with evidence, each referenced event id must exist in the same run. */
+    sameRunEventReference?: boolean;
+}
 interface TraceContractObservationRules {
     required?: string[];
     failOn?: Array<"failed" | "unknown" | "skipped">;
+    /**
+     * Structural provenance gates for `required` observation names.
+     *
+     * @experimental
+     */
+    requireProvenance?: TraceContractObservationProvenance;
+}
+/**
+ * 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[];
 }
-interface TraceContractInput {
+/** Contract body without alternatives (base or branch). */
+type TraceContractBody = {
     run?: TraceContractRunRules;
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+};
+interface TraceContractInput extends TraceContractBody {
+    /**
+     * Optional actor/run projection applied before evaluation (#320).
+     *
+     * @experimental
+     */
+    scope?: TraceContractScope;
+    alternatives?: TraceContractAlternatives;
 }
 
 /**

package/dist/index.d.ts

@@ -170,6 +170,24 @@ interface TraceReadResult {
     sourceFiles: string[];
 }
 
+/**
+ * Explicit actor/run projection for TraceContract evaluation (#320).
+ *
+ * Selectors use only declared metadata (or explicit event ids). Zero matches
+ * and singular-actor ambiguity fail closed. No timestamp or display-name
+ * inference.
+ *
+ * @experimental
+ */
+interface TraceContractScope {
+    runId?: string;
+    subAgentId?: string;
+    groupId?: string;
+    workflowStep?: string;
+    /** Explicit root event id; evaluation projects to that event and descendants. */
+    rootEventId?: string;
+}
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -182,7 +200,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,40 +214,110 @@ 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;
     maxTotalTokens?: number;
     allowedModels?: string[];
 }
+/**
+ * Structural provenance requirements for named observed outcomes (#321).
+ *
+ * These checks prove method/evidence linkage was recorded. They do **not**
+ * prove the claim is semantically true, authorized, complete, or externally
+ * trusted.
+ *
+ * @experimental
+ */
+interface TraceContractObservationProvenance {
+    /** Require a non-empty method from the bounded ObservedOutcomeMethod vocabulary. */
+    method?: boolean;
+    /**
+     * Require bounded evidence references. Supported shapes:
+     * `string` event id, `{ eventId }`, or `{ eventIds: string[] }` (max 16 ids).
+     */
+    evidence?: boolean;
+    /** When true with evidence, each referenced event id must exist in the same run. */
+    sameRunEventReference?: boolean;
+}
 interface TraceContractObservationRules {
     required?: string[];
     failOn?: Array<"failed" | "unknown" | "skipped">;
+    /**
+     * Structural provenance gates for `required` observation names.
+     *
+     * @experimental
+     */
+    requireProvenance?: TraceContractObservationProvenance;
+}
+/**
+ * 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[];
 }
-interface TraceContractInput {
+/** Contract body without alternatives (base or branch). */
+type TraceContractBody = {
     run?: TraceContractRunRules;
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+};
+interface TraceContractInput extends TraceContractBody {
+    /**
+     * Optional actor/run projection applied before evaluation (#320).
+     *
+     * @experimental
+     */
+    scope?: TraceContractScope;
+    alternatives?: TraceContractAlternatives;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-inspect/vitest",
-  "version": "6.19.1",
+  "version": "6.21.0",
   "license": "MIT",
   "type": "module",
   "description": "Vitest reporter and experimental TraceContract matchers for AgentInspect local evidence",
@@ -37,7 +37,7 @@
     "vitest": "^2.1.0 || ^3.2.6"
   },
   "dependencies": {
-    "agent-inspect": "6.19.1"
+    "agent-inspect": "6.21.0"
   },
   "devDependencies": {
     "vitest": "^3.2.7"