AI 에이전트가 재시도 시 이메일을 다시 보내는 문제: 부작용을 위한 아웃박스

pip install reactifact
python -m examples.outbox.main   # 일곱 가지 케이스가 있으며, 각각 단언됨

from reactifact import PendingAction, ProduceCall, produce

@produce(Receipt, also_creates=[PendingAction])
...

런타임은 각 생성(generation)의 커밋 후 아웃박스(outbox)를 비우면서, 각 액션에 대해 `dispatched` 상태로 표시하거나, 디스패처가 예외를 발생시키면 `failed` (그리고 재발생) 처리합니다. 실패한 디스패치는 손실된 효과(lost effect)가 아니라 _상태_입니다.

## 분리 구조가 제공하는 이점

-   **재생(Replay)은 복원할 뿐, 다시 전송하지 않습니다.** reactifact 재생은 커밋 체인(commit chain)을 따라 걸으며 런타임을 실행하지 않고 `Context`를 재구축합니다. 기록된 알림은 상태로 읽어옵니다. 재생은 "왜 그것이 전송되었는가?"라는 질문에 다시 보내지 않고 답합니다.
-   **재시도(Retries)는 중복되지 않습니다.** 재개된 실행은 동일한 안정 ID를 재파생하므로, `effects.act`는 `None`을 반환하고 두 번째 의도(intent)가 존재하지 않습니다.
-   **병합된 브랜치(Merged branches)는 수렴합니다.** 독립적으로 같은 액션에 도달한 두 포크(forks)는 ID를 공유하며 **하나의** 의도로 병합됩니다. 디스패치 기록부(상태/타임스탬프/오류)는 3방향 병합 서명에서 제외되며, `dispatched` 측이 어떤 브랜치가 병합 대상이든 관계없이 승리합니다. 따라서 병합은 이미 전송된 액션을 부활시킬 수 없습니다. 동일한 ID를 가진 상충되는 페이로드(payload)는 조용한 마지막 쓰기 승리(last-write-wins)가 아니라 명시적인 병합 **충돌(conflict)**입니다.
-   **동일 세대 중복은 붕괴됩니다.** 하나의 생성에서 의도를 기록하는 두 프로듀서가 각각 하나씩의 아티팩트와 한 번의 전송을 생성합니다. 이는 커밋 후 드레인(drain) 시점에 중복 제거(dedupe)가 발생하기 때문입니다.

사용자는 큐(queue)로부터 얻고 싶었던 운영 스토리(operational story)를 얻게 되지만, 이 "큐"는 이미 가지고 있는 버전 관리된 상태일 뿐입니다.

## 솔직한 한계점

이것은 의도적으로 메시지 브로커가 아니며, 그 한계점들은 명확하게 밝힐 가치가 있습니다:

- **정확히 한 번이 아닌, 적어도 한 번(at-least-once)입니다.** 실제 전송과 `dispatched` 커밋 사이에서 충돌이 발생하면 배달 처리가 재실행됩니다. 프레임워크가 I/O를 정확히 한 번(exactly-once)으로 처리할 수는 없기 때문에, 의도(intent)는 외부 시스템에 전달하는 `idempotency_key`를 포함하며, 이 키가 외부 시스템 측에서 중복을 제거합니다. 이것이 모든 실제 아웃박스(outbox)가 의존하는 동일한 계약입니다.
- **백그라운드 릴레이가 없습니다.** 다음 `arun()` 호출이나 명시적인 `flush_pending_actions()` 호출이 아웃박스를 비우며, 프레임워크가 폴러(poller)를 자동으로 실행하지 않습니다. 재시도 및 백오프 정책은 애플리케이션(디스패처를 래핑하는 방식)에 남아 있어야 합니다. 왜냐하면 이것은 제품 결정이지, 프레임워크의 반사적 동작이 아니기 때문입니다.
- **단일 프로세스(single-process) 기반입니다.** 아웃박스는 상태(state)가 리플레이 안전성(replay-safe)을 갖도록 하지만, reactifact를 분산 작업 큐(distributed task queue)로 만들지는 않습니다.

이것이 분리된 구조의 핵심입니다. 상태는 버전 관리되고 재현 가능하지만, 외부 세계는 그렇지 않으며, 이 둘 사이의 경계는 함수 중간에 숨겨진 것이 아니라 사용자가 직접 선언해야 하는 무언가여야 합니다.

## 오프라인 실행하기 (Run it offline)

이 전체 기능은 API 키가 필요 없는 독립적인 실행 파일 형태로 제공됩니다. `examples/outbox`는 일곱 가지 케이스를 순회하며 각각을 검증합니다:

이 기능은 상관관계가 있는 구조화된 로깅과 우아한 종료를 갖춘 트랜잭션별 마감 시간(per-turn deadline)을 함께 묶어 0.14.0 버전에서 출시되었으며 (현재 릴리스는 0.15.x): 

-   릴리스: [https://github.com/bzdvdn/reactifact/releases/latest](https://github.com/bzdvdn/reactifact/releases/latest)
-   코드: [https://github.com/bzdvdn/reactifact](https://github.com/bzdvdn/reactifact)
-   문서: `docs/en/patterns.md#outbox-external-side-effects` 및 `docs/en/durability.md#outbox-in-production`

이것이 절반의 이야기입니다. 아웃박스(outbox)는 외부 효과가 두 번 실행되는 것을 막아줍니다.

나머지 절반, 즉 답변 뒤에 있는 _상태(state)_를 검사하고 재현할 수 있게 만들어 해시(hash)하고 재생(replay)하며 추적 기록을 감사(audit)할 수 있도록 하는 것이 바로 [다음 게시물](https://dev.to/bzdvdn/auditable-agents-turn-the-answer-into-a-claim-you-can-check-2lm4-temp-slug-3862381)에서 다룰 내용입니다.

만약 여러분이 외부 세계와 상호작용하는 에이전트(agent)를 구축하고 있다면, 정말 알고 싶습니다. **재현 가능한 계산과 외부 효과 사이의 경계를 어디에 긋고 있나요?** Intents-as-state가 하나의 답변이지만, 다른 아이디어들도 궁금합니다.