pcbjam/docs/features/async/23-jspi-runtime.md

23 — The JSPI runtime (current architecture)

Status: 2026-08-14 · CURRENT · supersedes the TL;DR of this directory's README ("we are not switching to JSPI" — we did, 2026-08) · lineage: 21 (park-site audit = the migration surface), 22 (the absorb plan this replaced: one owner for every switch — JSPI delivered that owner as the engine itself), doc 15 (stale-resume refusal), doc 18 (embind mutator/parker classification).

This is the reference for how suspension works now. The numbered docs 01–22 are the Asyncify-era investigation log; read them as history.

1. The shape of the runtime

Every wasm entry point that can suspend is a promising export. A suspension inside one is a plain await in an imported JS function: the engine parks that activation's native stack and returns a Promise to the JS caller. No instrumentation pass, no unwind/rewind state machine, no shared suspension register — the failure family the 01–22 docs fought (two subsystems clobbering one currData) is unrepresentable.

What JSPI does not solve, and the two shims do:

• The C spill stack is not switched per activation (emscripten #27364). Both shims apply the "green-region" discipline proven red/green by tests/apps/standalone/jspi-stack: every activation gets its own spill region and the shared __stack_pointer is swapped only at window boundaries.
• Engine re-entries are not serialized. The scheduler's resume turnstile (§3) makes them so.

2. The promising-export census — three synchronized copies

The set of promising exports is declared in THREE places that must stay in sync (a name missing from one produces a SuspendError at runtime, not a build error — see docs/debugging/DEBUG.md §3):

copy	consumer
scripts/common/jspi-exports.txt	-sJSPI_EXPORTS=@… at link (build-kicad-target.sh)
jspi-scheduler.js installExportWraps([...])	activation tracking + spill regions for the same names
tests/apps/Makefile.wasm WX_JSPI_EXPORTS	the wx test apps + races/coroutine harness links

The census is the wx KEEPALIVE entries that can park (wx_dom_event, wx_dom_mouse, wx_window_*, ProcessEvents, the three ticks), main, and pcbjam_libctx_entry (the coroutine entry export). Regenerate by grep, not from memory. The embind parkers (§5) are a fourth surface but carry their own declaration (emscripten::async()), not a census entry.

3. The scheduler/turnstile contract (jspi-scheduler.js)

Windows. A promising export's execution is a sequence of windows: the FIRST window runs synchronously from its JS caller (a real JS frame, tracked by _actStack push/pop), each RESUMED window is entered by the engine from a promise reaction (no JS frame of ours — tracked by _windowLive). The wasm executing at any moment belongs to _actStack's top when non-empty, else _windowLive.

Suspension records. Every park lands in _suspended (id → record with kind, waitKind, token, sp, suspendedAt). Wait kinds: the wx token waits (modal, nested, clipboard, font), the KiCad lib bridge (lib, fp-lib), the shim's own yields (frame, sleep, promise), and the coroutine hooks (libctx-enter = an enterer awaiting a yield, libctx = a coroutine parked on its own yield). __wxWaitDump() is a live view of all of it.

Resume turnstile. SP swaps happen only at microtask boundaries and for at most ONE activation between wasm re-entries. Ready resumes queue in _resumeReady; _pumpResume arms exactly one (SP → its region, record → _windowLive) and resolves its gate; the engine's re-entry is the only reaction on that gate. The next pump runs when that window ends — its next suspension or its completion, both observed. A window stuck armed >2 s while resumes queue is force-cleared with a beacon (a suspension bypassed the shim).

Mutator FIFO. The doc-18 mutator class (kicadCollabApply, saves, theme flips, …) must not enter wasm while a board load is in flight — the open activation is suspended mid-load and a mutator entering between its parks would mutate the board under it. The wrap queues them while kicadOpenFileBusy() is true and drains the FIFO in order, time-boxed, once it clears. Semantic exclusion; nothing engine-specific about it.

Mailbox lane. Timer/wheel callbacks queue via enqueueAfter and are delivered in order from a fresh task through the _wxWasmMailboxTick promising export; a suspension inside a delivered handler parks the tick's own activation. A throwing handler triggers containment: wx_dispatch_abandon plus resolution of the top nested/modal waits, so a parked quasi-modal is never left unresolvable.

4. libcontext: ownership, refusal, quarantine

The KiCad coroutine backend (kicad/thirdparty/libcontext/libcontext.cpp, wasm32 platform) runs each coroutine as ONE promising activation with a promise pair per switch (yielded / resume). Records are tombstones — never freed, ~48 B, censused — so every stale-handle path is refused loudly instead of corrupting memory.

Ownership rule. A COROUTINE owns exactly one record: m_callee.ctx. m_caller.ctx is BORROWED — written by jump_fcontext's symmetric protocol, it names whoever entered you (or the root). The 2026-08-13 phantom-release bug: ~CALL_CONTEXT released the borrowed caller handle; under the fiber backend that was survivable, under JSPI it killed a LIVE coroutine's record mid-slice (the "dead tools" bug — every tool dead after one dialog). Fixed twice over in db81985: the destructor releases only what it owns, and the backend REFUSES release of a running record or of any record on the current enterer chain (censused as release-of-running-ignored).

Refusal sentinel. A refused transition returns a pointer to a static INVOCATION_ARGS-shaped sentinel (FROM_ROUTINE, null destination/context) — never raw −1. coroutine.h dereferences jump returns unconditionally, and a live coroutine CAN legitimately observe a refusal (a nested-dispatch partner dying mid-flight); the old "unreachable" premise was disproven by a boot-time OOB. The doc-15 stale-resume contract also survives translation: js_libctx_resume refuses to resume a coroutine parked on a FOREIGN wait (its turnstile record's waitKind isn't libctx) — the legitimate wake is that wait's own resolution — ringing libctxRefusedResume.

Quarantine / destroy-while-parked. Releasing a coroutine parked mid-body marks the record dead, bumps deadParked, drops its turnstile record, and hands a parked enterer the sentinel so it un-hangs. A late wake for a quarantined record is dropped by the pump (never re-enter a freed body); a stray jump at the corpse gets the sentinel; double release is idempotent. Contained: the rest of the world keeps scheduling.

5. Embind call shapes (the delivery-mechanics table)

How a JS→wasm call may interact with suspension is decided at registration:

shape	suspension	semantics
plain embind function(...)	must not suspend	first park throws SuspendError (strict on Firefox ≥153)
emscripten::async() (bare)	legal	rerun hazard: embind re-executes the invoker when the awaited promise settles — observed during the migration as the triple-poke (one kicadTestFiberParkPoke() call landing three body executions). Use only for idempotent bodies, or don't.
raw KEEPALIVE export in the JSPI census	legal	one-shot: the body runs once per call, the call returns the activation's promise — the wx entry points' shape
PCBJAM_PARKER_POLICY + scheduler parker wrap	legal	async() under the hood, plus activation tracking, an 8 MB spill region (board parses are deep), and turnstile serialization — kicadOpenFile / kicadOpenFiles / kicadLibsReload

This table is why the kicadTestFiberPark* levers stayed sync-registered: neither legal shape can deliver a mid-park poke (the parker wrap would defer it — the exact race the levers exist to stage). They are manual Chromium-only probes; their contracts are pinned by the §6 battery instead.

6. The coroutine contract battery (18 cases)

tests/apps/standalone/jspi-coroutine/coroutine_jspi_test.cpp — a wx-free MiniCoro mirroring tool/coroutine.h's protocol exactly over the real libcontext. Node + browser, single-thread + pthread builds (tests/jspi/jspi-coroutine.spec.ts). What the families pin:

• Lifecycle (1, 7, 10, 11): entry runs the body exactly once to first yield; completion flips Running(); values round-trip; 48-yield stress.
• Spill-stack discipline (2, 3): locals and a 6-deep recursive frame survive suspension — the green-region proof at protocol level.
• Nesting / enterer inference (4, 5): child-in-parent routing, a parent yielding over a parked child — direction inferred from the enterer chain.
• Root bounce (6): RunMainStack runs the functor on the caller's activation and resumes with the payload (CONTINUE_AFTER_ROOT).
• wasm-EH interplay (12): yield INSIDE a catch block — the case the HoistCppCatches binaryen pass existed for, now native.
• Dispatch shape (13): resume driven from a JS timer through the wait import.
• Reclaim + ghosts (8, 14): finished activations release their JS slots and regions; a post-finish jump refuses with the SENTINEL (shape-checked).
• Release semantics (15, 16, 17, 18): mid-body release censused and never resumed; release of the RUNNING record refused (the phantom-release shape); release on the enterer chain refused; destroy-while-parked fully contained (census +1 exactly once, corpse jumps sentinel, fresh coroutines unaffected).

7. Services under emscripten 6

Emscripten 6 removed Module.mainScriptUrlOrBlob. The pthread glue now spawns its workers from _scriptName = self.location.href — for a blob-booted service worker that is the wrapper blob itself, so every pthread child re-executes the wrapper. occ-worker.js / ngspice-worker.js handle it with the em-pthread realm trick: if globalThis.name === "em-pthread", just importScripts(GLUE) and get out of the way (the glue tail self-instantiates into pthread-child mode). Without the branch the wrapper re-boots a whole service per pthread — the observed worker-spawn storm with the pool never filling.

KNOWN GAP (CDN cross-origin pthreads, editor path): boot.ts used to pin the pthread worker script via mainScriptUrlOrBlob — same-origin URL directly, cross-origin CDN base via a same-origin blob: that importScripts the CDN glue (with ACAO + CORP headers). With the option gone, the editor's cross-origin pthread spawn path has no equivalent pin; same-origin serving works. Not fixed in the cleanup — tracked here.

8. Exception policy

• wxApp::OnExceptionInMainLoop (wxwidgets/src/wasm/app.cpp): a throwing event handler must not tear down the app. The wx default exits the main loop — which reads as a silent clean shutdown mid-session. The override logs [wx-app] unhandled exception in event handler: … and returns true: the loop lives.
• JS-side containment: wx-dom.js contains rejections escaping a dispatch, and both delivery lanes' error paths call wx_dispatch_abandon() + resolve the top nested/modal waits — a throwing handler under an open quasi-modal must not strand the parked modal wait (the doc-19 family under new mechanics).
• Coroutine traps: an entry activation that rejects prints [libctx-jspi] … entry REJECTED with the stack, and the enterer receives the refusal sentinel — a trapped tool body is contained, not amplified.

9. Known gaps & upstream issues

• Firefox slow wasm tier — big promising modules run slow on FF; observed as FootprintEnumerate rows never appearing in 60 s (remote read path). Upstream #42199. The firefox leg of footprint-browse-remote is gated on it.
• Editor write bridge rot — symbol/footprint WRITE flows wedge at the New Symbol/Footprint dialog on both engines (pre-dates the migration; the web-e2e-rot 01 gap stands). Read paths are green.
• 3D raytracer engine toggle inert — the toolbar toggle does not engage the raytracer on the webgl-era wasm; pinned KNOWN-ISSUE in tests/kicad/3d-viewer-deadlock.spec.ts.

10. Migration evidence

• A/B benchmark vs the asyncify build (2026-08-14): build time / build memory / bundle size / load / open / FPS / heap — migration-evidence/jspi-vs-asyncify-bench-2026-08.md (raw data in migration-evidence/bench-data-2026-08/).
• Workflow results: migration-evidence/wf-result-11.json / wf-result-12.json (the durable spike output; the rest of the .jspi-assets/ spike tree was scratch and is gone — its ignore rule came from a global git-excludes file, not this repo's .gitignore).
• The investigation log: docs 01–22 in this directory (Asyncify-era; historical).
• The migration commits: parent 3f09a46 + e14faec + db81985 (phases 0–7, pipeline retirement, ownership fix + suite green) with 3ee174e (un-skip sweep), kicad 012d95ecb4, wxwidgets 1b5f0e31f4; the JSPI-only cleanup commit followed on experiment/jspi.