Exactly-Once: Your agent shouldn't pay the same invoice twice

The exactly-once library ensures that a side effect, such as paying an invoice or sending an email, is executed only once, even in the face of retries, crashes, resumptions, or replays. By wrapping the function that performs the payment, the library executes the effect once per key, then reuses the stored result on subsequent calls.

The integration process involves importing the necessary components from the library, creating a store to maintain records, and using the @once decorator to wrap the payment function. When pay_invoice is called, it transfers funds to the vendor using an idempotency key created from the function's arguments. Should the payment process fail mid-execution, the library writes a record to the store indicating that the payment is in flight.

Upon successful completion, the record is marked as committed and the result is saved. If the process crashes, the library quarantines the key to prevent duplicate payments. The library supports various storage options, including memory, SQLite, Redis, and PostgreSQL, each with their own guarantees. The core mechanism involves an atomic claim-and-set operation to ensure that each key is processed only once.

This provides a robust guarantee of exactly-once effect execution across different scenarios, such as retries, worker concurrency, crashes, and replays. The key to the payment is tied to the invoice's identity, ensuring that multiple attempts to pay the same invoice result in a single payment. Additionally, the library allows integration with providers' idempotency keys, enabling the replay of failed payments when the process resumes or when running in a distributed environment.