Package com.tnsai.metadata

Record Class ContractSpec

java.lang.Object
java.lang.Record
com.tnsai.metadata.ContractSpec
Record Components:
preconditions - gates checked before execution (a false one throws)
postconditions - gates checked after execution; may use result and old(expr)
invariants - gates checked before and after execution
validate - master switch; false disables all enforcement (treat as documentation)
strict - when false, postcondition failures are logged rather than thrown (pre/invariants always throw)
message - optional override for the violation message
public record ContractSpec(List<String> preconditions, List<String> postconditions, List<String> invariants, boolean validate, boolean strict, String message) extends Record
Programmatic form of the @Contract Design-by-Contract annotation (TNS-552) — the JEXL precondition / postcondition / invariant gates enforced around an action by ContractValidator.

This is the builder-path counterpart of @Contract: an action registered via RoleBuilder.addAction(ActionConfig) (which has no reflective method to carry the annotation) attaches its contract through ActionConfig.contract(). ContractValidator operates on this record for both paths — the annotation path goes through from(Contract) — so there is a single enforcement codepath.

Lives in com.tnsai.metadata (not com.tnsai.actions.contracts) because ActionConfig references it and actions.contracts already depends on metadata (ActionContract → ActionMetadata); placing it the other way would create a package cycle.

Distinct from ContractConfig, which models the older @ActionSpec.precondition + GOAP-effects mechanism (singular expressions + planning effects), not the @Contract DBC gates.

Since:
0.12.0 (TNS-637 phase 4)

  • Field Details

    • NONE

      public static final ContractSpec NONE
      No contract — empty gates. Default for actions without one.

  • Constructor Details

    • ContractSpec

      public ContractSpec(List<String> preconditions, List<String> postconditions, List<String> invariants, boolean validate, boolean strict, String message)
      Creates an instance of a ContractSpec record class.
      Parameters:
      preconditions - the value for the preconditions record component
      postconditions - the value for the postconditions record component
      invariants - the value for the invariants record component
      validate - the value for the validate record component
      strict - the value for the strict record component
      message - the value for the message record component

  • Method Details

    • from

      public static ContractSpec from(Contract contract)
      Adapts a @Contract annotation into a ContractSpec. A null annotation (no @Contract on the method) maps to NONE.

    • isEmpty

      public boolean isEmpty()
      True when there are no gates to enforce.

    • builder

      public static ContractSpec.Builder builder()

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • preconditions

      public List<String> preconditions()
      Returns the value of the preconditions record component.
      Returns:
      the value of the preconditions record component

    • postconditions

      public List<String> postconditions()
      Returns the value of the postconditions record component.
      Returns:
      the value of the postconditions record component

    • invariants

      public List<String> invariants()
      Returns the value of the invariants record component.
      Returns:
      the value of the invariants record component

    • validate

      public boolean validate()
      Returns the value of the validate record component.
      Returns:
      the value of the validate record component

    • strict

      public boolean strict()
      Returns the value of the strict record component.
      Returns:
      the value of the strict record component

    • message

      public String message()
      Returns the value of the message record component.
      Returns:
      the value of the message record component