Package com.tnsai.invariants

Class InvariantChecker

java.lang.Object
com.tnsai.invariants.InvariantChecker
All Implemented Interfaces:
com.tnsai.invariants.InvariantCheckerHandle
public class InvariantChecker extends Object implements com.tnsai.invariants.InvariantCheckerHandle
Runtime invariant checker for TnsAI roles.

Standalone checker capabilities:

  • @ActionSpec.precondition() - before action execution
  • @ActionSpec.postcondition() - after action execution
  • @State.invariants() - after any state change

ActionExecutor calls only checkStateInvariants() for an explicit @InvariantCheck. Direct callers may evaluate planner expressions with checkPrecondition(Method) and checkPostcondition(Method), but those expressions do not gate runtime action dispatch. Runtime contracts belong on @Contract.

Method-level @ActionSpec.invariants() was removed in 0.9.2 — use @State.invariants for state predicates and @ActionSpec.mustAlways/mustNever for behavioral constraints.

Usage


 InvariantChecker checker = new InvariantChecker(role);

 // Before action
 checker.checkPrecondition(method);

 // Execute action...

 // After action
 checker.checkPostcondition(method);
 checker.checkStateInvariants();
Author:
TnsAI Team

  • Constructor Details

    • InvariantChecker

      public InvariantChecker(Object target)
      Creates a checker for the given target object.
      Parameters:
      target - the object to check invariants on

    • InvariantChecker

      public InvariantChecker(Object target, boolean strict)
      Creates a checker for the given target object.
      Parameters:
      target - the object to check invariants on
      strict - if true, throws exceptions; if false, only logs warnings

  • Method Details

    • setStateField

      public InvariantChecker setStateField(String fieldName)
      Sets the state field name used for conditional rule effect checking.
      Parameters:
      fieldName - the field name (default: "state")
      Returns:
      this for chaining

    • checkPrecondition

      public void checkPrecondition(Method method)
      Checks the precondition of an action.
      Specified by:
      checkPrecondition in interface com.tnsai.invariants.InvariantCheckerHandle
      Parameters:
      method - the action method
      Throws:
      com.tnsai.invariants.InvariantViolationException - if precondition fails (in strict mode)

    • checkPostcondition

      public void checkPostcondition(Method method)
      Checks the postcondition of an action.
      Specified by:
      checkPostcondition in interface com.tnsai.invariants.InvariantCheckerHandle
      Parameters:
      method - the action method
      Throws:
      com.tnsai.invariants.InvariantViolationException - if postcondition fails (in strict mode)

    • checkStateInvariants

      public void checkStateInvariants()
      Checks all @State field invariants.
      Specified by:
      checkStateInvariants in interface com.tnsai.invariants.InvariantCheckerHandle
      Throws:
      com.tnsai.invariants.InvariantViolationException - if any state invariant fails (in strict mode)

    • checkBeforeAction

      public void checkBeforeAction(Method method)
      Checks all conditions before action execution.
      Parameters:
      method - the action method

    • checkAfterAction

      public void checkAfterAction(Method method)
      Checks all conditions after action execution.
      Parameters:
      method - the action method

    • collectViolations

      public List<String> collectViolations(Method method)
      Collects all violations without throwing exceptions.
      Parameters:
      method - the action method
      Returns:
      list of violation messages

    • check

      public static void check(Object target, String methodName)
      Checks invariants for a method on the given target.
      Parameters:
      target - the target object
      methodName - the method name
      Throws:
      com.tnsai.invariants.InvariantViolationException - if any check fails

    • checkAfter

      public static void checkAfter(Object target, String methodName)
      Checks invariants after action execution.
      Parameters:
      target - the target object
      methodName - the method name
      Throws:
      com.tnsai.invariants.InvariantViolationException - if any check fails