🐛 propagate halt out of scoped() + race() when callcc resolves externally

[taras]

Fixes #1185.

Problem

When callcc is resolved externally (scope.run(() => resolve(...))) inside a scoped() body that uses race(), the halt signal failed to stop the surrounding loop — all rounds ran to completion. This broke graceful SIGINT shutdown for the exact main() + scoped() round-boundary + race()-timeout pattern.

Root cause

scoped() runs on the same coroutine as its caller. On halt, routine.unwind() sets data.unwinding = true, and step() consumes it exactly once — it calls iterator.return() and resets the flag. But scoped's teardown (yield* destroy()) is async: it halts the race children across multiple scheduler turns. By the time teardown finished, unwinding had already been reset, so step() took the normal iterator.next() path and the outer loop simply continued to the next round instead of finishing its own unwind. (race/callcc matter only because they introduce the spawned children that make teardown span multiple turns.)

Fix

Localize the fix to scoped()/trap() and reuse the existing unwind-propagation machinery — no change to the coroutine step() state machine:

• Route the scoped body through a Trap (capturing success/error in t.outcome).
• Run teardown as yield* critical(destroy) so multi-step async cleanup completes via .next() rather than being short-circuited by the unwind branch.
• After teardown, yield t.exit() — when no outcome exists (the body was interrupted), Trap.exit() calls routine.unwind() again, re-asserting the unwind so the outer loop finishes instead of continuing.

This preserves the single-use-return unwind contract (the test/coroutine.test.ts "uses 'return' for a single iteration when unwound" canary still passes) and exports Trap so scoped can reuse it.

Relationship to #1186

This implements the same approach as #1186 (Trap-routed scoped + critical(destroy) + t.exit()) and additionally adds the missing regression test pinning the callcc + scoped + race halt path — there was previously no test covering this exact combination, so the bug could silently return.

Test

test/scoped.test.ts adds "propagates halt out of a scoped() + race() loop when callcc resolves externally". It reproduces the issue's scenario: the loop must stop after round-1-teardown and never start round 2. Verified to fail on v4 HEAD (all 3 rounds run) and pass with this fix.

[pkg-pr-new]

Open in StackBlitz

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

commit: 6b863b5

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing fix/1185-halt-through-scoped-race (6b863b5) with v4 (846b97e)}