StoryboardAI Engineering

Safe to repeat

Labelling each action so that doing it twice by accident has the same effect as doing it once.

What is making an action safe to repeat?

Resuming after a crash has a weak spot. If the crash comes after an action but before the checkpoint that records it, the agent will do that action again. For reading a file, that is harmless. For sending an email or charging a card, it is not.

The defence is to give each action a unique label and send it along. The service on the other end remembers the labels it has seen and quietly ignores a repeat.

Engineers call an action like this idempotent. It turns “never retry, something might happen twice” into “retry freely, nothing will”.

A key lets the receiver recognise a repeat.Step 1: Send the action with a key. Step 2: The reply is lost. Step 3: Send again, same key. Step 4: Already done: nothing repeats.1Send the actionwith a key2The reply is lost3Send again, samekey4Already done:nothing repeats
A key lets the receiver recognise a repeat.

Why does making an action safe to repeat matter?

In any system with networks and retries, the same request is sometimes sent twice. A reply is lost, a worker crashes after acting, a queue redelivers. If the action is a refund or an email, doing it twice is a real failure. Designing actions so that a repeat does nothing extra removes a whole class of expensive mistakes.

How does making an action safe to repeat work?

  1. Each action is given a key that identifies it uniquely, such as the order number and the kind of action.
  2. The key travels with the request.
  3. The receiving system remembers the keys it has already carried out.
  4. A request whose key it has seen is acknowledged and not carried out again.

When should you use making an action safe to repeat?

Use it when

  • An action moves money, sends a message or changes a record
  • Requests are retried after failures
  • Jobs are taken from a queue that may deliver twice

Think twice when

  • The action only reads
  • Running it twice gives the same state anyway, such as setting a value

Where does making an action safe to repeat sit in a real system?

The key is created by the side that asks, and remembered by the side that acts. It has to be enforced by the system that performs the action, because that is the only place that knows what has already happened.

What goes wrong with making an action safe to repeat?

  • Using a random key on each attempt, so every retry looks new.
  • Checking for a duplicate and acting in two separate steps, leaving a gap between them.
  • Assuming a queue delivers each job exactly once.

What does making an action safe to repeat look like in practice?

An assistant asks payments to refund $38 with the key rf-1042. The reply is lost on the network. It asks again with the same key. Payments recognises the key, replies that it is already done, and the customer is refunded once.

Watch it happen

These stories show safe to repeat at work, one step at a time.