@napi-rs/cli 3.8.3 → 3.8.4

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

@@ -56,9 +56,16 @@ Generated by [AVA](https://avajs.dev).
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
     let __emnapiWasmEnvCleanupPrepared = false␊
+    let __emnapiWasmEnvCleanupRan = false␊
+    let __emnapiWasmEnvCleanupDrained = false␊
+    let __emnapiWasmEnvCleanupDrainPromise␊
     let __wasiDisposed = false␊
     let __wasiDisposePromise␊
     let __completeWasiDisposal = function() {}␊
+    // Overridden by loader flavors that have a last-resort reclaim for a rollback␊
+    // that stopped short of destroying the context. See␊
+    // \`__rollbackWasiInitialization\`.␊
+    let __retainWasiRollbackForRetry = function() {}␊
     ␊
     function __isThenable(value) {␊
       return (␊
@@ -129,10 +136,168 @@ Generated by [AVA](https://avajs.dev).
       const prepare = __napiInstance?.exports?.napi_prepare_wasm_env_cleanup␊
       if (typeof prepare === 'function') {␊
         prepare()␊
+        __emnapiWasmEnvCleanupRan = true␊
       }␊
       __emnapiWasmEnvCleanupPrepared = true␊
     }␊
     ␊
+    // Mirror the primitive @emnapi/core schedules its threadsafe-function dispatch␊
+    // on, so the drain turns below interleave with that dispatch instead of racing␊
+    // ahead of it on a faster queue.␊
+    const __scheduleMacrotask = (function () {␊
+      if (typeof setImmediate === 'function') {␊
+        return function (callback) {␊
+          setImmediate(callback)␊
+        }␊
+      }␊
+      const __MessageChannel = globalThis.MessageChannel␊
+      if (typeof __MessageChannel === 'function') {␊
+        return function (callback) {␊
+          const channel = new __MessageChannel()␊
+          channel.port1.onmessage = function () {␊
+            channel.port1.onmessage = null␊
+            try {␊
+              channel.port1.close()␊
+            } catch {}␊
+            try {␊
+              channel.port2.close()␊
+            } catch {}␊
+            callback()␊
+          }␊
+          channel.port2.postMessage(null)␊
+        }␊
+      }␊
+      return function (callback) {␊
+        setTimeout(callback, 0)␊
+      }␊
+    })()␊
+    ␊
+    // 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␊
+    // destroying the context over a still-queued settlement — the wait stays␊
+    // bounded either way.␊
+    const __WASM_ENV_CLEANUP_DRAIN_TURNS = 128␊
+    // Without \`napi_wasm_env_cleanup_pending\` the queue is not observable. Fall␊
+    // back to the number of turns @emnapi/core needs to coalesce and dispatch a␊
+    // call made on this thread (two), plus a margin.␊
+    const __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS = 4␊
+    ␊
+    /**␊
+     * \`napi_prepare_wasm_env_cleanup\` only *queues* the promise settlements of the␊
+     * tasks it cancelled: \`napi_call_threadsafe_function\` appends to the␊
+     * threadsafe-function queue, and @emnapi/core dispatches that queue from a␊
+     * macrotask — two coalescing turns later, even for a call made on this very␊
+     * thread. \`Context.destroy()\` then runs the threadsafe function's cleanup hook,␊
+     * which drains the queue with a null env and *discards* whatever is still in it.␊
+     *␊
+     * So destroying without yielding first strands exactly the promises the barrier␊
+     * exists to settle. Yield real event-loop turns until the addon reports the␊
+     * queue empty; microtask checkpoints cannot help, no number of them lets a␊
+     * macrotask run.␊
+     *␊
+     * Returns nothing when there is nothing to wait for, which keeps disposal␊
+     * synchronous in the common case.␊
+     *␊
+     * The "already drained" flag is set only once a wait has actually finished.␊
+     * Scheduling a macrotask can fail — a host-provided or patched \`setImmediate\`␊
+     * that throws is enough — and a disposal that rejects stays retryable, so␊
+     * marking the drain complete up front would make the retry skip it and destroy␊
+     * the context with the barrier's settlements still queued.␊
+     *␊
+     * A wait that runs out of turns with the counter still nonzero rejects with␊
+     * \`ERR_NAPI_WASI_CLEANUP_PENDING\` for the same reason: at that point␊
+     * "finished" is indistinguishable from the stranding above, and destroying␊
+     * would discard the very settlement the wait was for. The rejection leaves the␊
+     * flag unset and disposal retryable.␊
+     */␊
+    function __drainWasmEnvCleanup() {␊
+      if (__emnapiWasmEnvCleanupDrained || !__emnapiWasmEnvCleanupRan) {␊
+        return␊
+      }␊
+      if (__emnapiWasmEnvCleanupDrainPromise) {␊
+        return __emnapiWasmEnvCleanupDrainPromise␊
+      }␊
+      const pending = __napiInstance?.exports?.napi_wasm_env_cleanup_pending␊
+      const observable = typeof pending === 'function'␊
+      if (observable) {␊
+        let queued␊
+        try {␊
+          queued = pending()␊
+        } catch {␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          return␊
+        }␊
+        if (!queued) {␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          return␊
+        }␊
+      }␊
+      const limit = observable␊
+        ? __WASM_ENV_CLEANUP_DRAIN_TURNS␊
+        : __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS␊
+      const drainPromise = (async () => {␊
+        let queued = 0␊
+        for (let turn = 0; turn < limit; turn++) {␊
+          await new Promise((resolve) => {␊
+            __scheduleMacrotask(resolve)␊
+          })␊
+          if (!observable) {␊
+            continue␊
+          }␊
+          try {␊
+            queued = pending()␊
+          } catch {␊
+            return␊
+          }␊
+          if (!queued) {␊
+            return␊
+          }␊
+        }␊
+        if (!observable) {␊
+          // Blind wait: without \`napi_wasm_env_cleanup_pending\` the bound IS the␊
+          // contract — there is nothing to consult, so finishing the turns is␊
+          // finishing the drain.␊
+          return␊
+        }␊
+        // The counter is still nonzero after every turn the bound allows. The wait␊
+        // stays bounded — but claiming success here would be indistinguishable from␊
+        // the stranding this drain exists to prevent: disposal would go on to␊
+        // destroy the context, whose cleanup hook discards the still-queued␊
+        // settlement with a null env, and the promise it was for hangs forever.␊
+        // Reject instead, as a retryable cleanup failure: the drained flag stays␊
+        // unset, dispose() (and the rollback) decline to destroy, and a later␊
+        // dispose() runs the drain again — by which time the queue has usually been␊
+        // delivered. A counter that is somehow stuck nonzero therefore costs each␊
+        // attempt at most another bounded wait and a rejection, never a stranded␊
+        // promise; the process-exit teardown still reclaims the context.␊
+        const drainError = new Error(␊
+          'the wasm environment still reports ' +␊
+            queued +␊
+            ' queued settlement(s) after ' +␊
+            limit +␊
+            ' event-loop turns; the context was not destroyed - retry dispose() to wait for the queue again',␊
+        )␊
+        drainError.code = 'ERR_NAPI_WASI_CLEANUP_PENDING'␊
+        throw drainError␊
+      })().then(␊
+        (value) => {␊
+          // Set only when the wait actually finished AND the queue was seen empty␊
+          // (or is unobservable): a drain that timed out with settlements still␊
+          // queued rejects above and must stay repeatable.␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          __emnapiWasmEnvCleanupDrainPromise = undefined␊
+          return value␊
+        },␊
+        (error) => {␊
+          __emnapiWasmEnvCleanupDrainPromise = undefined␊
+          throw error␊
+        },␊
+      )␊
+      __emnapiWasmEnvCleanupDrainPromise = drainPromise␊
+      return drainPromise␊
+    }␊
+    ␊
     function __destroyEmnapiContext() {␊
       if (__emnapiContextDestroyed || __emnapiContext === undefined) {␊
         __emnapiContextDestroyed = true␊
@@ -210,7 +375,7 @@ Generated by [AVA](https://avajs.dev).
       return __completeWasiDisposal()␊
     }␊
     ␊
-    function __startWasiDisposal() {␊
+    function __continueWasiDisposal() {␊
       const destroyResult = __destroyEmnapiContext()␊
       if (__isThenable(destroyResult)) {␊
         return Promise.resolve(destroyResult).then(__finishWasiDisposal)␊
@@ -218,6 +383,18 @@ Generated by [AVA](https://avajs.dev).
       return __finishWasiDisposal()␊
     }␊
     ␊
+    function __startWasiDisposal() {␊
+      // 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.␊
+      __prepareWasmEnvCleanup()␊
+      const drainResult = __drainWasmEnvCleanup()␊
+      if (__isThenable(drainResult)) {␊
+        return Promise.resolve(drainResult).then(__continueWasiDisposal)␊
+      }␊
+      return __continueWasiDisposal()␊
+    }␊
+    ␊
     /**␊
      * Disposes this generated WASI binding.␊
      *␊
@@ -289,8 +466,7 @@ Generated by [AVA](https://avajs.dev).
       return cleanupErrors␊
     }␊
     ␊
-    function __rollbackWasiInitialization() {␊
-      const cleanupErrors = []␊
+    function __destroyContextForWasiRollback(cleanupErrors) {␊
       let destroyResult␊
       try {␊
         destroyResult = __destroyEmnapiContext()␊
@@ -308,6 +484,83 @@ Generated by [AVA](https://avajs.dev).
       return __finishWasiInitializationRollback(cleanupErrors)␊
     }␊
     ␊
+    /**␊
+     * Leaves a rollback that could not reach the queued settlements undestroyed, and␊
+     * hands it to whatever this flavor has that can still reclaim it.␊
+     */␊
+    function __retainFailedWasiRollback(cleanupErrors) {␊
+      try {␊
+        __retainWasiRollbackForRetry()␊
+      } catch (cleanupError) {␊
+        cleanupErrors.push(cleanupError)␊
+      }␊
+      return cleanupErrors␊
+    }␊
+    ␊
+    /**␊
+     * Initialization can fail *after* registration has already run, and registration␊
+     * runs with a live environment: a module-init hook can start async work and then␊
+     * return an error, and the promise it created may already have escaped into␊
+     * JavaScript. The barrier cancels that work and *queues* the settlement, so this␊
+     * path needs the same drain the ordinary disposal does — destroying without␊
+     * yielding discards the queue with a null env and strands the promise.␊
+     *␊
+     * Stays synchronous when nothing is queued, which covers every failure before␊
+     * \`beforeInit\`: there is no instance to run the barrier on, so nothing to drain.␊
+     *␊
+     * A barrier or drain that did *not* finish stops the rollback short of␊
+     * destroying, which is what \`dispose()\` already does — a rejected drain there␊
+     * never reaches \`__continueWasiDisposal\`. Destroying anyway is the worse of the␊
+     * two trades, and not because of what it saves:␊
+     *␊
+     *   - It cannot deliver the settlements. \`Context.destroy()\` runs the␊
+     *     threadsafe function's cleanup hook, which drains the queue with a null env␊
+     *     and discards it, so a promise that already escaped into JavaScript hangs␊
+     *     forever with nothing left that could ever settle it.␊
+     *   - It saves less than it looks. \`Context.destroy()\` stops JavaScript calls␊
+     *     and runs cleanup hooks; it does not free the wasm instance or its Memory,␊
+     *     which this module's scope holds either way. What stopping short retains is␊
+     *     the emnapi context's bookkeeping and its un-run cleanup hooks.␊
+     *   - Retry is not theoretical. A rollback that records a cleanup error is␊
+     *     already kept in the process-wide registry above, so re-\`require()\`ing this␊
+     *     file replays it instead of re-instantiating — and the \`6e15de6f\` flag fix␊
+     *     means the replay drains again rather than skipping it. Destroying first is␊
+     *     what makes that retained record useless.␊
+     *␊
+     * The residual cost is honest: the CJS flavor hands the context to its␊
+     * \`process.on('exit')\` teardown, so a process that never retries still reclaims␊
+     * it on the way out. The ESM browser flavor has no equivalent — a module that␊
+     * throws while evaluating is permanently errored, so re-importing rethrows␊
+     * without re-running this file — and there the context stays until the realm␊
+     * goes away. That is the deliberate choice: a hung promise is a silent liveness␊
+     * bug with no upper bound, while the retained bookkeeping is bounded by the page.␊
+     */␊
+    function __rollbackWasiInitialization() {␊
+      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)␊
+    }␊
+    ␊
     let __wasiModule␊
     let __napiModule␊
     ␊
@@ -411,9 +664,16 @@ Generated by [AVA](https://avajs.dev).
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
     let __emnapiWasmEnvCleanupPrepared = false␊
+    let __emnapiWasmEnvCleanupRan = false␊
+    let __emnapiWasmEnvCleanupDrained = false␊
+    let __emnapiWasmEnvCleanupDrainPromise␊
     let __wasiDisposed = false␊
     let __wasiDisposePromise␊
     let __completeWasiDisposal = function() {}␊
+    // Overridden by loader flavors that have a last-resort reclaim for a rollback␊
+    // that stopped short of destroying the context. See␊
+    // \`__rollbackWasiInitialization\`.␊
+    let __retainWasiRollbackForRetry = function() {}␊
     ␊
     function __isThenable(value) {␊
       return (␊
@@ -484,10 +744,168 @@ Generated by [AVA](https://avajs.dev).
       const prepare = __napiInstance?.exports?.napi_prepare_wasm_env_cleanup␊
       if (typeof prepare === 'function') {␊
         prepare()␊
+        __emnapiWasmEnvCleanupRan = true␊
       }␊
       __emnapiWasmEnvCleanupPrepared = true␊
     }␊
     ␊
+    // Mirror the primitive @emnapi/core schedules its threadsafe-function dispatch␊
+    // on, so the drain turns below interleave with that dispatch instead of racing␊
+    // ahead of it on a faster queue.␊
+    const __scheduleMacrotask = (function () {␊
+      if (typeof setImmediate === 'function') {␊
+        return function (callback) {␊
+          setImmediate(callback)␊
+        }␊
+      }␊
+      const __MessageChannel = globalThis.MessageChannel␊
+      if (typeof __MessageChannel === 'function') {␊
+        return function (callback) {␊
+          const channel = new __MessageChannel()␊
+          channel.port1.onmessage = function () {␊
+            channel.port1.onmessage = null␊
+            try {␊
+              channel.port1.close()␊
+            } catch {}␊
+            try {␊
+              channel.port2.close()␊
+            } catch {}␊
+            callback()␊
+          }␊
+          channel.port2.postMessage(null)␊
+        }␊
+      }␊
+      return function (callback) {␊
+        setTimeout(callback, 0)␊
+      }␊
+    })()␊
+    ␊
+    // 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␊
+    // destroying the context over a still-queued settlement — the wait stays␊
+    // bounded either way.␊
+    const __WASM_ENV_CLEANUP_DRAIN_TURNS = 128␊
+    // Without \`napi_wasm_env_cleanup_pending\` the queue is not observable. Fall␊
+    // back to the number of turns @emnapi/core needs to coalesce and dispatch a␊
+    // call made on this thread (two), plus a margin.␊
+    const __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS = 4␊
+    ␊
+    /**␊
+     * \`napi_prepare_wasm_env_cleanup\` only *queues* the promise settlements of the␊
+     * tasks it cancelled: \`napi_call_threadsafe_function\` appends to the␊
+     * threadsafe-function queue, and @emnapi/core dispatches that queue from a␊
+     * macrotask — two coalescing turns later, even for a call made on this very␊
+     * thread. \`Context.destroy()\` then runs the threadsafe function's cleanup hook,␊
+     * which drains the queue with a null env and *discards* whatever is still in it.␊
+     *␊
+     * So destroying without yielding first strands exactly the promises the barrier␊
+     * exists to settle. Yield real event-loop turns until the addon reports the␊
+     * queue empty; microtask checkpoints cannot help, no number of them lets a␊
+     * macrotask run.␊
+     *␊
+     * Returns nothing when there is nothing to wait for, which keeps disposal␊
+     * synchronous in the common case.␊
+     *␊
+     * The "already drained" flag is set only once a wait has actually finished.␊
+     * Scheduling a macrotask can fail — a host-provided or patched \`setImmediate\`␊
+     * that throws is enough — and a disposal that rejects stays retryable, so␊
+     * marking the drain complete up front would make the retry skip it and destroy␊
+     * the context with the barrier's settlements still queued.␊
+     *␊
+     * A wait that runs out of turns with the counter still nonzero rejects with␊
+     * \`ERR_NAPI_WASI_CLEANUP_PENDING\` for the same reason: at that point␊
+     * "finished" is indistinguishable from the stranding above, and destroying␊
+     * would discard the very settlement the wait was for. The rejection leaves the␊
+     * flag unset and disposal retryable.␊
+     */␊
+    function __drainWasmEnvCleanup() {␊
+      if (__emnapiWasmEnvCleanupDrained || !__emnapiWasmEnvCleanupRan) {␊
+        return␊
+      }␊
+      if (__emnapiWasmEnvCleanupDrainPromise) {␊
+        return __emnapiWasmEnvCleanupDrainPromise␊
+      }␊
+      const pending = __napiInstance?.exports?.napi_wasm_env_cleanup_pending␊
+      const observable = typeof pending === 'function'␊
+      if (observable) {␊
+        let queued␊
+        try {␊
+          queued = pending()␊
+        } catch {␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          return␊
+        }␊
+        if (!queued) {␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          return␊
+        }␊
+      }␊
+      const limit = observable␊
+        ? __WASM_ENV_CLEANUP_DRAIN_TURNS␊
+        : __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS␊
+      const drainPromise = (async () => {␊
+        let queued = 0␊
+        for (let turn = 0; turn < limit; turn++) {␊
+          await new Promise((resolve) => {␊
+            __scheduleMacrotask(resolve)␊
+          })␊
+          if (!observable) {␊
+            continue␊
+          }␊
+          try {␊
+            queued = pending()␊
+          } catch {␊
+            return␊
+          }␊
+          if (!queued) {␊
+            return␊
+          }␊
+        }␊
+        if (!observable) {␊
+          // Blind wait: without \`napi_wasm_env_cleanup_pending\` the bound IS the␊
+          // contract — there is nothing to consult, so finishing the turns is␊
+          // finishing the drain.␊
+          return␊
+        }␊
+        // The counter is still nonzero after every turn the bound allows. The wait␊
+        // stays bounded — but claiming success here would be indistinguishable from␊
+        // the stranding this drain exists to prevent: disposal would go on to␊
+        // destroy the context, whose cleanup hook discards the still-queued␊
+        // settlement with a null env, and the promise it was for hangs forever.␊
+        // Reject instead, as a retryable cleanup failure: the drained flag stays␊
+        // unset, dispose() (and the rollback) decline to destroy, and a later␊
+        // dispose() runs the drain again — by which time the queue has usually been␊
+        // delivered. A counter that is somehow stuck nonzero therefore costs each␊
+        // attempt at most another bounded wait and a rejection, never a stranded␊
+        // promise; the process-exit teardown still reclaims the context.␊
+        const drainError = new Error(␊
+          'the wasm environment still reports ' +␊
+            queued +␊
+            ' queued settlement(s) after ' +␊
+            limit +␊
+            ' event-loop turns; the context was not destroyed - retry dispose() to wait for the queue again',␊
+        )␊
+        drainError.code = 'ERR_NAPI_WASI_CLEANUP_PENDING'␊
+        throw drainError␊
+      })().then(␊
+        (value) => {␊
+          // Set only when the wait actually finished AND the queue was seen empty␊
+          // (or is unobservable): a drain that timed out with settlements still␊
+          // queued rejects above and must stay repeatable.␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          __emnapiWasmEnvCleanupDrainPromise = undefined␊
+          return value␊
+        },␊
+        (error) => {␊
+          __emnapiWasmEnvCleanupDrainPromise = undefined␊
+          throw error␊
+        },␊
+      )␊
+      __emnapiWasmEnvCleanupDrainPromise = drainPromise␊
+      return drainPromise␊
+    }␊
+    ␊
     function __destroyEmnapiContext() {␊
       if (__emnapiContextDestroyed || __emnapiContext === undefined) {␊
         __emnapiContextDestroyed = true␊
@@ -565,7 +983,7 @@ Generated by [AVA](https://avajs.dev).
       return __completeWasiDisposal()␊
     }␊
     ␊
-    function __startWasiDisposal() {␊
+    function __continueWasiDisposal() {␊
       const destroyResult = __destroyEmnapiContext()␊
       if (__isThenable(destroyResult)) {␊
         return Promise.resolve(destroyResult).then(__finishWasiDisposal)␊
@@ -573,6 +991,18 @@ Generated by [AVA](https://avajs.dev).
       return __finishWasiDisposal()␊
     }␊
     ␊
+    function __startWasiDisposal() {␊
+      // 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.␊
+      __prepareWasmEnvCleanup()␊
+      const drainResult = __drainWasmEnvCleanup()␊
+      if (__isThenable(drainResult)) {␊
+        return Promise.resolve(drainResult).then(__continueWasiDisposal)␊
+      }␊
+      return __continueWasiDisposal()␊
+    }␊
+    ␊
     /**␊
      * Disposes this generated WASI binding.␊
      *␊
@@ -644,8 +1074,7 @@ Generated by [AVA](https://avajs.dev).
       return cleanupErrors␊
     }␊
     ␊
-    function __rollbackWasiInitialization() {␊
-      const cleanupErrors = []␊
+    function __destroyContextForWasiRollback(cleanupErrors) {␊
       let destroyResult␊
       try {␊
         destroyResult = __destroyEmnapiContext()␊
@@ -663,6 +1092,83 @@ Generated by [AVA](https://avajs.dev).
       return __finishWasiInitializationRollback(cleanupErrors)␊
     }␊
     ␊
+    /**␊
+     * Leaves a rollback that could not reach the queued settlements undestroyed, and␊
+     * hands it to whatever this flavor has that can still reclaim it.␊
+     */␊
+    function __retainFailedWasiRollback(cleanupErrors) {␊
+      try {␊
+        __retainWasiRollbackForRetry()␊
+      } catch (cleanupError) {␊
+        cleanupErrors.push(cleanupError)␊
+      }␊
+      return cleanupErrors␊
+    }␊
+    ␊
+    /**␊
+     * Initialization can fail *after* registration has already run, and registration␊
+     * runs with a live environment: a module-init hook can start async work and then␊
+     * return an error, and the promise it created may already have escaped into␊
+     * JavaScript. The barrier cancels that work and *queues* the settlement, so this␊
+     * path needs the same drain the ordinary disposal does — destroying without␊
+     * yielding discards the queue with a null env and strands the promise.␊
+     *␊
+     * Stays synchronous when nothing is queued, which covers every failure before␊
+     * \`beforeInit\`: there is no instance to run the barrier on, so nothing to drain.␊
+     *␊
+     * A barrier or drain that did *not* finish stops the rollback short of␊
+     * destroying, which is what \`dispose()\` already does — a rejected drain there␊
+     * never reaches \`__continueWasiDisposal\`. Destroying anyway is the worse of the␊
+     * two trades, and not because of what it saves:␊
+     *␊
+     *   - It cannot deliver the settlements. \`Context.destroy()\` runs the␊
+     *     threadsafe function's cleanup hook, which drains the queue with a null env␊
+     *     and discards it, so a promise that already escaped into JavaScript hangs␊
+     *     forever with nothing left that could ever settle it.␊
+     *   - It saves less than it looks. \`Context.destroy()\` stops JavaScript calls␊
+     *     and runs cleanup hooks; it does not free the wasm instance or its Memory,␊
+     *     which this module's scope holds either way. What stopping short retains is␊
+     *     the emnapi context's bookkeeping and its un-run cleanup hooks.␊
+     *   - Retry is not theoretical. A rollback that records a cleanup error is␊
+     *     already kept in the process-wide registry above, so re-\`require()\`ing this␊
+     *     file replays it instead of re-instantiating — and the \`6e15de6f\` flag fix␊
+     *     means the replay drains again rather than skipping it. Destroying first is␊
+     *     what makes that retained record useless.␊
+     *␊
+     * The residual cost is honest: the CJS flavor hands the context to its␊
+     * \`process.on('exit')\` teardown, so a process that never retries still reclaims␊
+     * it on the way out. The ESM browser flavor has no equivalent — a module that␊
+     * throws while evaluating is permanently errored, so re-importing rethrows␊
+     * without re-running this file — and there the context stays until the realm␊
+     * goes away. That is the deliberate choice: a hung promise is a silent liveness␊
+     * bug with no upper bound, while the retained bookkeeping is bounded by the page.␊
+     */␊
+    function __rollbackWasiInitialization() {␊
+      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)␊
+    }␊
+    ␊
     let __wasiModule␊
     let __napiModule␊
     ␊
@@ -785,9 +1291,16 @@ Generated by [AVA](https://avajs.dev).
     let __emnapiContextDestroyed = false␊
     let __emnapiContextDestroyPromise␊
     let __emnapiWasmEnvCleanupPrepared = false␊
+    let __emnapiWasmEnvCleanupRan = false␊
+    let __emnapiWasmEnvCleanupDrained = false␊
+    let __emnapiWasmEnvCleanupDrainPromise␊
     let __wasiDisposed = false␊
     let __wasiDisposePromise␊
     let __completeWasiDisposal = function() {}␊
+    // Overridden by loader flavors that have a last-resort reclaim for a rollback␊
+    // that stopped short of destroying the context. See␊
+    // \`__rollbackWasiInitialization\`.␊
+    let __retainWasiRollbackForRetry = function() {}␊
     ␊
     function __isThenable(value) {␊
       return (␊
@@ -858,10 +1371,168 @@ Generated by [AVA](https://avajs.dev).
       const prepare = __napiInstance?.exports?.napi_prepare_wasm_env_cleanup␊
       if (typeof prepare === 'function') {␊
         prepare()␊
+        __emnapiWasmEnvCleanupRan = true␊
       }␊
       __emnapiWasmEnvCleanupPrepared = true␊
     }␊
     ␊
+    // Mirror the primitive @emnapi/core schedules its threadsafe-function dispatch␊
+    // on, so the drain turns below interleave with that dispatch instead of racing␊
+    // ahead of it on a faster queue.␊
+    const __scheduleMacrotask = (function () {␊
+      if (typeof setImmediate === 'function') {␊
+        return function (callback) {␊
+          setImmediate(callback)␊
+        }␊
+      }␊
+      const __MessageChannel = globalThis.MessageChannel␊
+      if (typeof __MessageChannel === 'function') {␊
+        return function (callback) {␊
+          const channel = new __MessageChannel()␊
+          channel.port1.onmessage = function () {␊
+            channel.port1.onmessage = null␊
+            try {␊
+              channel.port1.close()␊
+            } catch {}␊
+            try {␊
+              channel.port2.close()␊
+            } catch {}␊
+            callback()␊
+          }␊
+          channel.port2.postMessage(null)␊
+        }␊
+      }␊
+      return function (callback) {␊
+        setTimeout(callback, 0)␊
+      }␊
+    })()␊
+    ␊
+    // 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␊
+    // destroying the context over a still-queued settlement — the wait stays␊
+    // bounded either way.␊
+    const __WASM_ENV_CLEANUP_DRAIN_TURNS = 128␊
+    // Without \`napi_wasm_env_cleanup_pending\` the queue is not observable. Fall␊
+    // back to the number of turns @emnapi/core needs to coalesce and dispatch a␊
+    // call made on this thread (two), plus a margin.␊
+    const __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS = 4␊
+    ␊
+    /**␊
+     * \`napi_prepare_wasm_env_cleanup\` only *queues* the promise settlements of the␊
+     * tasks it cancelled: \`napi_call_threadsafe_function\` appends to the␊
+     * threadsafe-function queue, and @emnapi/core dispatches that queue from a␊
+     * macrotask — two coalescing turns later, even for a call made on this very␊
+     * thread. \`Context.destroy()\` then runs the threadsafe function's cleanup hook,␊
+     * which drains the queue with a null env and *discards* whatever is still in it.␊
+     *␊
+     * So destroying without yielding first strands exactly the promises the barrier␊
+     * exists to settle. Yield real event-loop turns until the addon reports the␊
+     * queue empty; microtask checkpoints cannot help, no number of them lets a␊
+     * macrotask run.␊
+     *␊
+     * Returns nothing when there is nothing to wait for, which keeps disposal␊
+     * synchronous in the common case.␊
+     *␊
+     * The "already drained" flag is set only once a wait has actually finished.␊
+     * Scheduling a macrotask can fail — a host-provided or patched \`setImmediate\`␊
+     * that throws is enough — and a disposal that rejects stays retryable, so␊
+     * marking the drain complete up front would make the retry skip it and destroy␊
+     * the context with the barrier's settlements still queued.␊
+     *␊
+     * A wait that runs out of turns with the counter still nonzero rejects with␊
+     * \`ERR_NAPI_WASI_CLEANUP_PENDING\` for the same reason: at that point␊
+     * "finished" is indistinguishable from the stranding above, and destroying␊
+     * would discard the very settlement the wait was for. The rejection leaves the␊
+     * flag unset and disposal retryable.␊
+     */␊
+    function __drainWasmEnvCleanup() {␊
+      if (__emnapiWasmEnvCleanupDrained || !__emnapiWasmEnvCleanupRan) {␊
+        return␊
+      }␊
+      if (__emnapiWasmEnvCleanupDrainPromise) {␊
+        return __emnapiWasmEnvCleanupDrainPromise␊
+      }␊
+      const pending = __napiInstance?.exports?.napi_wasm_env_cleanup_pending␊
+      const observable = typeof pending === 'function'␊
+      if (observable) {␊
+        let queued␊
+        try {␊
+          queued = pending()␊
+        } catch {␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          return␊
+        }␊
+        if (!queued) {␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          return␊
+        }␊
+      }␊
+      const limit = observable␊
+        ? __WASM_ENV_CLEANUP_DRAIN_TURNS␊
+        : __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS␊
+      const drainPromise = (async () => {␊
+        let queued = 0␊
+        for (let turn = 0; turn < limit; turn++) {␊
+          await new Promise((resolve) => {␊
+            __scheduleMacrotask(resolve)␊
+          })␊
+          if (!observable) {␊
+            continue␊
+          }␊
+          try {␊
+            queued = pending()␊
+          } catch {␊
+            return␊
+          }␊
+          if (!queued) {␊
+            return␊
+          }␊
+        }␊
+        if (!observable) {␊
+          // Blind wait: without \`napi_wasm_env_cleanup_pending\` the bound IS the␊
+          // contract — there is nothing to consult, so finishing the turns is␊
+          // finishing the drain.␊
+          return␊
+        }␊
+        // The counter is still nonzero after every turn the bound allows. The wait␊
+        // stays bounded — but claiming success here would be indistinguishable from␊
+        // the stranding this drain exists to prevent: disposal would go on to␊
+        // destroy the context, whose cleanup hook discards the still-queued␊
+        // settlement with a null env, and the promise it was for hangs forever.␊
+        // Reject instead, as a retryable cleanup failure: the drained flag stays␊
+        // unset, dispose() (and the rollback) decline to destroy, and a later␊
+        // dispose() runs the drain again — by which time the queue has usually been␊
+        // delivered. A counter that is somehow stuck nonzero therefore costs each␊
+        // attempt at most another bounded wait and a rejection, never a stranded␊
+        // promise; the process-exit teardown still reclaims the context.␊
+        const drainError = new Error(␊
+          'the wasm environment still reports ' +␊
+            queued +␊
+            ' queued settlement(s) after ' +␊
+            limit +␊
+            ' event-loop turns; the context was not destroyed - retry dispose() to wait for the queue again',␊
+        )␊
+        drainError.code = 'ERR_NAPI_WASI_CLEANUP_PENDING'␊
+        throw drainError␊
+      })().then(␊
+        (value) => {␊
+          // Set only when the wait actually finished AND the queue was seen empty␊
+          // (or is unobservable): a drain that timed out with settlements still␊
+          // queued rejects above and must stay repeatable.␊
+          __emnapiWasmEnvCleanupDrained = true␊
+          __emnapiWasmEnvCleanupDrainPromise = undefined␊
+          return value␊
+        },␊
+        (error) => {␊
+          __emnapiWasmEnvCleanupDrainPromise = undefined␊
+          throw error␊
+        },␊
+      )␊
+      __emnapiWasmEnvCleanupDrainPromise = drainPromise␊
+      return drainPromise␊
+    }␊
+    ␊
     function __destroyEmnapiContext() {␊
       if (__emnapiContextDestroyed || __emnapiContext === undefined) {␊
         __emnapiContextDestroyed = true␊
@@ -939,7 +1610,7 @@ Generated by [AVA](https://avajs.dev).
       return __completeWasiDisposal()␊
     }␊
     ␊
-    function __startWasiDisposal() {␊
+    function __continueWasiDisposal() {␊
       const destroyResult = __destroyEmnapiContext()␊
       if (__isThenable(destroyResult)) {␊
         return Promise.resolve(destroyResult).then(__finishWasiDisposal)␊
@@ -947,6 +1618,18 @@ Generated by [AVA](https://avajs.dev).
       return __finishWasiDisposal()␊
     }␊
     ␊
+    function __startWasiDisposal() {␊
+      // 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.␊
+      __prepareWasmEnvCleanup()␊
+      const drainResult = __drainWasmEnvCleanup()␊
+      if (__isThenable(drainResult)) {␊
+        return Promise.resolve(drainResult).then(__continueWasiDisposal)␊
+      }␊
+      return __continueWasiDisposal()␊
+    }␊
+    ␊
     /**␊
      * Disposes this generated WASI binding.␊
      *␊
@@ -1018,8 +1701,7 @@ Generated by [AVA](https://avajs.dev).
       return cleanupErrors␊
     }␊
     ␊
-    function __rollbackWasiInitialization() {␊
-      const cleanupErrors = []␊
+    function __destroyContextForWasiRollback(cleanupErrors) {␊
       let destroyResult␊
       try {␊
         destroyResult = __destroyEmnapiContext()␊
@@ -1037,6 +1719,83 @@ Generated by [AVA](https://avajs.dev).
       return __finishWasiInitializationRollback(cleanupErrors)␊
     }␊
     ␊
+    /**␊
+     * Leaves a rollback that could not reach the queued settlements undestroyed, and␊
+     * hands it to whatever this flavor has that can still reclaim it.␊
+     */␊
+    function __retainFailedWasiRollback(cleanupErrors) {␊
+      try {␊
+        __retainWasiRollbackForRetry()␊
+      } catch (cleanupError) {␊
+        cleanupErrors.push(cleanupError)␊
+      }␊
+      return cleanupErrors␊
+    }␊
+    ␊
+    /**␊
+     * Initialization can fail *after* registration has already run, and registration␊
+     * runs with a live environment: a module-init hook can start async work and then␊
+     * return an error, and the promise it created may already have escaped into␊
+     * JavaScript. The barrier cancels that work and *queues* the settlement, so this␊
+     * path needs the same drain the ordinary disposal does — destroying without␊
+     * yielding discards the queue with a null env and strands the promise.␊
+     *␊
+     * Stays synchronous when nothing is queued, which covers every failure before␊
+     * \`beforeInit\`: there is no instance to run the barrier on, so nothing to drain.␊
+     *␊
+     * A barrier or drain that did *not* finish stops the rollback short of␊
+     * destroying, which is what \`dispose()\` already does — a rejected drain there␊
+     * never reaches \`__continueWasiDisposal\`. Destroying anyway is the worse of the␊
+     * two trades, and not because of what it saves:␊
+     *␊
+     *   - It cannot deliver the settlements. \`Context.destroy()\` runs the␊
+     *     threadsafe function's cleanup hook, which drains the queue with a null env␊
+     *     and discards it, so a promise that already escaped into JavaScript hangs␊
+     *     forever with nothing left that could ever settle it.␊
+     *   - It saves less than it looks. \`Context.destroy()\` stops JavaScript calls␊
+     *     and runs cleanup hooks; it does not free the wasm instance or its Memory,␊
+     *     which this module's scope holds either way. What stopping short retains is␊
+     *     the emnapi context's bookkeeping and its un-run cleanup hooks.␊
+     *   - Retry is not theoretical. A rollback that records a cleanup error is␊
+     *     already kept in the process-wide registry above, so re-\`require()\`ing this␊
+     *     file replays it instead of re-instantiating — and the \`6e15de6f\` flag fix␊
+     *     means the replay drains again rather than skipping it. Destroying first is␊
+     *     what makes that retained record useless.␊
+     *␊
+     * The residual cost is honest: the CJS flavor hands the context to its␊
+     * \`process.on('exit')\` teardown, so a process that never retries still reclaims␊
+     * it on the way out. The ESM browser flavor has no equivalent — a module that␊
+     * throws while evaluating is permanently errored, so re-importing rethrows␊
+     * without re-running this file — and there the context stays until the realm␊
+     * goes away. That is the deliberate choice: a hung promise is a silent liveness␊
+     * bug with no upper bound, while the retained bookkeeping is bounded by the page.␊
+     */␊
+    function __rollbackWasiInitialization() {␊
+      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)␊
+    }␊
+    ␊
     let __wasiModule␊
     let __napiModule␊
     ␊