jspi: migration phases 0-7 — build knob, scheduler shim, test successor suite

Toolchain: emsdk 6.0.6 (versions.sh; cache-hash keys on it). Build knob
PCBJAM_ASYNC_BACKEND=jspi|asyncify: build-kicad-target.sh links editors with
-sJSPI + -sJSPI_EXPORTS=@scripts/common/jspi-exports.txt + --pre-js
jspi-scheduler.js (no DYNCALLS, no post-link asyncify pipeline); wx build
stamps the backend and forces clean on flip or unknown provenance;
docker/build.sh passes the knob, seeds the emscripten ports cache from the
volume every launch, jspi postprocess = patch-env-shim only.

scripts/common/shims/jspi-scheduler.js: the JSPI successor scheduler —
token-wait registry, resume turnstile (one armed resume between engine
re-entries, SP swaps only at microtask boundaries), green-region spill
stacks (16-aligned tops), S1 embind mutator FIFO lane + parker wraps, S6
shutdown, libctx integration hooks (suspend/end/quarantine + g_current
arm/clear), SuspendError attributor, lost-wake + stuck-window watchdogs,
__wxWaitDump observability.

Embind: PARKER registrations get emscripten::async() under PCBJAM_JSPI
(wasm/bindings/pcbjam_async_policy.h). nanosleep yields route via the shim.

Tests: tests/asyncify -> tests/jspi successor suite (jspi-stack red/green
shadow-stack battery, jspi-coroutine MiniCoro harness, suspend-races
semantic scenarios + __wxWaitDump books coherence); projects jspi-firefox/
jspi-chrome (asyncify-webkit retired — no JSPI in WebKit); unconditional
Firefox JSPI pref; guard-beacons -> wait-beacons (+wxScheduler/libctxJspi
families); Makefile.wasm links test apps against JSPI with the shim as a
tracked link prerequisite.

Web: WasmTool setRo await + __wxWaitDump forensics, open-flow contained
promise, scheduler-shim.test.ts retargeted (8 green).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NDeBaKKhQztd8KiVtHuyXr

docker/build.sh

@@ -177,6 +177,16 @@ docker compose -f docker/docker-compose.yml up -d --build
 # This avoids the timestamp mismatch cycle that caused full rebuilds every time.
 # Transferred files get current container time, so make detects them correctly.
 kw_stage container-sync
+# Re-seed the emscripten ports cache from the persistent volume: /emsdk lives
+# in the container layer, so any image-context edit recreates the container
+# and wipes the cache — and the in-container github fetch is flaky. Seeds are
+# staged once into the kicad-build-cache volume (emcache/ports); this copy
+# survives every recreation. No-op when the staging dir is absent.
+docker compose -f docker/docker-compose.yml exec kicad-wasm-builder bash -c \
+    'if [ -d /workspace/build-wasm/emcache/ports ]; then \
+        mkdir -p /emsdk/upstream/emscripten/cache/ports && \
+        cp -a /workspace/build-wasm/emcache/ports/. /emsdk/upstream/emscripten/cache/ports/ && \
+        echo "seeded emscripten ports cache from volume"; fi' || true
 echo "Syncing source code to container..."
 # rsync into the macOS-backed volume intermittently hits transient VirtioFS glitches:
 # temp-file rename failures (exit 23) or vanished-source files (exit 24, harmless).
@@ -244,6 +254,7 @@ compile_app() {
     # for headless CLIs like kicad_tools — the gl1 shim needs glm).
     docker compose -f docker/docker-compose.yml exec -e EMSDK=/emsdk \
         -e BUILD_3D_VIEWER="${BUILD_3D_VIEWER:-}" \
+        -e PCBJAM_ASYNC_BACKEND="${PCBJAM_ASYNC_BACKEND:-}" \
         kicad-wasm-builder \
         "/workspace/scripts/kicad/build-${app}.sh" "${ARGS[@]}"
 
@@ -283,6 +294,15 @@ postprocess_app() {
         return 0
     fi
 
+    # JSPI backend: the app links with the real in-container tools and needs no
+    # dyncall shims (no -sDYNCALLS), no host finalize, and no asyncify pass —
+    # the scheduler ships as a --pre-js at link. Only the ENV merge shim remains.
+    if [ "${PCBJAM_ASYNC_BACKEND:-asyncify}" = "jspi" ]; then
+        kw_stage env-shim
+        node ./scripts/common/patch-env-shim.mjs "${out_dir}/${app}.js"
+        return 0
+    fi
+
     # Inject dynCall shims (fixes "dynCall_* is not defined" errors in Emscripten 4.x)
     kw_stage dyncall-shims
     ./scripts/common/inject-dyncall-shims.sh "${out_dir}/${app}.js"

docker/docker-compose.yml

@@ -20,6 +20,14 @@ services:
           cpus: '${KICAD_DOCKER_CPUS:-10}'
           memory: ${KICAD_DOCKER_MEM:-32G}
 
+    # Emscripten cache on the PERSISTENT build volume: /emsdk lives in the
+    # container layer, so every container recreation (any image-context edit
+    # rebuilds the image) wiped the ports/sysroot cache and forced re-downloads
+    # through a flaky in-container fetcher. On the volume it survives, and the
+    # host can pre-seed port tarballs into emcache/ports/.
+    environment:
+      EM_CACHE: /workspace/build-wasm/emcache
+
     volumes:
       # Host source mounted read-only at staging location
       # (rsync'd to /workspace on container start to fix macOS timestamp issues)