@napi-rs/cli 3.10.1 → 3.10.2

package/src/api/__tests__/templates.spec.ts

@@ -1005,6 +1005,124 @@ function initializationRollbackBody(code: string): string {
   return code.slice(deferredStart, code.indexOf('throw error', deferredStart))
 }
 
+/**
+ * The body of `__startWasiDisposal`, sliced so that "the drain runs on the
+ * disposal path" cannot be satisfied by a call somewhere else in the file.
+ */
+function disposalStartBody(code: string): string {
+  const start = code.indexOf(DISPOSAL_START_SIGNATURE)
+  return start === -1 ? '' : code.slice(start, code.indexOf('\n}', start))
+}
+
+const DISPOSAL_START_SIGNATURE = 'function __startWasiDisposal() {'
+
+/**
+ * `napi_async_work` is the one thing the settlement barrier above does not
+ * cover. The eager loaders drain it from the shared prelude; the
+ * deferred/workerd loader carries its own per-instance lifecycle and drains it
+ * there, so both are asserted — just against different function names.
+ */
+const eagerWasiLoaderCases = wasiLoaderCases.filter(({ code }) =>
+  code.includes(EAGER_ROLLBACK_SIGNATURE),
+)
+const deferredWasiLoaderCases = wasiLoaderCases.filter(
+  ({ code }) => !code.includes(EAGER_ROLLBACK_SIGNATURE),
+)
+
+test('every WASI loader case is either eager or deferred', (t) => {
+  t.is(
+    eagerWasiLoaderCases.length + deferredWasiLoaderCases.length,
+    wasiLoaderCases.length,
+  )
+  t.true(deferredWasiLoaderCases.length >= 2)
+})
+
+for (const { name, code } of deferredWasiLoaderCases) {
+  test(`deferred WASI loader drains outstanding async work before teardown: ${name}`, (t) => {
+    t.true(
+      code.includes('napi_wasm_async_work_pending'),
+      'the deferred loader instantiates the same async-work plugin, so it strands the same work',
+    )
+    t.true(
+      code.includes('napi_wasm_cancel_pending_async_work'),
+      'threadless work is always queued rather than executing, so cancellation is what bounds the wait',
+    )
+    t.regex(
+      code,
+      /typeof __pending !== 'function' \|\|\s*typeof __cancelPending !== 'function'/,
+      'loader must feature-detect both exports',
+    )
+    // Per instance, from that instance's own exports: two instances have
+    // separate registries and must not wait on each other.
+    t.true(
+      code.includes('__drainInstanceAsyncWork(__napiInstance)'),
+      'the drain must read the disposing instance, not a module-global one',
+    )
+    // Both teardown paths destroy the environment those completions need.
+    const disposal = code.slice(
+      code.indexOf('const __runInstanceDisposal'),
+      code.indexOf('let __instanceDisposePromise'),
+    )
+    t.true(
+      disposal.includes('__drainInstanceAsyncWork'),
+      'per-instance disposal must drain outstanding async work',
+    )
+    t.true(
+      initializationRollbackBody(code).includes('__drainInstanceAsyncWork'),
+      'the initialization-failure path must drain it too',
+    )
+  })
+}
+
+test('the eager loader cases are the ones that share the disposal prelude', (t) => {
+  // Guards the filter above: a prelude change that stopped emitting the eager
+  // rollback would silently empty the loop below instead of failing.
+  t.true(eagerWasiLoaderCases.length >= 4)
+})
+
+for (const { name, code } of eagerWasiLoaderCases) {
+  test(`WASI loader drains outstanding async work before teardown: ${name}`, (t) => {
+    t.true(
+      code.includes('napi_wasm_async_work_pending'),
+      'loader must poll the addon for outstanding async work; nothing about it is observable from JavaScript in a threaded build',
+    )
+    t.true(
+      code.includes('napi_wasm_cancel_pending_async_work'),
+      'loader must cancel work that has not started, or disposal waits for the whole queue instead of only what is running',
+    )
+    // Both exports are optional, exactly like the settlement handshake: an
+    // addon built against a napi crate that predates them must keep loading and
+    // disposing as it does today.
+    t.regex(
+      code,
+      /typeof pending !== 'function' \|\| typeof cancelPending !== 'function'/,
+      'loader must feature-detect both exports',
+    )
+    // The wait is a real referenced timer, not a macrotask spin: the addon is
+    // polled, so a zero-delay turn would burn the loop instead of yielding it.
+    t.true(
+      code.includes(
+        '__scheduleTimer(resolve, __WASI_ASYNC_WORK_POLL_INTERVAL_MS)',
+      ),
+      'the async-work wait must yield with a real timer',
+    )
+    t.true(
+      disposalStartBody(code).includes('__drainWasiAsyncWork'),
+      'disposal must drain outstanding async work',
+    )
+    // Ordering is the whole point: the completion callbacks run addon code, and
+    // the barrier, `Context.destroy()` and the termination each take that away.
+    t.false(
+      disposalStartBody(code).includes('__prepareWasmEnvCleanup'),
+      'the async-work drain must run before the barrier, not beside it',
+    )
+    t.true(
+      initializationRollbackBody(code).includes('__drainWasiAsyncWork'),
+      'initialization rollback tears down the same things and needs the same drain',
+    )
+  })
+}
+
 // The loaders order their own teardown barrier-then-destroy, but the emnapi
 // context is a live object: an embedder or test harness holding it, or emnapi's
 // own `beforeExit` auto-destroy on a host where `suppressDestroy()` is absent,

package/src/api/templates/load-wasi-template.ts

@@ -167,6 +167,7 @@ let __emnapiWasmEnvCleanupRan = false
 let __emnapiWasmEnvCleanupDrained = false
 let __emnapiWasmEnvCleanupDrainPromise
 let __wasiDisposed = false
+let __wasiAsyncWorkDrainPromise
 let __wasiDisposePromise
 let __completeWasiDisposal = function () {}
 // Overridden by loader flavors that have a last-resort reclaim for a rollback
@@ -291,6 +292,24 @@ const __scheduleMacrotask = (function () {
   }
 })()
 
+// A real, *referenced* timer, for waits that must let the whole host make
+// progress between looks — the async-work drain polls the addon rather than
+// interleaving with the @emnapi/core dispatch, so a zero-delay macrotask there
+// would spin the loop instead of yielding it. Falls back to the macrotask
+// scheduler on a host without timers.
+function __scheduleTimer(callback, delay) {
+  const setTimer = globalThis.setTimeout
+  if (typeof setTimer !== 'function') {
+    __scheduleMacrotask(callback)
+    return
+  }
+  try {
+    setTimer(callback, delay)
+  } catch {
+    __scheduleMacrotask(callback)
+  }
+}
+
 // Turns to wait for while the addon still reports queued settlements. Reaching
 // zero is the only success. A counter still nonzero at this bound rejects the
 // disposal as retryable (\`ERR_NAPI_WASI_CLEANUP_PENDING\`) rather than
@@ -491,6 +510,135 @@ function __keepEventLoopAliveUntil(work) {
   )
 }
 
+// How often to re-read \`napi_wasm_async_work_pending\` while waiting. The wait
+// ends when the addon reports zero, so this only decides how promptly disposal
+// notices — not how long it waits.
+const __WASI_ASYNC_WORK_POLL_INTERVAL_MS = 1
+
+/**
+ * Settles this addon's outstanding \`napi_async_work\` before the teardown that
+ * would strand it.
+ *
+ * \`napi_prepare_wasm_env_cleanup\` does not cover async work, and nothing about
+ * it is observable from JavaScript: the threadless archive resolves
+ * \`napi_*_async_work\` through the \`@emnapi/core\` plugins, but the threaded one
+ * links the C \`async_work.c\` on the uv threadpool, so there the wasm neither
+ * imports nor exports those symbols and the only brackets a loader could watch
+ * (\`_emnapi_ctx_*_waiting_request_counter\`) are shared with threadsafe
+ * functions. The addon is the one place both flavors go through, so it answers
+ * for both, through the same kind of handshake the settlement drain uses:
+ *
+ *   - \`napi_wasm_cancel_pending_async_work()\` cancels what no thread has
+ *     started. Those completion callbacks run with \`napi_cancelled\`, which
+ *     napi-rs turns into a promise rejected with an \`AbortError\`.
+ *   - \`napi_wasm_async_work_pending()\` counts what is still owed a completion
+ *     callback. Work already executing refuses cancellation and stays counted
+ *     until it finishes normally — which it can, because this runs before the
+ *     barrier, before \`Context.destroy()\` and before anything is terminated.
+ *
+ * Both exports are optional: an addon built against a napi crate that predates
+ * them drains nothing and keeps the previous behavior, exactly as the
+ * \`napi_wasm_env_cleanup_pending\` handshake degrades.
+ *
+ * Returns nothing when there is nothing outstanding, which keeps disposal
+ * synchronous in the common case. The promise it returns otherwise never
+ * rejects.
+ *
+ * The wait has no deadline, and that is the point: giving up would destroy the
+ * environment with a completion callback still owed, which is the stranding
+ * this exists to prevent. A task whose \`execute\` never returns already keeps an
+ * *undisposed* process alive in exactly the same way, so disposal inherits that
+ * rather than inventing a bound it cannot honor.
+ *
+ * Safe to call from inside a completion callback, which is reachable: settling
+ * a task runs addon code that can re-enter JavaScript — a setter on the value
+ * being handed back, a threadsafe-function callback — and that JavaScript can
+ * call \`dispose()\`. Two things make it terminate rather than wait on itself:
+ *
+ *   - The addon keeps a work registered until its completion callback
+ *     *finishes*, so the count read here is at least one and this takes the
+ *     polling path instead of declaring the environment drained and tearing it
+ *     down from inside the frame that is still settling a promise.
+ *   - The poll is a timer, so it cannot run until the callback has returned to
+ *     the host — by which time that work has left the registry. The count the
+ *     next poll reads is the one taken after the callback finished.
+ *
+ * \`__disposeWasiBinding\` hands every caller the same in-flight promise, so the
+ * nested call joins this disposal rather than starting a second one.
+ */
+function __drainWasiAsyncWork() {
+  if (__wasiAsyncWorkDrainPromise !== undefined) {
+    return __wasiAsyncWorkDrainPromise
+  }
+  const exports = __napiInstance?.exports
+  const pending = exports?.napi_wasm_async_work_pending
+  const cancelPending = exports?.napi_wasm_cancel_pending_async_work
+  if (typeof pending !== 'function' || typeof cancelPending !== 'function') {
+    return
+  }
+
+  const readPending = () => {
+    try {
+      return pending()
+    } catch (error) {
+      // A trap is the only way this call fails: it reads a counter and cannot
+      // allocate or call back into JavaScript. A trapped instance can no longer
+      // run anything, so its outstanding work is unreachable by definition —
+      // there is nothing left to wait for, and refusing to dispose would only
+      // keep a dead instance and its stuck counter alive. Best-effort here is
+      // the honest answer, and it is what disposal did before this drain
+      // existed.
+      //
+      // Only a trap. Anything else means the export is not what this loader
+      // thinks it is, which is a defect worth surfacing rather than disposing
+      // over.
+      if (error instanceof globalThis.WebAssembly.RuntimeError) {
+        return 0
+      }
+      throw error
+    }
+  }
+
+  if (!readPending()) {
+    return
+  }
+  try {
+    cancelPending()
+  } catch {
+    // Cancellation is an optimization: it bounds the wait by the work already
+    // executing. Failing it only means waiting for the whole queue instead.
+  }
+  if (!readPending()) {
+    return
+  }
+
+  const drainPromise = __keepEventLoopAliveUntil(
+    (async () => {
+      while (readPending()) {
+        await new Promise((resolve) => {
+          __scheduleTimer(resolve, __WASI_ASYNC_WORK_POLL_INTERVAL_MS)
+        })
+      }
+    })(),
+  ).then(
+    () => {
+      __wasiAsyncWorkDrainPromise = undefined
+    },
+    (error) => {
+      // A wait that could not run is not a wait that finished. The only way
+      // here is a host whose timers and macrotask primitives all refuse, and
+      // the work is still outstanding — reporting success would destroy the
+      // environment over it, which is the stranding this exists to prevent.
+      // Reject instead: disposal stays retryable, and the context is not
+      // destroyed. Clearing the memo first is what makes the retry re-run this.
+      __wasiAsyncWorkDrainPromise = undefined
+      throw error
+    },
+  )
+  __wasiAsyncWorkDrainPromise = drainPromise
+  return drainPromise
+}
+
 /**
  * \`@emnapi/wasi-threads\` counts a worker exit as expected only when its own
  * thread manager performed the termination. A bare \`worker.terminate()\` reaches
@@ -572,7 +720,7 @@ function __continueWasiDisposal() {
   return __finishWasiDisposal()
 }
 
-function __startWasiDisposal() {
+function __cleanUpWasmEnvForWasiDisposal() {
   // Run the pre-teardown barrier, then let the settlements it queued actually
   // reach JavaScript, and only then destroy the environment. Doing these two
   // back to back is what strands them.
@@ -584,6 +732,21 @@ function __startWasiDisposal() {
   return __continueWasiDisposal()
 }
 
+function __startWasiDisposal() {
+  // Outstanding \`napi_async_work\` goes first, while the environment is still
+  // completely live: the completion callbacks run addon code, and everything
+  // after this point takes that away from them — the barrier shuts the async
+  // runtime down, \`Context.destroy()\` stops JavaScript calls, and terminating
+  // the pool threads removes what would have reported the work finished.
+  const asyncWorkResult = __drainWasiAsyncWork()
+  if (__isThenable(asyncWorkResult)) {
+    return Promise.resolve(asyncWorkResult).then(
+      __cleanUpWasmEnvForWasiDisposal,
+    )
+  }
+  return __cleanUpWasmEnvForWasiDisposal()
+}
+
 /**
  * Disposes this generated WASI binding.
  *
@@ -725,29 +888,60 @@ function __retainFailedWasiRollback(cleanupErrors) {
  * bug with no upper bound, while the retained bookkeeping is bounded by the page.
  */
 function __rollbackWasiInitialization() {
-  const cleanupErrors = []
-  let drainResult
-  let settlementsUnreached = false
+  // The environment teardown this rollback performs, kept nested so it cannot
+  // be reached without the async-work drain below running first.
+  function __rollbackWasmEnvForWasiInitialization() {
+    const cleanupErrors = []
+    let drainResult
+    let settlementsUnreached = false
+    try {
+      __prepareWasmEnvCleanup()
+      drainResult = __drainWasmEnvCleanup()
+    } catch (cleanupError) {
+      cleanupErrors.push(cleanupError)
+      settlementsUnreached = true
+    }
+    if (__isThenable(drainResult)) {
+      return Promise.resolve(drainResult).then(
+        () => __destroyContextForWasiRollback(cleanupErrors),
+        (cleanupError) => {
+          cleanupErrors.push(cleanupError)
+          return __retainFailedWasiRollback(cleanupErrors)
+        },
+      )
+    }
+    if (settlementsUnreached) {
+      return __retainFailedWasiRollback(cleanupErrors)
+    }
+    return __destroyContextForWasiRollback(cleanupErrors)
+  }
+
+  // Same reason as \`__startWasiDisposal\`: a module-init hook can start async
+  // work before the load goes on to fail, and this rollback tears down exactly
+  // what those completions need. Settle them while everything is still live,
+  // before the barrier and the teardown above take that away.
+  //
+  // A drain that could not finish leaves async work possibly outstanding, and
+  // destroying the context over it would strand exactly what this rollback is
+  // there to settle. Stop short and retain instead — the same trade
+  // \`__rollbackWasmEnvForWasiInitialization\` makes for the settlement drain, so
+  // the context stays reclaimable by a retry or by this flavor's own
+  // last-resort teardown.
+  const __retainAfterAsyncWorkDrainFailure = (cleanupError) =>
+    __retainFailedWasiRollback([cleanupError])
+  let asyncWorkResult
   try {
-    __prepareWasmEnvCleanup()
-    drainResult = __drainWasmEnvCleanup()
+    asyncWorkResult = __drainWasiAsyncWork()
   } catch (cleanupError) {
-    cleanupErrors.push(cleanupError)
-    settlementsUnreached = true
+    return __retainAfterAsyncWorkDrainFailure(cleanupError)
   }
-  if (__isThenable(drainResult)) {
-    return Promise.resolve(drainResult).then(
-      () => __destroyContextForWasiRollback(cleanupErrors),
-      (cleanupError) => {
-        cleanupErrors.push(cleanupError)
-        return __retainFailedWasiRollback(cleanupErrors)
-      },
+  if (__isThenable(asyncWorkResult)) {
+    return Promise.resolve(asyncWorkResult).then(
+      __rollbackWasmEnvForWasiInitialization,
+      __retainAfterAsyncWorkDrainFailure,
     )
   }
-  if (settlementsUnreached) {
-    return __retainFailedWasiRollback(cleanupErrors)
-  }
-  return __destroyContextForWasiRollback(cleanupErrors)
+  return __rollbackWasmEnvForWasiInitialization()
 }
 `
 }
@@ -875,14 +1069,27 @@ const __workerPoolSize = Math.max(
   const memoryName = threads ? '__sharedMemory' : '__wasmMemory'
   const asyncWorkPoolOption = `    asyncWorkPoolSize: ${threads ? '__asyncWorkPoolSize' : 0},
 `
-  // Every build links a "basic" emnapi archive without the C async-work and
-  // threadsafe-function implementations (the `emnapi-napi-rs(-mt)` archives shipped by the emnapi package), so the
-  // JavaScript implementations must be provided through the emnapi plugins in
-  // both threading modes. Without threads the C code would be unconditional
-  // `napi_generic_failure` stubs; with threads it would shadow the
-  // `@emnapi/core` threaded TSFN/async-work protocol the plugins implement.
+  // Which archive a build links decides who implements async work and
+  // threadsafe functions — see `emnapi_link_library` in
+  // `crates/build/src/wasi.rs`. Without threads it is `emnapi-basic-napi-rs`,
+  // the "basic" model: both stay wasm imports, and the `@emnapi/core`
+  // JavaScript plugins below are what resolves them; without the plugins
+  // instantiation fails with a LinkError naming the missing import. With
+  // threads it is `emnapi-napi-rs-mt`, the full composition, whose C
+  // `async_work.c` / `threadsafe_function.c` run on the uv threadpool inside
+  // the wasm — it imports none of those symbols, so the plugins are inert
+  // there. They are passed in both modes because only the archive knows which
+  // applies, and a plugin nothing imports costs nothing.
+  //
+  // This is why the async-work drain on the disposal path cannot live here:
+  // with threads there is no JavaScript seam at all, so `__drainWasiAsyncWork`
+  // asks the addon instead.
   const emnapiPluginImport = `  emnapiAsyncWorkPlugin as __emnapiAsyncWorkPlugin,\n  emnapiTSFNPlugin as __emnapiTSFNPlugin,\n`
-  const emnapiPluginOption = `    plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],\n`
+  const emnapiPluginOption = `    plugins: [
+      __captureWasiThreadManager,
+      __emnapiAsyncWorkPlugin,
+      __emnapiTSFNPlugin,
+    ],\n`
   const workerOption = threads
     ? `    onCreateWorker() {
       const worker = new Worker(new URL('./wasi-worker-browser.mjs', import.meta.url), {
@@ -1492,6 +1699,101 @@ function __drainWasmEnvCleanup(__instance) {
   })()
 }
 
+// A real, *referenced* timer for the async-work wait below, which polls the
+// addon rather than interleaving with the @emnapi/core dispatch: a zero-delay
+// macrotask there would spin the loop instead of yielding it. Falls back to the
+// macrotask scheduler on a host without timers.
+function __scheduleTimer(__callback, __delay) {
+  const __setTimer = globalThis.setTimeout
+  if (typeof __setTimer !== 'function') {
+    __scheduleMacrotask(__callback)
+    return
+  }
+  try {
+    __setTimer(__callback, __delay)
+  } catch {
+    __scheduleMacrotask(__callback)
+  }
+}
+
+// How often to re-read \`napi_wasm_async_work_pending\` while waiting. The wait
+// ends when the addon reports zero, so this only decides how promptly disposal
+// notices — not how long it waits.
+const __WASI_ASYNC_WORK_POLL_INTERVAL_MS = 1
+
+/**
+ * Settles this instance's outstanding \`napi_async_work\` before the teardown
+ * that would strand it.
+ *
+ * The same hole the eager loaders had, and the same fix: the environment
+ * cleanup barrier covers promise settlements queued on the threadsafe-function
+ * queue and says nothing about \`napi_async_work\`, so destroying the context
+ * with a work still outstanding leaves its completion callback with nowhere to
+ * run and its promise unsettled forever.
+ *
+ * This flavor is threadless, so \`compute\` runs on the JavaScript thread inside
+ * the macrotask that dequeued it: while this is running, any outstanding work
+ * is queued rather than executing, and \`napi_wasm_cancel_pending_async_work\`
+ * can take all of it. The poll is still what decides when the drain is done —
+ * cancellation delivers those completions from a later macrotask, not
+ * synchronously.
+ *
+ * Per instance, from that instance's own exports: two instances of this loader
+ * have separate registries and must not wait on each other.
+ *
+ * Both exports are optional, so an addon built against a napi crate that
+ * predates them keeps the previous behavior.
+ *
+ * Returns nothing when there is nothing outstanding, which keeps disposal
+ * synchronous in the common case. No deadline: giving up would destroy the
+ * environment with a completion callback still owed.
+ */
+function __drainInstanceAsyncWork(__instance) {
+  const __exports = __instance?.exports
+  const __pending = __exports?.napi_wasm_async_work_pending
+  const __cancelPending = __exports?.napi_wasm_cancel_pending_async_work
+  if (typeof __pending !== 'function' || typeof __cancelPending !== 'function') {
+    return
+  }
+
+  const __readPending = () => {
+    try {
+      return __pending()
+    } catch (__error) {
+      // A trap is the only way this call fails: it reads a counter and cannot
+      // allocate or call back into JavaScript. A trapped instance can no longer
+      // run anything, so its outstanding work is unreachable by definition and
+      // best-effort is the honest answer. Anything else means the export is not
+      // what this loader thinks it is — a defect worth surfacing.
+      if (__error instanceof globalThis.WebAssembly.RuntimeError) {
+        return 0
+      }
+      throw __error
+    }
+  }
+
+  if (!__readPending()) {
+    return
+  }
+  try {
+    __cancelPending()
+  } catch {
+    // Cancellation only bounds the wait. Failing it means waiting for the queue
+    // to run instead, which the poll below already does.
+  }
+  if (!__readPending()) {
+    return
+  }
+
+  return (async () => {
+    while (__readPending()) {
+      await new Promise((__resolve) => {
+        __scheduleTimer(__resolve, __WASI_ASYNC_WORK_POLL_INTERVAL_MS)
+      })
+    }
+  })()
+}
+
 function __createLifecycleReentryError(__operation) {
   const __error = new Error(
     __operation +
@@ -1988,7 +2290,15 @@ ${instanceHostState}\
     if (__lifecycleState !== 'failed') {
       __lifecycleState = 'disposal'
     }
-    // Settle what the barrier cancelled before the environment stops
+    // Outstanding async work first, while the environment is still completely
+    // live: its completion callbacks run addon code, and the barrier and
+    // \`Context.destroy()\` below each take that away. Undefined unless work is
+    // outstanding.
+    const __asyncWorkDrained = __drainInstanceAsyncWork(__napiInstance)
+    if (__asyncWorkDrained) {
+      await __asyncWorkDrained
+    }
+    // Then settle what the barrier cancelled, before the environment stops
     // accepting JavaScript calls. Undefined unless something is queued, so
     // an idle disposal is not delayed by a single turn.
     const __drained = __prepareForDisposal()
@@ -2145,6 +2455,14 @@ ${installInstanceHosts}\
     // so a failure before beforeInit costs no extra turn.
     let __settlementsUnreached = false
     try {
+      // Registration can start async work too, and this path destroys the same
+      // environment its completions need. A drain that cannot finish leaves the
+      // work outstanding, so it counts as settlements unreached and stops the
+      // rollback short of destroying, exactly like a failed barrier drain.
+      const __asyncWorkDrained = __drainInstanceAsyncWork(__napiInstance)
+      if (__asyncWorkDrained) {
+        await __asyncWorkDrained
+      }
       const __drained = __prepareForDisposal()
       if (__drained) {
         await __drained
@@ -2628,17 +2946,34 @@ function __createWasiWorker(filename) {
       }
     })(),
     reuseWorker: true,
-    plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],
+    plugins: [
+      __captureWasiThreadManager,
+      __emnapiAsyncWorkPlugin,
+      __emnapiTSFNPlugin,
+    ],
 `
     : `    asyncWorkPoolSize: 0,
-    plugins: [__captureWasiThreadManager, __emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],
+    plugins: [
+      __captureWasiThreadManager,
+      __emnapiAsyncWorkPlugin,
+      __emnapiTSFNPlugin,
+    ],
 `
-  // Every build links a "basic" emnapi archive without the C async-work and
-  // threadsafe-function implementations (the `emnapi-napi-rs(-mt)` archives shipped by the emnapi package), so the
-  // JavaScript implementations must be provided through the emnapi plugins in
-  // both threading modes. Without threads the C code would be unconditional
-  // `napi_generic_failure` stubs; with threads it would shadow the
-  // `@emnapi/core` threaded TSFN/async-work protocol the plugins implement.
+  // Which archive a build links decides who implements async work and
+  // threadsafe functions — see `emnapi_link_library` in
+  // `crates/build/src/wasi.rs`. Without threads it is `emnapi-basic-napi-rs`,
+  // the "basic" model: both stay wasm imports, and the `@emnapi/core`
+  // JavaScript plugins below are what resolves them; without the plugins
+  // instantiation fails with a LinkError naming the missing import. With
+  // threads it is `emnapi-napi-rs-mt`, the full composition, whose C
+  // `async_work.c` / `threadsafe_function.c` run on the uv threadpool inside
+  // the wasm — it imports none of those symbols, so the plugins are inert
+  // there. They are passed in both modes because only the archive knows which
+  // applies, and a plugin nothing imports costs nothing.
+  //
+  // This is why the async-work drain on the disposal path cannot live here:
+  // with threads there is no JavaScript seam at all, so `__drainWasiAsyncWork`
+  // asks the addon instead.
   const emnapiPluginRequire = `  emnapiAsyncWorkPlugin: __emnapiAsyncWorkPlugin,\n  emnapiTSFNPlugin: __emnapiTSFNPlugin,\n`
   const workerOption = threads
     ? `    onCreateWorker() {