♻️ Unify task / coroutine lifecycles

[cowboyd]

Motivation

fixes #1159 #1160 #1153 #1128
closes #1167 #1155 #1162
sets up #1154

There were correctness issues in v4 that arose when halting. They all stemmed from the fact that different parts of the codebase had different ideas about when a task was actually "done" — especially when that task was halted. This led to multiple races around the question.

Approach

This rectifies the situation in the following ways:

1. Every coroutine has a single definite future that can only be resolved when the coroutine is completely exhausted.
2. The task future is derived entirely from the coroutine's future.
3. The task's halt() future is also derived entirely from the coroutine's future.

For tasks, error / success / halt all flow through the same code path: the complete conclusion of the coroutine's body. The only way to see any of these values is for the reducer to ask the coroutine to produce { done: true, value: T }. Previously, we were just dropping this on the floor and resolving a future in a finally {} block of the body.

This entailed making the coroutine layer smarter than before, but the result is a simpler architecture. Rather than being managed by a host of reducers, delimiters, and error boundaries, the coroutine is now the primary organ of evaluation. Coroutines themselves — not instructions — are added to and removed from the reducer queue, so there is no after-the-fact validation of instructions to drop stale ones. A coroutine that changes its internal state between ticks is still fresh when it is dequeued. This eliminated the need for tickets.

We were also able to make trap() the single abstraction for error containment. There is no longer a separate error boundary at the task level.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/effection@1168

commit: 3cfd672

[codspeed-hq]

Merging this PR will improve performance by ×2.1

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
❌ 1 (👁 1) regressed benchmark
✅ 4 untouched benchmarks
⏩ 18 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	Simulation	effection-inline.recursion	2,775.7 µs	521.5 µs	×5.3
👁	Memory	effection-inline.recursion	3.3 KB	4.1 KB	-18.46%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing unified-lifecycle (3cfd672) with v4 (096ebda)}

Footnotes

1. 18 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩