Phase 8b: async-runtime adapter — the executor pool and its timer

[Wahbeh-Mohammad]

Part of #31. First PR of phase 8b's three-PR stack — the code — built off main at a7cfeb6 (phases 0–7 and 8a) concurrently with 8c #32, reviewed and approved there; main has not moved since, so no reconcile pass was needed. Its tests are the next PR up and the phase record the one after. The first executor Transport.async_over has ever had, and the first real producer to settle phase 2's pivot.

What lands

dexpace-async-thread becomes a real gem — 10 files, +1,053 / −14 — ASYNC-1, 2, 5, 7–20 (seventeen ✅), ASYNC-3 ⏳ and ASYNC-4 N/A under §10.5 exactly as the issue forecast, plus fifteen cross-reference rows (PIPE-33, ASYNC-6, SEAM-12, SEAM-18, SEAM-25, XCUT-11, XCUT-13, XCUT-22, …).

• Dexpace::Async::Thread::Pool — a fixed-size ::Thread pool over a bounded ::Thread::SizedQueue (size: required, queue_limit: derived from QUEUE_DEPTH_PER_WORKER), .build validating through four private class methods, #initialize keyword-only. #post never blocks the caller: a full queue or a closed pool raises RejectedError synchronously, which Bridge::AsyncOver routes to Completer#fail — the rejection policy that satisfies ASYNC-2 rather than violating it (R12). The worker loop is named, netted (rescue ::Exception → one contained http.instrumentation.hook ERROR diagnostic; report_on_exception = false), and performs the ASYNC-8–ASYNC-12 diagnostic hop: the caller's Fiber[] snapshot captured at #post, installed for the task through Diagnostics.with, and cleared at both boundaries — after every task and before the next — so nothing a task writes leaks to the next job on the same worker (P8-20). The gem's own defect diagnostic is emitted inside the installed context so it carries the caller's trace.id — round 4's R3-1, the one real code defect the reviews found: the report had been emitted after Diagnostics.with restored the thread, on the worker and on the timer alike.
• #close / #release — Closeable's latch; the queue closed, the sentinels drained within shutdown_timeout: (DEFAULT_SHUTDOWN_TIMEOUT), the workers joined inside what remains so Thread.list is stable at return, SEAM-25's INSTRUMENTATION_SHUTDOWN emitted once at INFO with worker_count and drained (ASYNC-15–17). A close from one of the pool's own threads completes instead of self-joining (round 1's R0-2/R0-8: drain_workers counts the calling worker as exited; Timer#stop never joins ::Thread.current).
• #delay(seconds) over the private Timer (ASYNC-18, R11): a parked timer thread over the pool's clock: and a ::Thread::Queue#pop(timeout:) wake — never Kernel#sleep, never a Fiber.scheduler; the future settles with true (P8-71 — Completer#fulfil(nil) raises; 5a's P5-52 precedent), a zero delay settles inline, a NaN, infinite or Complex duration is refused at the call (round 2's R1-1 — a NaN had killed the timer thread). Every callback runs guarded under the delay caller's own snapshot (round 3's R2-1 — the timer had inherited the first caller's Fiber[] for every later delay), entries are removed by identity, #schedule after #stop is refused through on_shutdown, and the timer carries the worker's net with a bounded join that never re-raises a dead thread's exception past #close (P8-22 and P8-25 extended, P8-75). private_constant :Timer, with a hooks.rbs-style sig mirror.
• The entry file — require "dexpace", REQUIRED_CORE (7a's spelling, P8-72; the design's CORE_REQUIREMENT renamed, never aliased) and the version-skew assertion run before the require_relative chain, so a skewed Dexpace::VERSION fails the require itself and defines no Pool — the direct form P8-21 chose because there is no executor registry (P2-1). The gemspec is byte-identical: dexpace-core and nothing else.
• sig/ mirrors lib/ one file per file; the manifest regenerated once — dexpace-async-thread 2 → 14 rows (Pool, .build, #post, #delay, #size, #queue_limit, #name, the three constants, REQUIRED_CORE, RejectedError; nothing for the private Timer, Job or Entry); the other five manifests byte-identical to main. The skeleton's smoke suite preloads core's stdlib before its constant snapshot and pins the four public constants.

Touches nothing else: no core file (Bridge::AsyncOver already checks the token before dispatch — phase 2's #44 — so the design's finding 2 was closed before this phase, and two of the plan's tests were rewritten to assert what core does), no tool, task, gate, Steepfile, rbs_collection.yaml, VERSIONS, Gemfile or CI file, nothing under 8c's, 8a's or 7a's gems. The plan's Task 1 allowlist fix and Task 12 composed clean-bundle check were both already on main (phase 0's #36; 8a's clean_bundle_check installs core beside every adapter) and are recorded as verification passes.

Decisions taken in the open, against the plan's text

Ledger rows P8-71–P8-78 in the design's As-built addendum and the checklist's "Deviations from the plan" (forty-one items). Beyond those above: the composed test at the charter's convergence point 2 is this lane's (8a landed first) and lives in this gem's test tree (P8-73 — see the tests PR); worker-side reads of the diagnostic context go through Diagnostics.capture because the 3.2 floor retains nil-valued Fiber[] keys, and core's reserved dexpace. slots travel with the snapshot (P8-74); the plan's Task 7 Step 8 "deadlock proof" is measured false (the timer's wait runs on the timer thread, which has no scheduler) and routed; the doubles are unique top-level Pool-prefixed constants and the test classes are gem-unique too (PoolMatrixFactsTest — the one-process test:gems run aborted at load on a bare MatrixFactsTest), now a CLAUDE.md constraint.

Layering

Each tip is green under every gate on its own tree — all eighteen. This branch is green on the SimpleCov floor too — 98.43% on 4.0.6 (3,704 runs, 0 failures); the tests PR takes the same tree to 99.87% with 3,818 runs / 73,279 assertions and 1 skip — 8a's TRANSPORT-18 measured vacuity, on main today.

Verification

• Independent review, five rounds by five fresh reviewers with a fix round between each — the four-review cap was reached with round 3 at 0 blocking / 1 should-fix / 1 nit, and the manager chose one targeted round because R3-1 was a real code defect (6c's and 8a's precedent): round 0 1 / 2 / 5; round 1 0 / 1 / 2; round 2 1 / 0 / 2; round 3 0 / 1 / 1; round 4 approve, 0 / 0 / 0. Code changes from review: a close from the pool's own threads (round 1), the non-finite duration (round 2), the timer's per-delay context (round 3), the correlated defect diagnostic (round 4); every other finding was a test or docs gap, each closed by a mutation-proven case.
• All eighteen gates individually at this tip on 4.0.6; the matrix set on 3.2.11 (98.48%), and on 3.3.12 and 3.4.10 at the tests tip; honest RuboCop clean (672 files); probe clean at the docs tip — each run by the reviewers and again by the manager's pre-push checks.
• Mutations: 38, 43, 52, 47 and 42 by the five reviewers on 4.0.6 and 3.2.11; the one survivor at the last round is the recorded equivalent (guard 8 alone — the closed? pre-check in #post, whose red proof is 8 + 5 together). Forty-three guards run red and recorded in the checklist.
• By experiment, both interpreters: a block posted under {trace.id: REQ-7} that raises produces a diagnostic carrying REQ-7 (nil at the round-3 tip); a close from a #delay future's on_settle returns with the shutdown event emitted; a stuck on_settle handler cannot hang #close; #delay(Float::NAN) refused synchronously; the real Dexpace::Transport::NetHTTP over WireServer through Transport.async_over(adapter, executor: pool) — a 200 as the exact object, a scripted failure as the same exception, an in-window cancel closing the pump-backed response exactly once; the as-built page's eleven blocks extracted and run as one script on both rows (56 checks).

Known follow-ups from the reviews (not blocking a gate)

• Recorded equivalents: guard 8 alone (the closed? pre-check in #post) and guard 12 alone (return false if budget <= 0) — each survives alone; 8 + 5 and 12b are the red proofs.
• #on_settle on a #delay future runs on the timer thread, or on the closing thread when #close fails it; a stuck handler there is the caller's own doing — documented in the README's "Where callbacks run", not guarded against. The shutdown callback runs under the delay caller's context on the closing thread and is restored, never cleared (P8-78).
• Routed to phase 10's inbound list, dated: under the one-process test:gems the main fiber's storage held 5c's NO_SPAN slot when this gem's diagnostics suite ran (whether DexpaceTestCase should assert the main fiber's storage unchanged at teardown, and which suite leaves it); the plan's Task 7 Step 8 premise (whether XCUT-11's audit wants a structural scan for a mutex held across a queue wait).
• pool_delay_test.rb and the as-built page reach the timer's entry list through instance_variable_get; a rename of those ivars needs the tests updated. Guard 5's racing test catches the missing ClosedQueueError arm only when the window opens; the deterministic "queue closed under an open latch" case is the load-bearing guard.