Package com.tnsai.reliability

Interface ResumableRun<I,O>

Type Parameters:
I - the run's input type
O - the run's terminal output type
All Known Implementing Classes:
DefaultResumableRun
public interface ResumableRun<I,O>
Driver for a long-running, checkpoint-backed agent execution (TNS-299). The reliability counterpart to a bare while loop.

A single ResumableRun instance owns the contract for one kind of run — its step list, its serialization shape, its idempotency strategy. Each call to execute(I, com.tnsai.reliability.RunConfig) begins a new run with a freshly minted run id; resume(java.lang.String) picks up an existing run from its latest checkpoint; abort(java.lang.String, com.tnsai.reliability.AbortReason) stops one mid-flight.

Execution model

The orchestrator invokes the run's steps in order, persisting a Checkpoint between them via the configured CheckpointStore. Side-effecting steps consult an IdempotencyStore to dedupe retries. Progress events flow to a ProgressSink. Policy (RunConfig) caps duration / retries / cost / progress timeout; breaches abort the run with the appropriate AbortReason.

Idempotency contract

Calling execute with the same input does not dedupe at this layer — every execute starts fresh with a new run id. Per-step idempotency, where the same logical step inside a single run mustn't double-execute on retry, is what com.tnsai.idempotency provides. Cross-call idempotency (the entire run shouldn't be started twice) belongs to the consumer's request boundary, not here.
Since:
0.10.0 (TNS-299)

  • Method Details

    • execute

      Outcome<O> execute(I input, RunConfig config)
      Start a new run. The orchestrator mints a fresh run id, walks the step list, and returns a terminal Outcome.
      Parameters:
      input - initial input handed to the first step
      config - execution-time policies; bounds duration / retries / cost / progress timeout
      Returns:
      one of the four Outcome variants — never null
      Throws:
      NullPointerException - if either argument is null

    • resume

      Outcome<O> resume(String runId)
      Pick up a paused run from its latest checkpoint. The orchestrator loads the checkpoint via CheckpointStore.latest(java.lang.String), restores step state, and continues from the next step.

      If no checkpoint exists for runId, the implementation returns Outcome.Failed with a clear "no such run" message rather than starting a fresh one — confusing one for the other was the bug pattern this primitive is supposed to prevent.

      Throws:
      NullPointerException - if runId is null
      IllegalArgumentException - if runId is blank

    • abort

      void abort(String runId, AbortReason reason)
      Stop a run that's currently in flight. The orchestrator transitions to Outcome.Aborted at the next step boundary; already-running step bodies are not interrupted, so abort is cooperative — designed for "graceful shutdown by the next safe point" rather than mid-call cancellation.

      Calling abort on a run id that isn't in flight is a no-op (already terminated runs ignore the request).