pcbjam/docs/features/async/21-park-site-audit.md

21 — Park-site audit (doc 20 D0 deliverable)

Status: AUDIT (2026-08-05). The classification doc 20 §6 D0 calls for: every Asyncify park site in the tree, classified by whose stack it suspends — tool fiber / entry stack / main loop — with the routing decision per site. Method as doc 18: enumerate every EM_ASYNC_JS / emscripten_sleep primitive, follow each to its callers, record evidence as file:line. Inventory taken AFTER D-1 (the legacy twins startModal / wxWasmRunNestedLoop / the popup pump no longer exist).

0. Why the class matters (the doc-19 lens)

• On-fiber parks are the strand class: a tool fiber that parks mid-body trips the stale-fiber quarantine, and its legitimate resume can be refused → the fiber never completes, the dispatch guard it holds never releases, the UI freezes (doc 19 §4).
• Entry-stack parks are the interlock-holder class: the parked chain holds wxWasmDispatchDepth (or is zeroed around the park by hand), so dispatch degrades to Paint-only until the promise settles. Recoverable — but it is the reason the quarantine/consume-once guessing layer exists at all.
• Main-loop parks that complete every tick are safe by construction (doc 13 §6c): nothing stays suspended across a dispatch.

D1–D4 give the first two classes their own scheduler contexts; the third stays as-is unless D5 is taken.

1. Inventory (14 production sites, 3 test levers)

Headline: 8 wx sites, 9 KiCad/bridge sites (counting the clipboard quartet as 4 and the ngspice pair as 2); after D-1 no site has a legacy twin — one code path per site.

#	site	file:line	parks	wake source	route
W1	wxWasmYieldUntilJs — the wait primitive (modal + nested quasi-modal)	wx evtloop.cpp:175	fiber (dialog opened from a tool action — the doc-19 case) or entry (plain handler chain)	wait-registry resolveWait	D3 — context yield
W2	wxWasmYieldToBrowser — per-frame yield	wx evtloop.cpp:292	main loop, completes every frame	rAF	safe (doc 13 §6c); scheduler-owned only if D5 is taken
W3	wxDomPopupMenuModal	wx window.cpp:723	fiber (canvas context menu runs inside a TOOL_MANAGER coroutine) or entry	wxShowContextMenu promise	D3 — same yield as W1 (wait-shaped)
W4	clipboard quartet js_{write,read,has,clear}*Clipboard	wx clipbrd.cpp:38/76/120/147	entry or fiber (copy/paste actions; SetData→:261, GetData→:331)	navigator.clipboard promise	D4 — bridge helper
W5	js_enumerateFonts	wx fontenum.cpp:33 (caller :119)	entry (font enumeration in dialog/startup paths)	Local Font Access promise	D4
K1	pcbjam_libs_request_js — symbol libs	sch_io_pcbjam_lib.cpp:58	entry (open flows, busy-gated) and fiber (lazy chooser loads; kicadLibsReload is fibered — doc 18 asymmetry 3)	kicadLibs.request promise	D4
K2	pcbjam_fp_libs_request_js — footprint libs	pcb_io_pcbjam_fp.cpp:58	same shape as K1 (board-open inline preload; fp chooser lazy)	same	D4
K3	pcbjam_3d_request_js — 3D model fetch	pcbjam_model_fetch.cpp:51	entry or fiber (3D cache EnsureModelFile: viewer open, raytracer prep, STEP export)	3D provider promise	D4
K4	js_occExportRequest — STEP export	wasm/stubs/exporter_step_stub.cpp:59	entry (export dialog flow)	occ-service worker promise	D4
K5	js_occLoadModelRequest — OCE model load	wasm/stubs/oce_plugin_stub.cpp:64	entry or fiber (3D cache load path)	occ-service worker promise	D4
K6	js_ngspice_request / js_ngspice_get_vec	wasm/stubs/sharedspice_client.cpp:60/82	entry (sim frame actions; get_vec has the known pre-existing asyncify crash)	ngspice-service worker promise	D4
K7	__wasm_main_thread_yield_ms — the nanosleep shadow	wasm/shims/nanosleep_yield.c:32	whatever main-thread stack calls sleep_for — the "anywhere" class (raytracer join loops today), and TOOL_MANAGER::RunSynchronousAction's spin loop, tool_manager.cpp:370-371 — an in-place park INSIDE a tool body, in a loop, with a nested wxYield() dispatch on top of it (identified 2026-08-07; doc 22 §10 "The tool-body park site, NAMED")	setTimeout	D4, plus a caller sweep: each sleep_for reached on the main thread is a park site of its own. The RunSynchronousAction caller is the one that BLOCKS Phase D — it kills four canvas-tool specs at D-on with the blue screen — and it moves first
T1	open-gate test park (testParkMs sleeps)	wasm/bindings/{pcbnew,eeschema,pl_editor,kicad_editor}_embind.cpp ×8	entry (deliberate)	timeout	keep — stages the open-window collisions
T2	timer park lever	wasm/bindings/timer_park.h:73	mailbox-delivered timer entry (deliberate)	timeout	keep
T3	fiber park lever	wasm/bindings/fiber_park.h:78	fiber mid-body (deliberate — stages exactly the doc-19 strand)	timeout	keep; its refusal pin flips red→green at D6

Notes:

• W1 absorbed the legacy modal/nested/popup pumps at S4+D-1; it is now the single wait primitive — and exactly the site doc 20 §3 calls out: "API is right, implementation parks in place." D3 swaps its implementation for a context yield; nothing above it changes.
• W3 is wait-shaped but bypasses the registry (it awaits the menu promise directly). D3 should route it through the same context yield as W1 — either by registering a "popup" wait or by the D4 promise helper; decided at D3, not here.
• K1/K2's fiber lane is the second half of the doc-19 exposure: a chooser's lazy lib load parks the tool fiber that owns the chooser. Any strand fix that only covers W1 leaves K1/K2 able to reproduce the same freeze.
• K7 is the only site whose caller set is open-ended (anything reaching nanosleep on the main thread). The D4 gate ("no handleSleep on a fiber stack") is what turns an unaudited new caller from a silent hazard into a loud assertion failure.

2. pthread scoping (doc 20 risk 4, settled for D1)

• Every site above parks the main browser thread's Asyncify state only. No park site exists on a worker: nanosleep_yield.c:41 branches workers to emscripten_thread_sleep (real blocking sleep — workers may block).
• The symbol-lib bridge has a second, non-Asyncify path for library pthreads: sch_io_pcbjam_lib.cpp:112 (pcbjam_libs_request_on_main) proxies the request to the main thread via emscripten_proxy_* and blocks the worker until pcbjam_libs_finish (:49) releases it; a global lock (:167-181) serializes concurrent worker loads. This path never touches Asyncify and is OUT of the context migration's scope — but D1's scheduler must not assume "all lib loads park" either: a proxied load holds no context.
• Consequence for D1: contexts are a main-thread-only concept; the scheduler registry needs no cross-thread story. The raytracer interplay (K7) is confined to "main thread yields while a worker boots" — unchanged by D1–D4.

2b. What D1 built (2026-08-05)

wasm/sched/context.{h,cpp} — the contexts every site in §1 will migrate onto, with a star topology (contexts yield to the scheduler; only the scheduler resumes) rather than libcontext's symmetric swap. That is what converts every "route" cell above from "move the park" into "move the park onto a context whose state is recorded". Nothing in §1 is wired to it yet: W1/W3 move at D3, the bridges at D4.

Sizing note for the D4 migration: contexts run 128 KB C stack + 128 KB asyncify buffer, and the layer measures its own high-water use. The D1 harness's synthetic frames cost ~34 B each — a floor, not a production figure. When each bridge in §1 moves at D4, take its deep-park high-water from the beacon and size from that; do not carry the harness number, and do not inherit libcontext's 512 K by default either.

3. What D4's assertion must cover

"No handleSleep park happens inside a fiber" (doc 20 §6 D4) must trip on: W1/W3 if D3 left a path unmigrated, W4, K1, K2, K3, K5, and any K7 caller reached from a tool coroutine. Sites T1–T3 are exempt by name (they exist to stage parks). The assertion belongs in the scheduler shim (it already owns Fibers bookkeeping and the __pendingSleepContexts list), gated to dev/test builds at D4 and promoted per D6.

4. Red spec (the other D0 deliverable)

Landed as tests/kicad/quasimodal-strand.spec.ts (pcbjam 6ab0843): open a schematic, double-click a symbol → Symbol Properties (quasi-modal on a tool fiber = W1's fiber lane), arm the parking timer while the dialog is up (so its park lands on top of the opener's open-ended park — structural overlap, not a race), click OK → the dialog must close and the wait books must balance. RED today by the doc-19 mechanism, 6/6 identical (closed=false dialogs=1 refused-resumes=1); goes green at D3. Marked test.fail() so the battery stays runnable while red — when D3 lands, Playwright flags "expected to fail but passed", forcing the flip to a plain green pin. A separate GREEN "staging" test asserts the window is real, so the pin cannot rot into vacuity.

Audit consequence recorded there: the strand reproduces on a 2-object fixture — the warm-load byte volume that dice-loads the 68/1 family is not an ingredient. Two concurrent parks suffice, which is why D3 (waits on contexts) closes this class and D5 (main as a context) is not required for it.