Package com.tnsai.annotations

Enum Class IdempotencyHint

java.lang.Object
java.lang.Enum<IdempotencyHint>
com.tnsai.annotations.IdempotencyHint
All Implemented Interfaces:
Serializable, Comparable<IdempotencyHint>, Constable
public enum IdempotencyHint extends Enum<IdempotencyHint>
Declares the runtime dispatcher's expectation about idempotency-key tracking for a Tool method (TNS-299). Tracking itself is configured independently with com.tnsai.idempotency.Idempotent.

Companion to SideEffect: a tool's effect classification tells you whether retries are dangerous; this hint tells the runtime dispatcher whether an active policy with a stable key is required to make retries safe.

Since:
0.10.0 (TNS-299)

  • Enum Constant Details

    • NONE

      public static final IdempotencyHint NONE
      No idempotency tracking. Either the tool is naturally idempotent (matches Tool.idempotent()) or its side effects are inconsequential enough that a duplicate call is acceptable. Default for SideEffect.NONE and SideEffect.READ tools.

    • OPTIONAL

      public static final IdempotencyHint OPTIONAL
      Idempotency tracking is supported but not required. Dispatch uses an independent Idempotent policy when present and otherwise runs unguarded. Useful for write tools that can be retried safely under a key but don't have to be.

    • REQUIRED

      public static final IdempotencyHint REQUIRED
      Idempotency tracking is mandatory. The runtime dispatcher refuses to invoke the tool unless Idempotent provides a stable HASH_INPUT or EXPLICIT key strategy with a positive cache TTL and surfaces an actionable error otherwise. Reserve for tools where a duplicate would cause real damage — payments, public posts, irreversible deletes.

  • Method Details

    • values

      public static IdempotencyHint[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static IdempotencyHint valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null