@napi-rs/cli 3.8.2 → 3.8.4

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

@@ -8,9 +8,16 @@ let __napiInstance
 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 (
@@ -81,10 +88,168 @@ function __prepareWasmEnvCleanup() {
   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
@@ -162,7 +327,7 @@ function __finishWasiDisposal() {
   return __completeWasiDisposal()
 }
 
-function __startWasiDisposal() {
+function __continueWasiDisposal() {
   const destroyResult = __destroyEmnapiContext()
   if (__isThenable(destroyResult)) {
     return Promise.resolve(destroyResult).then(__finishWasiDisposal)
@@ -170,6 +335,18 @@ function __startWasiDisposal() {
   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.
  *
@@ -241,8 +418,7 @@ function __finishWasiInitializationRollback(cleanupErrors) {
   return cleanupErrors
 }
 
-function __rollbackWasiInitialization() {
-  const cleanupErrors = []
+function __destroyContextForWasiRollback(cleanupErrors) {
   let destroyResult
   try {
     destroyResult = __destroyEmnapiContext()
@@ -259,6 +435,83 @@ function __rollbackWasiInitialization() {
   }
   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)
+}
 `
 
 export const createWasiBrowserBinding = (
@@ -271,6 +524,10 @@ export const createWasiBrowserBinding = (
   errorEvent = false,
   threads = true,
 ) => {
+  // Threaded builds always get a pre-created worker pool (see
+  // `reuseWorkerOption` below), and pool pre-creation is asynchronous, so
+  // they always initialize asynchronously.
+  const effectiveAsyncInit = asyncInit || threads
   const fsImport = fs
     ? buffer
       ? `import { memfs, Buffer } from '@napi-rs/wasm-runtime/fs'`
@@ -317,17 +574,55 @@ const __wasi = new __WASI({
   const emnapiInjectBuffer = buffer
     ? '  __emnapiContext.features.Buffer = Buffer\n'
     : ''
-  const emnapiInstantiateImport = asyncInit
+  const emnapiInstantiateImport = effectiveAsyncInit
     ? `instantiateNapiModule as __emnapiInstantiateNapiModule`
     : `instantiateNapiModuleSync as __emnapiInstantiateNapiModuleSync`
-  const emnapiInstantiateCall = asyncInit
+  const emnapiInstantiateCall = effectiveAsyncInit
     ? `await __emnapiInstantiateNapiModule`
     : `__emnapiInstantiateNapiModuleSync`
+  // The `reuseWorker` pool is what lets addon Rust code spawn threads while
+  // the calling thread is blocked inside the wasm call: a browser cannot
+  // start a worker until the blocking thread returns to its event loop, so
+  // a thread spawned mid-call can never boot and the caller deadlocks
+  // waiting for it. With a pre-created pool, spawning is only a message to
+  // an already-running worker.
+  //
+  // Its size comes from `navigator.hardwareConcurrency` at runtime (logical
+  // cores, floored at 2, with a fallback for privacy-fuzzed or missing
+  // values): a constant undersizes both ends of the range — big desktops
+  // leave parallelism on the table, and a fuzzed "2 cores" would
+  // oversubscribe.
+  //
+  // The reuse pool is sized as `__asyncWorkPoolSize + __workerPoolSize`
+  // because emnapi's async-work pool draws its workers from the SAME reuse
+  // pool: the async reservation must be included or async-work
+  // initialization can starve the reuse pool before addon threads spawn.
+  //
+  // `strict` is deliberately NOT set. Review suggested it so exhaustion
+  // errors instead of allocating a fresh worker, but it breaks
+  // spawn-and-return workloads (e.g. `testWorkers` in examples/napi, which
+  // spawns workers and joins them on a helper thread): at exhaustion their
+  // `std::thread::spawn` panics on EAGAIN. Without `strict` the fallback
+  // allocates a fresh worker, which boots normally once the spawning
+  // parent returns to its event loop — and for joins inside a blocked
+  // call, the pre-created pool is what those calls draw from anyway.
+  const workerPoolSizeBinding = threads
+    ? `const __asyncWorkPoolSize = 4
+const __workerPoolSize = Math.max(
+  2,
+  globalThis.navigator?.hardwareConcurrency ?? 4,
+)
+
+`
+    : ''
+  const reuseWorkerOption = threads
+    ? `    reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },\n`
+    : ''
   const workerRuntimeImport = threads
     ? `  createOnMessage as __wasmCreateOnMessageForFsProxy,\n`
     : ''
   const memoryName = threads ? '__sharedMemory' : '__wasmMemory'
-  const asyncWorkPoolOption = `    asyncWorkPoolSize: ${threads ? 4 : 0},
+  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
@@ -380,7 +675,7 @@ const ${memoryName} = new WebAssembly.Memory({
   maximum: ${maximumMemory},
 ${threads ? '  shared: true,\n' : ''}\
 })
-
+${workerPoolSizeBinding}\
 let __emnapiContext
 ${emnapiContextLifecycle}
 let __wasiModule
@@ -397,6 +692,7 @@ try {
   } = ${emnapiInstantiateCall}(__wasmFile, {
     context: __emnapiContext,
 ${asyncWorkPoolOption}\
+${reuseWorkerOption}\
 ${emnapiPluginOption}\
     wasi: __wasi,
 ${workerOption}\
@@ -591,6 +887,129 @@ function __attachCleanupError(__error, __cleanupError) {
   } catch {}
 }
 
+// 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.
+ */
+function __drainWasmEnvCleanup(__instance) {
+  const __pending = __instance?.exports.napi_wasm_env_cleanup_pending
+  const __observable = typeof __pending === 'function'
+  if (__observable) {
+    let __queued
+    try {
+      __queued = __pending()
+    } catch {
+      return
+    }
+    if (!__queued) {
+      return
+    }
+  }
+  const __limit = __observable
+    ? __WASM_ENV_CLEANUP_DRAIN_TURNS
+    : __WASM_ENV_CLEANUP_BLIND_DRAIN_TURNS
+  return (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: \`__prepareForDisposal\`
+    // leaves its drained flag unset, dispose() (and the instantiation-failure
+    // path) 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 managed
+    // beforeExit destroyer 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
+  })()
+}
+
 function __createLifecycleReentryError(__operation) {
   const __error = new Error(
     __operation +
@@ -995,6 +1414,64 @@ async function __createInstance(
   let __destroyOwnedContext
   let __destroyManagedOwnedContext
   let __napiInstance
+  let __wasmEnvCleanupRan = false
+  let __wasmEnvCleanupPrepared = false
+  let __wasmEnvCleanupDrained = false
+  let __wasmEnvCleanupDrainPromise
+  const __prepareEnvCleanup = () => {
+    if (__wasmEnvCleanupPrepared) {
+      return
+    }
+    const __prepareWasmEnvCleanup =
+      __napiInstance?.exports.napi_prepare_wasm_env_cleanup
+    if (typeof __prepareWasmEnvCleanup === 'function') {
+      __prepareWasmEnvCleanup()
+      __wasmEnvCleanupRan = true
+    }
+    __wasmEnvCleanupPrepared = true
+  }
+  // The barrier + settlement drain, hoisted out of the context destroyer so the
+  // drain can yield without widening the destroyer's reentry window. Both
+  // yielding paths run it — dispose() and the initialization-failure rollback.
+  // The destroyer still runs the barrier itself (idempotently) for the one path
+  // that cannot yield: managed beforeExit cleanup of an instance whose rollback
+  // is being retried.
+  //
+  // "Drained" is recorded only once a wait has actually finished. Scheduling a
+  // macrotask can fail — a host-provided or patched \`setImmediate\` that throws
+  // is enough — and dispose() stays retryable after it rejects, so marking the
+  // drain complete up front would make the retry skip it and destroy the context
+  // with the barrier's settlements still queued.
+  const __prepareForDisposal = () => {
+    if (__wasmEnvCleanupDrained) {
+      return
+    }
+    if (__wasmEnvCleanupDrainPromise) {
+      return __wasmEnvCleanupDrainPromise
+    }
+    __prepareEnvCleanup()
+    if (!__wasmEnvCleanupRan) {
+      return
+    }
+    const __drained = __drainWasmEnvCleanup(__napiInstance)
+    if (!__drained || typeof __drained.then !== 'function') {
+      __wasmEnvCleanupDrained = true
+      return
+    }
+    const __tracked = __drained.then(
+      (__value) => {
+        __wasmEnvCleanupDrained = true
+        __wasmEnvCleanupDrainPromise = undefined
+        return __value
+      },
+      (__error) => {
+        __wasmEnvCleanupDrainPromise = undefined
+        throw __error
+      },
+    )
+    __wasmEnvCleanupDrainPromise = __tracked
+    return __tracked
+  }
   const __destroyBeforeExit = __beforeExitDestroy
     ? async () => {
         if (__lifecycleState === 'failed') {
@@ -1020,13 +1497,7 @@ async function __createInstance(
     destroy,
     destroyForModuleLifecycle,
     registerCleanup: __registerCleanup,
-  } = await __createManagedEmnapiContext(() => {
-    const __prepareWasmEnvCleanup =
-      __napiInstance?.exports.napi_prepare_wasm_env_cleanup
-    if (typeof __prepareWasmEnvCleanup === 'function') {
-      __prepareWasmEnvCleanup()
-    }
-  })
+  } = await __createManagedEmnapiContext(__prepareEnvCleanup)
   __destroyEmnapiContext = destroy
   __destroyOwnedContext = () => __destroyEmnapiContext()
   __destroyManagedOwnedContext = destroyForModuleLifecycle
@@ -1072,6 +1543,13 @@ ${emnapiInjectBuffer}\
         if (__lifecycleState !== 'failed') {
           __lifecycleState = 'disposal'
         }
+        // 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()
+        if (__drained) {
+          await __drained
+        }
         return __beforeExitDestroy
           ? __destroyManagedOwnedContext()
           : __destroyOwnedContext()
@@ -1079,6 +1557,23 @@ ${emnapiInjectBuffer}\
     }
   } catch (error) {
     __lifecycleState = 'failed'
+    // Instantiation can fail *after* registration has 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. Settle what the barrier cancels before the context is
+    // destroyed, exactly like dispose() does; destroying without yielding
+    // discards the queue with a null env. Undefined unless something is queued,
+    // so a failure before beforeInit costs no extra turn.
+    let __settlementsUnreached = false
+    try {
+      const __drained = __prepareForDisposal()
+      if (__drained) {
+        await __drained
+      }
+    } catch (drainError) {
+      __attachCleanupError(error, drainError)
+      __settlementsUnreached = true
+    }
     let __registrationError
     let __registrationFailed = false
     if (!__beforeExitDestroy) {
@@ -1092,6 +1587,25 @@ ${emnapiInjectBuffer}\
         __registrationFailed = true
       }
     }
+    if (__settlementsUnreached) {
+      // The barrier or the drain did not finish, so the settlements it queued
+      // are still in the threadsafe-function queue. Destroying now runs the
+      // cleanup hook that drains that queue with a null env and discards it,
+      // stranding a promise that already escaped into JavaScript — with nothing
+      // left that could ever settle it. dispose() refuses to destroy for exactly
+      // this reason (a rejected drain there never reaches the destroy), so this
+      // path refuses too.
+      //
+      // Nothing leaks. The registration just above — and, for the singleton, the
+      // one made before instantiation — leaves this context in
+      // \`__managedEmnapiContextDestroyers\`, so beforeExit destroys it and
+      // dispose() can retry it. Only the destruction is deferred, and the turns
+      // that pass in the meantime are exactly what the queue needed.
+      try {
+        __registerManagedBeforeExitListener()
+      } catch {}
+      throw error
+    }
     try {
       await __destroyManagedOwnedContext()
     } catch (disposeError) {
@@ -1646,10 +2160,18 @@ function __removeWasiExitListener() {
 
 function __disposeWasiBindingAtExit() {
   __wasiExitListenerRegistered = false
+  // An 'exit' handler cannot yield, so it cannot wait for queued promise
+  // settlements the way __startWasiDisposal does — the process is leaving and
+  // those promises have no observer left anyway. Run the synchronous teardown
+  // directly. Every step is idempotent, which also makes this the synchronous
+  // finish for a disposal that is still waiting for its drain.
   try {
-    const result = __disposeWasiBinding()
-    if (__isThenable(result)) {
-      void Promise.resolve(result).catch(() => {})
+    __destroyEmnapiContext()
+  } catch {}
+  try {
+    const workerResult = __terminateWasiWorkers()
+    if (__isThenable(workerResult)) {
+      void Promise.resolve(workerResult).catch(() => {})
     }
   } catch {}
 }
@@ -1665,6 +2187,13 @@ function __registerWasiExitListener() {
 }
 
 __completeWasiDisposal = __removeWasiExitListener
+// A rollback that could not reach the queued settlements keeps the context so
+// the registry replay above can retry it. Nothing forces that replay to happen,
+// so hand the context to the same synchronous teardown a successful load uses:
+// a process that exits without ever retrying still runs the cleanup hooks. The
+// handler cannot yield, so it does not settle anything — but by then the process
+// is leaving and those promises have no observer left anyway.
+__retainWasiRollbackForRetry = __registerWasiExitListener
 
 function __captureEmnapiAutoDestroyListener() {
   if (