@agent-inspect/jest 6.22.0 → 6.23.0

package/dist/index.d.cts

@@ -188,6 +188,108 @@ interface TraceContractScope {
     rootEventId?: string;
 }
 
+/**
+ * Declared-versus-enforced control checks for TraceContract (6.23).
+ *
+ * A stored declaration is not proof of enforcement.
+ *
+ * @experimental
+ */
+
+type ControlStage = "declared" | "presented" | "validated" | "enforced" | "observed" | "accepted";
+interface TraceContractControlRules {
+    /**
+     * Tools declared/presented to the agent (inline). Distinct from `enforcedTools`.
+     */
+    declaredTools?: string[];
+    /**
+     * Tools the harness claims to enforce (inline allowlist).
+     */
+    enforcedTools?: string[];
+    /**
+     * RUN/event attribute holding a string[] of declared tool names.
+     * Used when `declaredTools` is omitted.
+     */
+    declaredToolsAttribute?: string;
+    /**
+     * RUN/event attribute holding a string[] of enforced tool names.
+     */
+    enforcedToolsAttribute?: string;
+    /**
+     * Fail when both declared and enforced sets resolve and differ.
+     */
+    requireDeclaredMatchesEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the enforced set.
+     */
+    requireObservedWithinEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the declared set.
+     */
+    requireObservedWithinDeclared?: boolean;
+    /**
+     * Require observation names for control stages (default `control.<stage>`).
+     */
+    requiredStages?: Array<{
+        stage: ControlStage;
+        /** Observation name; defaults to `control.<stage>`. */
+        observation?: string;
+    }>;
+}
+
+/**
+ * Retry / side-effect safety checks for TraceContract (6.23).
+ *
+ * Uses explicit attempt identity from session workflow metadata.
+ * AgentInspect evaluates; it does not perform retries.
+ *
+ * @experimental
+ */
+
+interface TraceContractRetryRules {
+    /**
+     * Maximum attempts per `operationId` (or `attemptOf` grouping).
+     * Counts distinct `attemptId` values when present, else finished tool/LLM events.
+     */
+    maxAttempts?: number;
+    /**
+     * When true, every operation with attempts must include a non-running terminal event.
+     */
+    requireTerminalResult?: boolean;
+    /**
+     * Fail when `fallbackOf` is set without a prior error attempt for the referenced operation.
+     */
+    fallbackOnlyAfterFailure?: boolean;
+    /**
+     * Tool names treated as non-idempotent. A later attempt after an `ok` occurrence fails
+     * unless idempotency / no-side-effect evidence is present on the retry.
+     */
+    nonIdempotentTools?: string[];
+    /**
+     * When true, retries require `idempotencyKey` or `attributes.noSideEffect === true`.
+     */
+    requireIdempotencyEvidenceForRetry?: boolean;
+    /**
+     * When true, recovered success paths must still retain at least one error attempt event.
+     */
+    requireRecoveredFailureVisible?: boolean;
+}
+
+type ToolArgumentOperator = "exists" | "type" | "equals" | "oneOf";
+type ToolArgumentOccurrence = "first" | "last" | "any" | "all";
+interface ToolArgumentCheck {
+    tool: string;
+    path: string;
+    operator: ToolArgumentOperator;
+    occurrence?: ToolArgumentOccurrence;
+    /** Required for `equals`. */
+    expected?: unknown;
+    /** Required for `oneOf`. */
+    oneOf?: readonly unknown[];
+    /** Required for `type` (`string` | `number` | `boolean` | `object` | `array` | `null`). */
+    type?: "string" | "number" | "boolean" | "object" | "array" | "null";
+}
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -242,6 +344,32 @@ interface TraceContractToolRules {
      * @beta Available through `agent-inspect/checks`.
      */
     requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Bounded structured tool-argument checks (JSON Pointer + limited operators).
+     *
+     * Missing structured evidence fails closed as unevaluable (not pass).
+     * Findings never embed full actual inputs.
+     *
+     * @experimental Additive in 6.23.
+     */
+    arguments?: ToolArgumentCheck[];
+    /**
+     * Default occurrence mode for `orderRules` when a rule omits `occurrenceMode`.
+     *
+     * @experimental Additive in 6.23.
+     */
+    defaultOccurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Mixed per-pair ordering rules (additive alongside `requiredOrder`).
+     *
+     * @experimental Additive in 6.23.
+     */
+    orderRules?: Array<{
+        before: string;
+        after: string;
+        occurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+        requireEndpoints?: boolean;
+    }>;
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
@@ -309,6 +437,18 @@ type TraceContractBody = {
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+    /**
+     * Declared-versus-enforced control invariants.
+     *
+     * @experimental Additive in 6.23.
+     */
+    controls?: TraceContractControlRules;
+    /**
+     * Retry / side-effect safety using explicit attempt identity.
+     *
+     * @experimental Additive in 6.23.
+     */
+    retry?: TraceContractRetryRules;
 };
 interface TraceContractInput extends TraceContractBody {
     /**

package/dist/index.d.ts

@@ -188,6 +188,108 @@ interface TraceContractScope {
     rootEventId?: string;
 }
 
+/**
+ * Declared-versus-enforced control checks for TraceContract (6.23).
+ *
+ * A stored declaration is not proof of enforcement.
+ *
+ * @experimental
+ */
+
+type ControlStage = "declared" | "presented" | "validated" | "enforced" | "observed" | "accepted";
+interface TraceContractControlRules {
+    /**
+     * Tools declared/presented to the agent (inline). Distinct from `enforcedTools`.
+     */
+    declaredTools?: string[];
+    /**
+     * Tools the harness claims to enforce (inline allowlist).
+     */
+    enforcedTools?: string[];
+    /**
+     * RUN/event attribute holding a string[] of declared tool names.
+     * Used when `declaredTools` is omitted.
+     */
+    declaredToolsAttribute?: string;
+    /**
+     * RUN/event attribute holding a string[] of enforced tool names.
+     */
+    enforcedToolsAttribute?: string;
+    /**
+     * Fail when both declared and enforced sets resolve and differ.
+     */
+    requireDeclaredMatchesEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the enforced set.
+     */
+    requireObservedWithinEnforced?: boolean;
+    /**
+     * Fail when any observed finished tool is outside the declared set.
+     */
+    requireObservedWithinDeclared?: boolean;
+    /**
+     * Require observation names for control stages (default `control.<stage>`).
+     */
+    requiredStages?: Array<{
+        stage: ControlStage;
+        /** Observation name; defaults to `control.<stage>`. */
+        observation?: string;
+    }>;
+}
+
+/**
+ * Retry / side-effect safety checks for TraceContract (6.23).
+ *
+ * Uses explicit attempt identity from session workflow metadata.
+ * AgentInspect evaluates; it does not perform retries.
+ *
+ * @experimental
+ */
+
+interface TraceContractRetryRules {
+    /**
+     * Maximum attempts per `operationId` (or `attemptOf` grouping).
+     * Counts distinct `attemptId` values when present, else finished tool/LLM events.
+     */
+    maxAttempts?: number;
+    /**
+     * When true, every operation with attempts must include a non-running terminal event.
+     */
+    requireTerminalResult?: boolean;
+    /**
+     * Fail when `fallbackOf` is set without a prior error attempt for the referenced operation.
+     */
+    fallbackOnlyAfterFailure?: boolean;
+    /**
+     * Tool names treated as non-idempotent. A later attempt after an `ok` occurrence fails
+     * unless idempotency / no-side-effect evidence is present on the retry.
+     */
+    nonIdempotentTools?: string[];
+    /**
+     * When true, retries require `idempotencyKey` or `attributes.noSideEffect === true`.
+     */
+    requireIdempotencyEvidenceForRetry?: boolean;
+    /**
+     * When true, recovered success paths must still retain at least one error attempt event.
+     */
+    requireRecoveredFailureVisible?: boolean;
+}
+
+type ToolArgumentOperator = "exists" | "type" | "equals" | "oneOf";
+type ToolArgumentOccurrence = "first" | "last" | "any" | "all";
+interface ToolArgumentCheck {
+    tool: string;
+    path: string;
+    operator: ToolArgumentOperator;
+    occurrence?: ToolArgumentOccurrence;
+    /** Required for `equals`. */
+    expected?: unknown;
+    /** Required for `oneOf`. */
+    oneOf?: readonly unknown[];
+    /** Required for `type` (`string` | `number` | `boolean` | `object` | `array` | `null`). */
+    type?: "string" | "number" | "boolean" | "object" | "array" | "null";
+}
+
 /**
  * @experimental Typed trace contract input. Evolves during v6.5.x.
  */
@@ -242,6 +344,32 @@ interface TraceContractToolRules {
      * @beta Available through `agent-inspect/checks`.
      */
     requiredOrderMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Bounded structured tool-argument checks (JSON Pointer + limited operators).
+     *
+     * Missing structured evidence fails closed as unevaluable (not pass).
+     * Findings never embed full actual inputs.
+     *
+     * @experimental Additive in 6.23.
+     */
+    arguments?: ToolArgumentCheck[];
+    /**
+     * Default occurrence mode for `orderRules` when a rule omits `occurrenceMode`.
+     *
+     * @experimental Additive in 6.23.
+     */
+    defaultOccurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+    /**
+     * Mixed per-pair ordering rules (additive alongside `requiredOrder`).
+     *
+     * @experimental Additive in 6.23.
+     */
+    orderRules?: Array<{
+        before: string;
+        after: string;
+        occurrenceMode?: "first-occurrence" | "happens-before" | "all-occurrences";
+        requireEndpoints?: boolean;
+    }>;
 }
 interface TraceContractLlmRules {
     maxCalls?: number;
@@ -309,6 +437,18 @@ type TraceContractBody = {
     tools?: TraceContractToolRules;
     llm?: TraceContractLlmRules;
     observations?: TraceContractObservationRules;
+    /**
+     * Declared-versus-enforced control invariants.
+     *
+     * @experimental Additive in 6.23.
+     */
+    controls?: TraceContractControlRules;
+    /**
+     * Retry / side-effect safety using explicit attempt identity.
+     *
+     * @experimental Additive in 6.23.
+     */
+    retry?: TraceContractRetryRules;
 };
 interface TraceContractInput extends TraceContractBody {
     /**

package/package.json

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