[Feature] purwc: a single module compilation worker - purs-wasm orchestrate mode and nix-style cache store

.githooks/pre-push

@@ -20,6 +20,12 @@ if ! command -v pnpm >/dev/null 2>&1; then
   exit 1
 fi
 
+# The DEFAULT build is now orchestrate (ADR 0042): the compiler test suite builds its fixtures through
+# the `purwc` worker against `$PURS_WASM_STORE`. Point it at a persistent repo-local store so the
+# library closure (Prelude, …) is compiled once and reused across test programs (and across pushes),
+# instead of a cold orchestrate per program. Respects an externally-set store.
+export PURS_WASM_STORE="${PURS_WASM_STORE:-$PWD/.purs-wasm-store}"
+
 for target in compiler binaryen; do
   echo "[pre-push] $target: compile → test → check"
   pnpm -F "$target" run compile

.github/workflows/bench.yaml

@@ -59,7 +59,7 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
-      # The bench scripts shell out to `purs-wasm/index.dev.js`, which imports the compiled
+      # The bench scripts shell out to `purs-wasm/index.js`, which imports the compiled
       # CLI at `output/PursWasm.CLI.Main` (the `purs-wasm` package — `spago build -p purs-wasm`
       # also builds its `compiler` dependency) and merges `runtime/runtime.wasm` + the ulib
       # lib's `foreign.wasm`s, so build the runtime first. Then compile the ulib lib (ADR
@@ -69,28 +69,43 @@ jobs:
       # it with a `bench` build first.
       - name: Build the CLIs, runtime, and ulib lib
         run: |
-          # `spago build -p ulib-tooling` builds the maintainer CLI AND its `purs-wasm` dependency
-          # (the user `build` CLI), so both index.dev.js entries resolve.
+          # Build the index.js entry points. Since the cli-lib extraction (ADR 0038),
+          # `ulib-tooling` depends on `cli-lib`, not on `purs-wasm`, so it no longer drags in the
+          # user `build` CLI — `purs-wasm` (which `purs-wasm/index.js` imports as
+          # `output/PursWasm.CLI.Main`) must be built explicitly. `purwc` too: the bench builds run the
+          # DEFAULT orchestrate mode (ADR 0042), which spawns the `purwc` worker as a subprocess. Each
+          # `spago build` also builds its `compiler` dependency.
+          spago build -p purs-wasm
+          spago build -p purwc
           spago build -p ulib-tooling
           pnpm -F ./compiler run build:runtime
           spago build -p bench --output bench/output
-          node ./ulib-tooling/index.dev.js install
+          node ./ulib-tooling/index.js install
           # Assert the shadows are in sync with the *pinned* package set (spago.lock) and that
           # ulib/compat.json is up to date (ADR 0028/0029 release record). Fails if a shadow is stale
           # (the set bumped that package past the shadow's major.minor) or compat.json drifted —
           # without it the bench would silently measure the un-specialized registry-fallback path.
-          node ./ulib-tooling/index.dev.js compat --check
+          node ./ulib-tooling/index.js compat --check
 
       # graph.sh builds all three backends + renders the 7 algorithm graphs;
-      # count-state-graph.sh / count-effect-graph.sh / count-run-graph.sh add the State-,
-      # Effect-, and Run/Free-monad graphs; curry-graph.sh adds the curry-vs-uncurry tax graph.
+      # count-state-graph.sh / count-effect-graph.sh add the State- and Effect-monad graphs;
+      # curry-graph.sh adds the curry-vs-uncurry tax graph.
+      #
+      # count-run-graph.sh (purescript-run / Free-monad STATE) is DISABLED: the `CountRun` wasm
+      # build succeeds but traps at runtime with `illegal cast`. Root cause is a backend codegen
+      # limitation, NOT a regression — `Control.Monad.Free` encodes its existential with
+      # `unsafeCoerce` (a no-op on JS, but on wasm-GC the value's static type — a `{type,value}`
+      # record — and its dynamic type — the actual `Free` node struct — diverge, so the record
+      # projection's `ref.cast` traps). The effectful `runBaseEffect` path collapses the interpreter
+      # and works (examples-run runs fine); only the pure `Run.State` + `extract` loop in `CountRun`
+      # leaves a runtime Free interpreter that hits the trapping cast. Re-enable once the backend
+      # supports the `unsafeCoerce` existential pattern (or fully collapses the pure interpreter).
       - name: Render benchmark graphs
         working-directory: bench
         run: |
           bash ./graph.sh
           bash ./count-state-graph.sh
           bash ./count-effect-graph.sh
-          bash ./count-run-graph.sh
           bash ./curry-graph.sh
 
       - name: Comparison tables → run summary

.github/workflows/ci.yaml

@@ -38,12 +38,28 @@ jobs:
     needs: changes
     if: needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
+    # The DEFAULT build is now orchestrate (ADR 0042): the compiler leg's e2e/bin tests build their
+    # fixtures through the `purwc` worker against this content-addressed store. Sharing it across the
+    # run means the library closure (Prelude, …) is compiled once and every later test program hits it.
+    env:
+      PURS_WASM_STORE: ${{ github.workspace }}/.purs-wasm-store
     strategy:
       matrix:
         target: [compiler, binaryen, purs-wasm, ulib-tooling]
     steps:
       # Setup Nix envirionment
       - uses: actions/checkout@v5
+      # Persist the store across runs so even the first test program hits a warm library closure. Keyed
+      # on the codegen-affecting sources (the compiler / cli-lib key logic / worker / lib) + the purs
+      # pin: any change to them re-fills a fresh store, so a stale artifact can never be served. No
+      # restore-keys — a partial/older store is a correctness risk, not just a slower build. Only the
+      # compiler leg builds wasm, so only it caches (avoids an empty-store leg racing to save the key).
+      - name: Cache purs-wasm store
+        if: matrix.target == 'compiler'
+        uses: actions/cache@v4
+        with:
+          path: .purs-wasm-store
+          key: ${{ runner.os }}-purs-wasm-store-${{ hashFiles('compiler/src/**', 'cli-lib/src/**', 'purwc/src/**', 'ulib/**', 'flake.lock', 'spago.lock') }}
       # v30 ships Nix >= 2.18, required by the pinned nixos-25.11 nixpkgs.
       - uses: cachix/install-nix-action@v30
         with:

.github/workflows/nightly.yaml

@@ -81,11 +81,20 @@ jobs:
           printf 'export const version = "v%s"\n' "${{ steps.ver.outputs.version }}" > src/PursWasm/CLI/Version.js
 
       # `ignore-scripts` (above) also suppresses `prepack` on `npm publish`, so assemble the package
-      # — bundle/ + runtime/ + lib/ — with an explicit `npm run`, which is not suppressed.
+      # — bundle/ + purwc/ + runtime/ + lib/ — with an explicit `npm run`, which is not suppressed.
       - name: Assemble package
         working-directory: purs-wasm
         run: npm run prepack
 
+      # Smoke-test the ASSEMBLED package before publishing: install the tarball into a throwaway
+      # project and run a real DEFAULT (orchestrate) build. The unit `test` above never invokes
+      # `build`, so it cannot catch a runtime asset (purwc / lib / runtime) missing from the package —
+      # this step does (it would have caught the published default build failing with "Cannot find
+      # module …/purwc/index.js" when orchestrate became the default, ADR 0042).
+      - name: Smoke build (published package)
+        working-directory: purs-wasm
+        run: node scripts/smoke.mjs
+
       # `--tag nightly` keeps the stable `latest` tag in place; OIDC trusted publishing needs no token.
       - name: Publish nightly
         working-directory: purs-wasm

.gitignore

@@ -2,6 +2,10 @@
 /output
 /output-es
 /output-wasm
+/output-purwc
+# ADR 0042/0040: the local content-addressed store the test suite / pre-push hook share via
+# $PURS_WASM_STORE (so the library closure compiles once across test programs).
+/.purs-wasm-store
 /dist
 # generated from runtime/runtime.wat by `npm run build:runtime` (chained into test:e2e)
 /runtime/runtime.wasm
@@ -29,10 +33,15 @@ compiler/test/e2e-fixtures-out/
 
 #
 _draft
+.claude-session
 
 # purs-wasm npm bundle build artifacts
 purs-wasm/bundle/
 purs-wasm/.build/
+purs-wasm/_build/
+purs-wasm/_build-purwc/
+# the bundled `purwc` worker prepack ships inside the package (NOT the top-level `purwc/` workspace)
+purs-wasm/purwc/
 purs-wasm/runtime/
 purs-wasm/lib/
 purs-wasm/*.tgz

bench/count-effect-graph.sh

@@ -14,7 +14,7 @@ spago build -p bench --output bench/output
 purs-backend-es build --corefn-dir bench/output --output-dir bench/output-js-es --int-tags
 # 3. our wasm backend, in its OWN output dir (see count-state-graph.sh: the shared `output-wasm` is
 # `Bench.Main`'s, and the comparison-tables CI step re-runs the .mjs without rebuilding)
-node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-count-effect -e CountEffect
+node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-count-effect -e CountEffect
 
 cd "$here"
 node count-effect.mjs

bench/count-effect.mjs

@@ -9,7 +9,7 @@
 //   * js-es    : purs-backend-es (output-js-es, the optimized JS people ship)
 //
 //   build:  spago build -p bench --output bench/output
-//           node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-count-effect -e CountEffect
+//           node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-count-effect -e CountEffect
 //           purs-backend-es build --corefn-dir ./bench/output --output-dir ./bench/output-js-es --int-tags
 //   run:    node bench/count-effect.mjs
 //

bench/count-run-graph.sh

@@ -13,7 +13,7 @@ spago build -p bench --output bench/output
 # 2. the optimized JS backend (js-es)
 purs-backend-es build --corefn-dir bench/output --output-dir bench/output-js-es --int-tags
 # 3. our wasm backend, in its OWN output dir (count-run.mjs reads ./output-wasm-run)
-node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-run -e CountRun
+node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-run -e CountRun
 
 cd "$here"
 node count-run.mjs

bench/count-run.mjs

@@ -8,7 +8,7 @@
 //   * js-es    : purs-backend-es (output-js-es, the optimized JS people ship)
 //
 //   build:  spago build -p bench --output bench/output
-//           node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-run -e CountRun
+//           node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-run -e CountRun
 //           purs-backend-es build --corefn-dir ./bench/output --output-dir ./bench/output-js-es --int-tags
 //   run:    node bench/count-run.mjs
 //

bench/count-state-graph.sh

@@ -15,7 +15,7 @@ purs-backend-es build --corefn-dir bench/output --output-dir bench/output-js-es
 # `Bench.Main`): every bench builds a different entry, and the comparison-tables CI step re-runs the
 # .mjs without rebuilding — a shared dir would leave whichever bench built last, so count-state.mjs
 # would read the wrong wasm (no `countTo` export → "wasmCheck is not a function").
-node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-count-state -e CountState
+node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-count-state -e CountState
 
 cd "$here"
 node count-state.mjs

bench/count-state.mjs

@@ -9,7 +9,7 @@
 //   * js-es    : purs-backend-es (output-js-es, the optimized JS people ship)
 //
 //   build:  spago build -p bench --output bench/output
-//           node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-count-state -e CountState
+//           node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-count-state -e CountState
 //           purs-backend-es build --corefn-dir ./bench/output --output-dir ./bench/output-js-es --int-tags
 //   run:    node bench/count-state.mjs
 //

bench/curry-graph.sh

@@ -18,7 +18,7 @@ purs-backend-es build --corefn-dir bench/output --output-dir bench/output-js-es
 done
 # 3. our wasm backend, in its OWN output dir (see count-state-graph.sh: the shared `output-wasm` is
 # `Bench.Main`'s, and the comparison-tables CI step re-runs the .mjs without rebuilding)
-node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-curry -e BenchCurry
+node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-curry -e BenchCurry
 
 cd "$here"
 node curry.mjs

bench/curry.mjs

@@ -8,7 +8,7 @@
 //   * js-es    : purs-backend-es (output-js-es, the optimized JS people ship)
 //
 //   build:  spago build -p bench --output bench/output
-//           node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-curry -e BenchCurry
+//           node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-curry -e BenchCurry
 //           purs-backend-es build --corefn-dir ./bench/output --output-dir ./bench/output-js-es --int-tags
 //   run:    node bench/curry.mjs
 //

bench/graph.sh

@@ -18,7 +18,7 @@ purs-backend-es build --corefn-dir bench/output --output-dir bench/output-js-es
   f="${f#./}"; mkdir -p "bench/output-js-es/$(dirname "$f")"; cp "bench/output/$f" "bench/output-js-es/$f"
 done
 # 3. our wasm backend
-node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm -e Bench.Main
+node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm -e Bench.Main
 
 cd "$here"
 node graph.mjs

bench/package.json

@@ -3,9 +3,9 @@
   "type": "module",
   "scripts": {
     "build:ps": "cd .. && spago build -p bench --output bench/output",
-    "build:wasm:main": "cd .. && node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm -e Bench.Main --force",
-    "build:wasm:count-effect": "cd .. && node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-count-effect -e CountEffect --force",
-    "build:wasm:curry": "cd .. && node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm-curry -e BenchCurry --force",
+    "build:wasm:main": "cd .. && node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm -e Bench.Main --force",
+    "build:wasm:count-effect": "cd .. && node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-count-effect -e CountEffect --force",
+    "build:wasm:curry": "cd .. && node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm-curry -e BenchCurry --force",
     "build:wasm": "npm run build:wasm:main && npm run build:wasm:count-effect && npm run build:wasm:curry",
     "build:wasm:base": "npm run build:wasm",
     "build": "npm run build:ps && npm run build:wasm",

bench/snapshot.sh

@@ -10,7 +10,7 @@ here="$(cd "$(dirname "$0")" && pwd)"
 cd "$here/.."
 
 spago build -p bench --output bench/output
-node ./purs-wasm/index.dev.js build -I ./bench/output -O ./bench/output-wasm -e Bench.Main
+node ./purs-wasm/index.js build -I ./bench/output -O ./bench/output-wasm -e Bench.Main
 
 cd "$here"
 stamp="$(date +%Y%m%d-%H%M%S)"

binaryen/src/Binaryen.js

@@ -298,6 +298,13 @@ export const addFunctionExportImpl =
 // cross-module function export, so the now-redundant export no longer pins the function (ADR 0037).
 export const removeExportImpl = (mod) => (externalName) => () => mod.removeExport(externalName);
 
+// Remove many exports in one flat JS loop. The orchestrate path over-exports every module's bindings
+// (thousands for a self-host build), so a PureScript `for_ … removeExport` builds an Effect bind chain
+// thousands deep and overflows the stack; the loop belongs in JS.
+export const removeExportsImpl = (mod) => (names) => () => {
+  for (let i = 0; i < names.length; i++) mod.removeExport(names[i]);
+};
+
 // Set the module's start function (run automatically at instantiation).
 export const setStartImpl = (mod) => (fn) => () => mod.setStart(fn);
 
@@ -322,6 +329,14 @@ export const optimizeImpl = (mod) => () => mod.optimize();
 // cost of re-optimising the whole merged module (ADR 0037 Phase 3).
 export const runPassesImpl = (mod) => (passes) => () => mod.runPasses(passes);
 
+// The global optimize / shrink levels `mod.optimize()` reads (Binaryen has no per-module setting).
+// `-O3` is optimize level 3 / shrink level 0. Used post-merge to fully DCE the orchestrate path's
+// over-exported cross-module instance code (a cheap pass leaves dead foreign imports — ADR 0042).
+export const setOptimizeLevelImpl = (level) => () => binaryen.setOptimizeLevel(level);
+export const setShrinkLevelImpl = (level) => () => binaryen.setShrinkLevel(level);
+export const getOptimizeLevelImpl = () => binaryen.getOptimizeLevel();
+export const getShrinkLevelImpl = () => binaryen.getShrinkLevel();
+
 // --- Validation & emission --------------------------------------------------
 
 export const validateImpl = (mod) => () => mod.validate() !== 0;

binaryen/src/Binaryen.purs

@@ -67,11 +67,16 @@ module Binaryen
   , globalSet
   , optimize
   , runPasses
+  , setOptimizeLevel
+  , setShrinkLevel
+  , getOptimizeLevel
+  , getShrinkLevel
   , validate
   , emitText
   , emitBinary
   , readBinary
   , removeExport
+  , removeExports
   -- Wasm GC
   , HeapType
   , TypeBuilder
@@ -591,6 +596,26 @@ foreign import runPassesImpl :: Module -> Array String -> Effect Unit
 runPasses :: Module -> Array String -> Effect Unit
 runPasses = runPassesImpl
 
+foreign import setOptimizeLevelImpl :: Int -> Effect Unit
+foreign import setShrinkLevelImpl :: Int -> Effect Unit
+foreign import getOptimizeLevelImpl :: Effect Int
+foreign import getShrinkLevelImpl :: Effect Int
+
+-- | The global optimize / shrink levels Binaryen's `optimize` (and pass pipeline) reads. `-O3` is
+-- | optimize level 3, shrink level 0; the defaults are 2 / 1. Global to the Binaryen instance, so a
+-- | caller that changes them for one `optimize` should restore them after (see `getOptimizeLevel`).
+setOptimizeLevel :: Int -> Effect Unit
+setOptimizeLevel = setOptimizeLevelImpl
+
+setShrinkLevel :: Int -> Effect Unit
+setShrinkLevel = setShrinkLevelImpl
+
+getOptimizeLevel :: Effect Int
+getOptimizeLevel = getOptimizeLevelImpl
+
+getShrinkLevel :: Effect Int
+getShrinkLevel = getShrinkLevelImpl
+
 foreign import validateImpl :: Module -> Effect Boolean
 
 -- | Validate the module; `true` means it is well-formed.
@@ -618,6 +643,13 @@ readBinary = readBinaryImpl
 
 foreign import removeExportImpl :: Module -> String -> Effect Unit
 
+-- | Remove many exports in one flat JS loop — stack-safe over the thousands of cross-module exports an
+-- | orchestrate self-host build produces (a PureScript `for_ … removeExport` overflows the stack).
+foreign import removeExportsImpl :: Module -> Array String -> Effect Unit
+
+removeExports :: Module -> Array String -> Effect Unit
+removeExports = removeExportsImpl
+
 -- | Remove an export by its external name (internalise it). After `wasm-merge` resolves a
 -- | cross-module function export, removing it lets the optimiser DCE the function if now unused.
 removeExport :: Module -> String -> Effect Unit

cli-lib/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "cli-lib",
+  "type": "module",
+  "scripts": {
+    "compile": "spago build -p cli-lib",
+    "test:unit": "spago test -p cli-lib --monochrome",
+    "test": "npm run test:unit",
+    "format": "purs-tidy format-in-place src test",
+    "check": "purs-tidy check src test"
+  }
+}