The following is AI (GPT 5.5)'s opinion on ADR-002 Phaser vs ADR-003 CompletableFuture for reference:

I’d still choose ADR-003 / CompletableFuture for this SDK.

The short version: Durable operation coordination is fundamentally a completion problem, not a barrier synchronization problem. A step, wait, invoke, or callback eventually reaches a terminal state, and any blocked caller should resume after that terminal state is durably recorded. CompletableFuture models that directly. Phaser can be made to work, but it asks the implementation to encode lifecycle meaning into phase numbers and party counts, which is exactly the kind of cleverness that becomes fragile under replay, duplicate updates, and edge-case timing.

Why CompletableFuture is better here:

1. The domain is one-shot completion.
   A durable operation needs to say: “I am complete; unblock anyone waiting on me.” CompletableFuture.complete(...) naturally supports that and is idempotent in spirit: duplicate completion attempts do not advance some hidden global phase. That matters because durable systems often see repeated state from replay, polling, retries, or backend responses.

2. Phaser depends on assumptions that the system cannot always guarantee.
   ADR-003 calls this out well: the Phaser model assumes a certain number of parties and specific phase transitions. In a concurrent replay/checkpoint system, those assumptions are hard to maintain. If you under-arrive, you deadlock. If you over-arrive, you move past the intended phase. Both are nasty failure modes.

3. CompletableFuture makes the coordination object match the operation.
   Each operation owns a future. Waiters attach to that operation. Completion happens when the operation is durably complete. That gives a cleaner mental model than “operation phase 0 means running, phase 1 means completing, phase 2 means safe to deregister,” especially for future contributors.

4. The failure modes are easier to test and explain.
   The CompletableFuture design still has subtle ordering requirements, especially around re-registering a blocked user thread before the step thread deregisters. But that logic is localized. The current code’s synchronized block around future completion/waiter registration is easier to reason about than a multi-phase protocol spread across operation execution and checkpoint callbacks.

5. It leaves the two-thread-pool idea intact.
   The valuable part of Philipp’s design was isolating user code from SDK/system work. CompletableFuture does not reject that; it gives the same architecture a simpler coordination primitive.

The best argument for ADR-002 is that Phaser explicitly models a multi-party handoff, and the two-phase protocol was trying to solve a real race: “don’t let the last worker deregister before the blocked caller is active again.” That is a serious problem, and the ADR-002 design shows thoughtful understanding of it. But I think Phaser is too powerful and too implicit for this case. It makes correctness depend on everyone participating in exactly the right phase choreography.

So my judgment: ADR-003 is the better long-term design, not because ADR-002 was careless, but because ADR-002 solved a hard problem with a synchronization primitive whose semantics did not quite fit durable replay. For SDK code that customers rely on, boring and directly modeled usually wins.