pcbjam/docs/features/async/15-timer-park-repro.md

15 — Timer-park repro lever (concurrent-Asyncify collision)

Status: lever built 2026-07-31 · spec tests/kicad/timer-park-repro.spec.ts · investigation: the v0.1.17–19 prod board-load trap (gal-refresh-timer).

Why this exists

The prod trap ("index out of bounds" + "unreachable executed" in doRewind/finishContextSwitch) has survived three shipped fixes and 10+ local repro attempts. The 2026-07-31 v0.1.19 crash log re-ranked the hypotheses decisively:

• The wx diagnostics shipped in v0.1.19 ([wx-dispatch] depth-erasure, [wx-timer] retry storms) were live and silent on a real crashing run — the modal depth-zeroing and long-parked-dispatch theories are disfavored.
• The load was fast (0.5 s open, warm caches) and still trapped, 214 ms after open:settled, before any collab embind entry — inside the GAL pre-first-paint 100 ms rearm cascade.

What remains is the concurrent-park family (emscripten #9153): the main loop spends most wall-clock time Asyncify-parked in wxWasmYieldToBrowser; a wx timer callback is a fresh JS→wasm entry; if the timer handler itself parks, two live Asyncify contexts share the single-slot Asyncify.currData. The handlesleep.js shim silently repairs the pointer aliasing (as of this change it REPORTS each repair as [wx-asyncify] …), but fiber swaps (emscripten_fiber_swap, used by every collab entry via TOOL_MANAGER coroutines) bypass its accounting entirely — and finishContextSwitch is exactly where the prod trap's second stack dies.

The lever

wasm/bindings/timer_park.h + exports in pcbnew_embind.cpp and kicad_editor_embind.cpp (mirrors the kicadTestSetOpenPark conventions):

• kicadTestArmTimerPark(delayMs, parkMs) → bool — one-shot wxTimer whose Notify() runs emscripten_sleep(parkMs). The entry path is byte-for-byte the GAL refresh timer's: emscripten_async_call → TimerCallbackFunc::Run → wxWasmDispatchGuard → Notify() — then it parks, which is what the GAL handler is suspected of doing (paint → GAL init / lib bridge) on crashing loads.
• kicadTestTimerParkState() → {"fired","done","parked","parkMs"} — JS-pollable progress. fired without done = the park is in flight.

Production is inert: nothing fires unless armed.

Side effect worth knowing: while the parked Notify() holds its dispatch guard, every other due timer spins the 17 ms retry loop — a park ≥ ~1 s also exercises the [wx-timer] retry storm diagnostic.

The spec

tests/kicad/timer-park-repro.spec.ts (pcbnew-collab harness, merged kicad_editor.js): open a 2k-item board, settle, then three cycles — park-only, park + fiber hammering (kicadCollabSnapshotItems / kicadCollabGetPos every 10 ms through the window), and a second hammered draw. Asserts:

• each cycle's Notify() fires, is observed parked, and survives its rewind;
• no embind entry traps; no trap signature anywhere in the console;
• the runtime stays functional afterwards (snapshot walks the board, a real apply lands);
• the [wx-asyncify] shim diagnostics observed the concurrent-park window — silence there means the lever never created the overlap (vacuous run), not a pass.

Interpretation: RED with the prod signature ⇒ hypothesis confirmed, and the failing interleaving is named by the shim lines. GREEN ⇒ plain double-park + fiber-during-park is handled; the prod mechanism needs another ingredient (ranked next: fiber swap racing a park's WAKE, GAL-init-specific state, memory growth mid-park — see the trace GREW +187MB at stage:done).

Round 1 result (2026-07-31, first run of the lever)

GREEN — and the window demonstrably engaged. Three cycles (park-only, 2× park + fiber hammer) on the fresh build:

• [wx-asyncify] aliased-wake-live fired 6×: two different chains' asyncify buffers restored over each other (83722240 ⇄ 104366080) — the literal #9153 cross-chain aliasing, live and deterministic. The shim's repair held every time; the runtime stayed fully functional.
• [wx-timer] retry storm: 60 retries (~1s parked, depth=1) + storm-end — the v0.1.19 C++ diagnostic channel validated end-to-end. (Prod's crash log had NO storm line ⇒ prod's fatal window is < ~1 s.)
• Shim-check calibration learned the hard way: handleSleep re-entry with state=2 (Rewinding) + currData set is NORMAL resume mechanics (~100/s during the cycles) — the concurrent-park/reentrant-state checks were narrowed to state===0 / state===1 accordingly.

Implication: plain concurrent park + fiber swaps + live pointer aliasing is INSUFFICIENT to trap on this build. Round 2 adds the next prod ingredient: heap growth mid-park (___libc_malloc(256MB) through the window — the prod trace grew +187 MB during the load), cycle 4 of the spec.

Round 2 result (2026-07-31, refined shim + growth cycle)

Still GREEN — four cycles, growth included. With the calibrated checks the picture is precise: 4× genuine concurrent-park (state 0 — the timer's _emscripten_sleep starting while the yield park's currData was live, wasm frames in the report stack), 8× aliased-wake-live (the two chains' buffers cross-restored, both directions), 5× overlapped-wake, 0× reentrant-state (mid-unwind entry does not occur), 256 MB heap growth mid-park absorbed cleanly.

So on Firefox/local, the full stack of suspected ingredients — fresh double-park, fiber swaps through the window, live currData aliasing, heap growth across parked buffers — is handled by the shim + runtime. The prod trap requires something this harness still lacks. Ranked next:

1. A second parking timer staggered into the FIRST one's wake tick — the prod first-trap stack is 3-deep in the async_call rearm cascade; a park colliding with a rewind in progress (not a parked-idle chain) is the one interleaving the lever does not yet force.
2. GAL pre-first-paint state (prod trapped before first paint; this harness is long-painted by cycle time).
3. Prod-only environment: real lib realtime resolves + presence WSS fibers + the user's machine timing.

The lever + spec stay as the regression gate for the fix regardless: they deterministically create and verify the concurrent-park window that all three shipped fixes were blind to.

Round 3 — v0.1.20 PROD crash decoded (2026-07-31 late, log console-export-2026-7-31_22-33-27.log)

The crash reproduced in prod with the diagnostics live, and they discriminate cleanly: ZERO concurrent-park, ZERO aliased-wake-live (this spec's collision class is NOT the prod mechanism — the two green rounds were a true negative), exactly one benign overlapped-wake … over null 2 ms after open:settled, traps 218 ms later. Decoding the trap stack against the shipped runtime source:

Root cause: a KiCad coroutine is Resume()d while its body is asyncify-parked inside handleSleep. libcontext-on-emscripten-fibers and handleSleep are two independent suspension protocols sharing one context: a fiber suspended by fiber_swap has valid rewind data at fiber+20; a fiber whose body parked via handleSleep does NOT (its live state is in the sleep's allocateData buffer, invisible to the fiber machinery — and to TOOL_MANAGER). Resume → fiber_swap into it → finishContextSwitch rewinds the STALE fiber+20 → rewind-path mismatch → "unreachable executed"; every subsequent entry (the GAL timer's async_call cascade among them) reads poisoned asyncify state → "index out of bounds". Impossible on native (no parking without yielding), unreachable in this spec (warm fibers never park internally), and untouched by all three shipped fixes.

Next: a kicadTestSetFiberPark(ms)-style lever (coroutine body that emscripten_sleep()s + a Resume poked mid-park) as spec cycle 5 — expected deterministically RED with exactly the prod signature — then the fix: track "asyncify park in flight" per fiber and defer Resume/swap-into until the park completes (wasm layer; kicadCollabFiberBusy from drift-trio #10b is the precedent).

Candidate real fix for the timer half (superseded by round 3 for the prod

crash, still sound hygiene)

Deliver timer notifies from the main-loop chain: the JS timer callback only marks the timer due and wakes the yield; the loop dispatches due timers after its rewind, when it is the sole live context. Structurally removes fresh-entry parks from timers. Keep the 17 ms retry interlock for the dispatch-chain case.