Package com.tnsai.annotations

Enum Class SideEffect

java.lang.Object

java.lang.Enum<SideEffect>

com.tnsai.annotations.SideEffect

All Implemented Interfaces:

Serializable, Comparable<SideEffect>, Constable

public enum SideEffect
extends Enum<SideEffect>

Classifies the observable effect a Tool method has on the world (TNS-299). ToolMethodRegistry carries this metadata into the runtime dispatch path and warns at registration time when an external tool omits an idempotency hint. The classification alone does not activate idempotency tracking; use Tool.idempotencyHint() with com.tnsai.idempotency.Idempotent for that policy.

Orthogonal to Tool.idempotent(): idempotent is a retry-layer hint that says "calling twice with the same args has the same effect"; this enum classifies where the effect lives (in-process? on disk? on a remote system?).

Since:

0.10.0 (TNS-299)

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
EXTERNAL	Calls a third-party system whose effect we cannot reverse.
NONE	Pure function.
READ	Reads external state but does not mutate it.
WRITE	Mutates state inside the framework or on a system the framework directly controls.

Method Summary

Modifier and Type	Method	Description
static SideEffect	valueOf(String name)	Returns the enum constant of this class with the specified name.
static SideEffect[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

compareTo, describeConstable, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

NONE

public static final SideEffect NONE

Pure function. No reads, no writes, no I/O. Calling the tool twice trivially produces the same result and the same world state. Safe to retry, parallelise, dedupe at any layer.

READ

public static final SideEffect READ

Reads external state but does not mutate it. Database SELECTs, GET requests, file reads, embedding lookups. Safe to retry; the world state doesn't change so duplicate calls are wasteful but not harmful.

WRITE

public static final SideEffect WRITE

Mutates state inside the framework or on a system the framework directly controls. Database INSERT/UPDATE/DELETE, file write, memory commit. Pair with Tool.idempotencyHint() and an com.tnsai.idempotency.Idempotent policy when retries must not double-execute.

EXTERNAL

public static final SideEffect EXTERNAL

Calls a third-party system whose effect we cannot reverse. POST to a payment processor, send a Telegram message, create a GitHub PR, kick off a CI build. Idempotency keys are strongly recommended; tools without a hint surface a registration-time warning.

Method Details

values

public static SideEffect[] 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 SideEffect 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