@napi-rs/cli 3.9.1 → 3.10.0

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

@@ -1,13 +1,139 @@
+import {
+  BINDING_TARGET_STAMP_HELPER,
+  NAPI_BINDING_TARGET_EXPORT,
+  NAPI_BINDING_TARGET_STAMP_FN,
+} from './binding-target.js'
+
 const WASI_DISPOSE_SYMBOL = 'napi.rs.wasi.dispose'
 const WASI_ROLLBACK_REGISTRY_SYMBOL = 'napi.rs.wasi.rollback.registry.v1'
 
-const emnapiContextLifecycle = `
+/**
+ * `Context.destroy()` disables JavaScript calls *before* it runs cleanup hooks
+ * (`setStopping` -> `setCanCallIntoJs(false)` -> `runCleanup`), and the
+ * threadsafe function's cleanup hook then drains its queue with a null env and
+ * discards it. So `napi_prepare_wasm_env_cleanup` has to run while the
+ * environment is still live — before `destroy()`, never from a hook inside it.
+ *
+ * The loaders already order their own teardown that way. A `destroy()` called
+ * by anyone else — an embedder or test harness holding the context, emnapi's
+ * own `beforeExit` auto-destroy on a host where `suppressDestroy()` is absent —
+ * would skip the barrier and discard exactly the settlements it exists to
+ * cancel and deliver. Own the ordering on the object rather than on each call
+ * site: shadow `destroy` once at creation, so every caller gets the barrier.
+ *
+ * The barrier is reentrant-hostile, so the wrapper has to be reentrancy-aware.
+ * `napi_prepare_wasm_env_cleanup` settles the promises it cancels synchronously,
+ * under a non-reentrant lifecycle mutex on the Rust side; a V8 promise hook
+ * (`promiseHooks.onSettled`, or the `async_hooks` hook `AsyncLocalStorage`
+ * installs) that calls `destroy()` therefore re-enters this wrapper from inside
+ * the barrier, and calling the barrier again aborts the whole wasm instance.
+ * While a prepare is in flight the nested `destroy()` is a no-op rather than a
+ * deferred one: the frame that started the barrier destroys the moment it
+ * returns, still synchronously, and `Context.destroy()` is typed `void`, so
+ * answering `undefined` loses nothing a caller could have observed. Letting the
+ * nested call through instead would tear the environment down mid-barrier and
+ * strand every settlement the barrier had not reached yet.
+ *
+ * Defensive, not strict: a context whose `destroy` cannot be read or redefined
+ * is returned unchanged rather than failing the load. A barrier that throws
+ * still propagates, exactly as it does from `__destroyEmnapiContext`.
+ *
+ * This is NOT a replacement for `dispose()`: only the disposal chain yields
+ * event-loop turns until `napi_wasm_env_cleanup_pending` reads zero, so a
+ * direct `destroy()` still cannot wait for a settlement queued by another
+ * thread. It delivers everything the barrier settles on this thread.
+ */
+const emnapiContextDestroyWrapper = `
+function __wrapEmnapiContextDestroyForSettlement(
+  context,
+  prepareEnvCleanup,
+  isPreparingEnvCleanup,
+) {
+  let destroy
+  try {
+    destroy = context.destroy
+  } catch {
+    return context
+  }
+  if (typeof destroy !== 'function') {
+    return context
+  }
+  try {
+    Object.defineProperty(context, 'destroy', {
+      configurable: true,
+      enumerable: false,
+      writable: true,
+      value: function () {
+        // Reentered from a promise hook that fired inside the barrier: the
+        // frame running it destroys as soon as it returns.
+        if (isPreparingEnvCleanup?.()) {
+          return
+        }
+        prepareEnvCleanup?.()
+        return Reflect.apply(destroy, this, arguments)
+      },
+    })
+  } catch {}
+  return context
+}
+`
+
+/**
+ * Host teardown must run while the environment can still accept N-API calls,
+ * and after the settlement drain: the drain is what lets the barrier's queued
+ * promise settlements reach JavaScript, and the task host is what publishes the
+ * CurrentThread turns they may still need. `__destroyEmnapiContext` is the
+ * single funnel every teardown path reaches — `dispose()`, the initialization
+ * rollback, and the CJS 'exit' handler — and it is reached only after
+ * `__startWasiDisposal` / the rollback have already prepared and drained, so
+ * one call there covers all three.
+ */
+const createEmnapiContextLifecycle = (asyncRuntime: boolean) => {
+  const currentThreadHosts = asyncRuntime
+    ? `
+let __currentThreadHostsDisposer
+
+function __reportCurrentThreadHostDisposalError(error) {
+  try {
+    const consoleHost = globalThis.console
+    if (consoleHost && typeof consoleHost.error === 'function') {
+      consoleHost.error(error)
+    }
+  } catch {}
+}
+
+/**
+ * Unregister the CurrentThread task and timer hosts this loader installed.
+ * Idempotent, and never throws: an unregister failure must not abort
+ * \`Context.destroy()\`, which would retain the whole environment over a
+ * bookkeeping error. The failure is reported instead.
+ */
+function __disposeCurrentThreadHosts() {
+  const dispose = __currentThreadHostsDisposer
+  if (dispose === undefined) {
+    return
+  }
+  __currentThreadHostsDisposer = undefined
+  try {
+    dispose()
+  } catch (error) {
+    __reportCurrentThreadHostDisposalError(error)
+  }
+}
+`
+    : ''
+  const disposeCurrentThreadHosts = asyncRuntime
+    ? '  __disposeCurrentThreadHosts()\n'
+    : ''
+
+  return `
 const __wasiDisposeSymbol = Symbol.for('${WASI_DISPOSE_SYMBOL}')
 const __wasiWorkers = new Set()
 let __napiInstance
 let __emnapiContextDestroyed = false
 let __emnapiContextDestroyPromise
 let __emnapiWasmEnvCleanupPrepared = false
+let __emnapiWasmEnvCleanupPreparing = false
 let __emnapiWasmEnvCleanupRan = false
 let __emnapiWasmEnvCleanupDrained = false
 let __emnapiWasmEnvCleanupDrainPromise
@@ -18,7 +144,7 @@ let __completeWasiDisposal = function () {}
 // that stopped short of destroying the context. See
 // \`__rollbackWasiInitialization\`.
 let __retainWasiRollbackForRetry = function () {}
-
+${currentThreadHosts}
 function __isThenable(value) {
   return (
     value !== null &&
@@ -80,14 +206,26 @@ function __attachCleanupErrors(error, cleanupErrors) {
   } catch {}
   return aggregate
 }
+${emnapiContextDestroyWrapper}
+function __isPreparingWasmEnvCleanup() {
+  return __emnapiWasmEnvCleanupPreparing
+}
 
 function __prepareWasmEnvCleanup() {
-  if (__emnapiWasmEnvCleanupPrepared) {
+  if (__emnapiWasmEnvCleanupPrepared || __emnapiWasmEnvCleanupPreparing) {
     return
   }
   const prepare = __napiInstance?.exports?.napi_prepare_wasm_env_cleanup
   if (typeof prepare === 'function') {
-    prepare()
+    // The addon settles the promises it cancels synchronously, under a
+    // non-reentrant lifecycle mutex: anything a promise hook calls from in
+    // here must not reach this export again.
+    __emnapiWasmEnvCleanupPreparing = true
+    try {
+      prepare()
+    } finally {
+      __emnapiWasmEnvCleanupPreparing = false
+    }
     __emnapiWasmEnvCleanupRan = true
   }
   __emnapiWasmEnvCleanupPrepared = true
@@ -259,6 +397,7 @@ function __destroyEmnapiContext() {
     return __emnapiContextDestroyPromise
   }
 
+${disposeCurrentThreadHosts}\
   __prepareWasmEnvCleanup()
   const result = __emnapiContext.destroy()
   if (!__isThenable(result)) {
@@ -513,6 +652,7 @@ function __rollbackWasiInitialization() {
   return __destroyContextForWasiRollback(cleanupErrors)
 }
 `
+}
 
 export const createWasiBrowserBinding = (
   wasiFilename: string,
@@ -523,11 +663,24 @@ export const createWasiBrowserBinding = (
   buffer = false,
   errorEvent = false,
   threads = true,
+  // `platformArchABI` of the flavor this loader belongs to. Defaults from
+  // `threads` so callers that predate the parameter keep their identity.
+  platformArchABI = threads ? 'wasm32-wasi' : 'wasm32-wasip1',
+  asyncRuntime = false,
 ) => {
   // 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 asyncRuntimeImport = asyncRuntime
+    ? `import { installCurrentThreadHosts as __installCurrentThreadHosts } from '@napi-rs/async-runtime'\n`
+    : ''
+  const installAsyncRuntimeHosts = asyncRuntime
+    ? `  __currentThreadHostsDisposer = __installCurrentThreadHosts(
+    __napiModule.exports,
+  )
+`
+    : ''
   const fsImport = fs
     ? buffer
       ? `import { memfs, Buffer } from '@napi-rs/wasm-runtime/fs'`
@@ -652,8 +805,11 @@ ${workerRuntimeImport}\
   WASI as __WASI,
 } from '@napi-rs/wasm-runtime'
 import { createContext as __emnapiCreateContext } from '@emnapi/runtime'
+${asyncRuntimeImport}\
 ${fsImport}
 ${bufferImport}
+export const __napiBindingTarget = '${platformArchABI}'
+${BINDING_TARGET_STAMP_HELPER}
 ${wasiCreation}
 
 const __wasmUrl = new URL('./${wasiFilename}.wasm', import.meta.url).href
@@ -677,12 +833,16 @@ ${threads ? '  shared: true,\n' : ''}\
 })
 ${workerPoolSizeBinding}\
 let __emnapiContext
-${emnapiContextLifecycle}
+${createEmnapiContextLifecycle(asyncRuntime)}
 let __wasiModule
 let __napiModule
 
 try {
-  __emnapiContext = __emnapiCreateContext({ autoDestroy: false })
+  __emnapiContext = __wrapEmnapiContextDestroyForSettlement(
+    __emnapiCreateContext({ autoDestroy: false }),
+    __prepareWasmEnvCleanup,
+    __isPreparingWasmEnvCleanup,
+  )
   __emnapiContext.suppressDestroy()
   ${emnapiInjectBuffer}
   ;({
@@ -715,6 +875,13 @@ ${workerOption}\
     },
   }))
   __publishWasiDispose(__napiModule.exports)
+${installAsyncRuntimeHosts}\
+  // The default export hands out this object; a named module export does not
+  // travel with it, so carry the marker on the binding itself too. After the
+  // host install, which hands the same object to addon-provided registration
+  // functions that may put anything on it, and inside this \`try\`, so a claimed
+  // name fails the load through the rollback below rather than past it.
+  ${NAPI_BINDING_TARGET_STAMP_FN}(__napiModule.exports, __napiBindingTarget)
 } catch (error) {
   const cleanupErrors = await __rollbackWasiInitialization()
   throw __attachCleanupErrors(error, cleanupErrors)
@@ -722,19 +889,232 @@ ${workerOption}\
 `
 }
 
+/**
+ * Module-scope prelude of the deferred loader: the compiled-in memory
+ * descriptor, the per-module instance counters, and the resolver that turns a
+ * `createInstance()` options bag into the one `WebAssembly.Memory` that
+ * instance runs on.
+ *
+ * Nothing here allocates — workerd bans allocation in global scope, so the
+ * Memory itself is created inside `__createInstance`.
+ */
+const DEFERRED_MEMORY_PREAMBLE = (
+  initialMemory: number,
+  maximumMemory: number,
+) => `
+export const WASM_MEMORY = Object.freeze({
+  initialPages: ${initialMemory},
+  maximumPages: ${maximumMemory},
+  pageBytes: 65536,
+  initialBytes: ${initialMemory} * 65536,
+  maximumBytes: ${maximumMemory} * 65536,
+})
+
+let __createdInstances = 0
+let __liveInstances = 0
+
+/**
+ * Counters for instances created by THIS module evaluation, not process-wide:
+ * a second bundled copy of this loader keeps its own. Only successfully
+ * created instances are counted, and \`liveInstances\` drops when an instance's
+ * \`dispose()\` resolves.
+ *
+ * \`declaredInitialMemoryBytes\` is declared address space, not a host's
+ * committed-memory metric; pair it with host telemetry rather than treating it
+ * as a quota.
+ */
+export function getDeferredRuntimeStats() {
+  return Object.freeze({
+    createdInstances: __createdInstances,
+    liveInstances: __liveInstances,
+    declaredInitialMemoryBytes: WASM_MEMORY.initialBytes,
+  })
+}
+
+const __arrayBufferByteLengthGetter = Object.getOwnPropertyDescriptor(
+  ArrayBuffer.prototype,
+  'byteLength',
+).get
+const __memoryBufferGetter = Object.getOwnPropertyDescriptor(
+  WebAssembly.Memory.prototype,
+  'buffer',
+).get
+// One managed initialization per Memory, success or failure: an attempt that
+// throws may already have written into linear memory, so the bytes are not a
+// clean slate for a second instance. Module-local, like the counters above.
+const __claimedMemories = new WeakSet()
+
+function __resolveInstanceMemory(__options) {
+  const __provided = __options == null ? undefined : __options.memory
+  if (__provided === undefined || __provided === null) {
+    // Page counts are handed to the engine unvalidated: it already rejects a
+    // negative, over-4GiB or below-maximum value with a precise message, and a
+    // second set of bounds here would only drift from it.
+    const __allocated = new WebAssembly.Memory({
+      initial:
+        __options != null && __options.initialMemoryPages !== undefined
+          ? __options.initialMemoryPages
+          : WASM_MEMORY.initialPages,
+      maximum:
+        __options != null && __options.maximumMemoryPages !== undefined
+          ? __options.maximumMemoryPages
+          : WASM_MEMORY.maximumPages,
+    })
+    // Claimed like a caller-provided one. The handle publishes it as
+    // \`instance.memory\`, so handing it back to \`createInstance()\` is as easy
+    // as passing your own twice, and it would put two live instances on one
+    // linear memory: each initialization rewrites the emnapi/WASI state the
+    // other is still running on.
+    __claimedMemories.add(__allocated)
+    return __allocated
+  }
+  if (
+    __options.initialMemoryPages !== undefined ||
+    __options.maximumMemoryPages !== undefined
+  ) {
+    throw new TypeError(
+      'Pass either memory or initialMemoryPages/maximumMemoryPages, not both',
+    )
+  }
+  let __buffer
+  try {
+    // Brand check: the getter throws for anything that is not a genuine
+    // WebAssembly.Memory, including a cross-realm look-alike object.
+    __buffer = Reflect.apply(__memoryBufferGetter, __provided, [])
+  } catch {
+    throw new TypeError('memory must be an unshared WebAssembly.Memory')
+  }
+  try {
+    // Throws for a SharedArrayBuffer. This loader has no threads, and shared
+    // growth does not detach: external views handed to the addon would
+    // silently outlive the bytes they describe.
+    Reflect.apply(__arrayBufferByteLengthGetter, __buffer, [])
+  } catch {
+    throw new TypeError(
+      'The deferred loader requires an unshared WebAssembly.Memory',
+    )
+  }
+  // The intrinsic getters above accept a genuine Memory from ANY realm, but
+  // the loader's dependencies do not: \`WASI.setMemory\` in
+  // \`@napi-rs/wasm-runtime\` and emnapi identify a Memory with a realm-local
+  // \`instanceof\`. A Memory built in another realm (a \`node:vm\` context, a
+  // same-origin iframe) would pass every check here and only fail deep inside
+  // initialization. Reject it up front, and before the claim below, so the
+  // caller keeps it usable in the realm that made it.
+  if (!(__provided instanceof WebAssembly.Memory)) {
+    throw new TypeError(
+      'memory must be a WebAssembly.Memory created in the same realm as this loader',
+    )
+  }
+  if (__claimedMemories.has(__provided)) {
+    throw new TypeError(
+      'This WebAssembly.Memory has already been used for a deferred initialization attempt and cannot be reused, including after a failed initialization or a disposal',
+    )
+  }
+  // Last step, after every check: a rejected option bag must leave the Memory
+  // unclaimed, or a caller could not fix the call and retry with it.
+  __claimedMemories.add(__provided)
+  return __provided
+}
+`
+
 export const createWasiDeferredBrowserBinding = (
   wasiFilename: string,
+  // Fed by `napi.wasm.threadlessInitialMemory ?? napi.wasm.initialMemory`.
   // 64 MiB leaves headroom for JS/runtime state under workerd's 128 MiB
   // isolate limit. The regular Node/browser loaders retain their historical
   // 4,000-page default.
   initialMemory = 1024,
   maximumMemory = 65536,
   buffer = false,
+  // Deferred loaders are only emitted for non-threaded flavors, so the
+  // default matches the only flavor `napi build` generates one for.
+  platformArchABI = 'wasm32-wasip1',
+  asyncRuntime = false,
 ) => {
   const bufferImport = buffer ? `import { Buffer } from 'buffer'` : ''
   const emnapiInjectBuffer = buffer
     ? '    __emnapiContext.features.Buffer = Buffer\n'
     : ''
+  // This flavor creates N independent instances per realm, each with its own
+  // emnapi context and its own `napiModule.exports`, so it uses the
+  // per-instance helpers rather than `installCurrentThreadHosts`: those return
+  // exact, idempotent disposers with no realm-global dedup, roll themselves
+  // back on a setup failure, and degrade to a no-op disposer when the realm has
+  // no `setTimeout`/`clearTimeout`.
+  // The `/workerd` subpath, not the barrel: the barrel's `index.cjs` also
+  // requires `current-thread-hosts.cjs`, whose realm-global registry and Node
+  // timer-handle bookkeeping this flavor never executes, and a CJS barrel is
+  // not tree-shakeable out of a worker bundle.
+  const asyncRuntimeImport = asyncRuntime
+    ? `import {
+  registerWorkerdCurrentThreadTaskHost as __registerWorkerdCurrentThreadTaskHost,
+  registerWorkerdTimerHost as __registerWorkerdTimerHost,
+} from '@napi-rs/async-runtime/workerd'
+`
+    : ''
+  // `__createManagedEmnapiContext` calls `__prepareEnvCleanup?.()` on EVERY
+  // destroy path (dispose(), managed beforeExit, module lifecycle), so a second
+  // hook next to it covers them all with one edit.
+  const managedHostDisposeParam = asyncRuntime ? '  __disposeHosts,\n' : ''
+  const managedHostDisposeCall = asyncRuntime
+    ? `      __disposeHosts?.()\n`
+    : ''
+  const instanceHostState = asyncRuntime
+    ? `  let __disposeInstanceHosts
+  const __reportInstanceHostDisposalError = (__error) => {
+    try {
+      const __consoleHost = globalThis.console
+      if (__consoleHost && typeof __consoleHost.error === 'function') {
+        __consoleHost.error(__error)
+      }
+    } catch {}
+  }
+  // Runs between the settlement drain and \`Context.destroy()\`; never throws,
+  // for the same reason the eager loaders' disposer does not.
+  const __disposeHostsBeforeDestroy = () => {
+    const __dispose = __disposeInstanceHosts
+    if (__dispose === undefined) {
+      return
+    }
+    __disposeInstanceHosts = undefined
+    __dispose()
+  }
+`
+    : ''
+  const installInstanceHosts = asyncRuntime
+    ? `    const __disposeTaskHost = __registerWorkerdCurrentThreadTaskHost(
+      __napiModule.exports,
+    )
+    try {
+      const __disposeTimerHost = __registerWorkerdTimerHost(
+        __napiModule.exports,
+      )
+      __disposeInstanceHosts = () => {
+        try {
+          __disposeTimerHost()
+        } catch (__error) {
+          __reportInstanceHostDisposalError(__error)
+        }
+        try {
+          __disposeTaskHost()
+        } catch (__error) {
+          __reportInstanceHostDisposalError(__error)
+        }
+      }
+    } catch (__error) {
+      try {
+        __disposeTaskHost()
+      } catch (__cleanupError) {
+        __attachCleanupError(__error, __cleanupError)
+      }
+      throw __error
+    }
+`
+    : ''
+  const managedHostDisposeArg = asyncRuntime
+    ? '    __disposeHostsBeforeDestroy,\n'
+    : ''
   return `import {
   emnapiAsyncWorkPlugin as __emnapiAsyncWorkPlugin,
   emnapiTSFNPlugin as __emnapiTSFNPlugin,
@@ -742,7 +1122,11 @@ export const createWasiDeferredBrowserBinding = (
   WASI as __WASI,
 } from '@napi-rs/wasm-runtime'
 import { createContext as __emnapiCreateContext } from '@emnapi/runtime'
+${asyncRuntimeImport}\
 ${bufferImport}
+${DEFERRED_MEMORY_PREAMBLE(initialMemory, maximumMemory)}
+export const __napiBindingTarget = '${platformArchABI}'
+${BINDING_TARGET_STAMP_HELPER}
 
 /**
  * Deferred, workerd-safe instantiation: no top-level I/O, no compile-from-bytes.
@@ -841,7 +1225,7 @@ async function __normalizeModuleForEmnapi(__module) {
       'provide structuredClone or MessageChannel support.',
   )
 }
-
+${emnapiContextDestroyWrapper}
 function __captureEmnapiAutoDestroyListener(__process) {
   if (
     !__process ||
@@ -1229,7 +1613,10 @@ function __registerManagedEmnapiContext(__process, __destroy) {
   }
 }
 
-async function __createManagedEmnapiContext(__prepareEnvCleanup) {
+async function __createManagedEmnapiContext(
+  __prepareEnvCleanup,
+  __isPreparingEnvCleanup,
+${managedHostDisposeParam}) {
   const __process =
     typeof process === 'object' && process !== null ? process : undefined
   const __finishAutoDestroyCapture =
@@ -1238,7 +1625,11 @@ async function __createManagedEmnapiContext(__prepareEnvCleanup) {
   let __contextInitializationError
   let __contextInitializationFailed = false
   try {
-    __emnapiContext = __emnapiCreateContext({ autoDestroy: false })
+    __emnapiContext = __wrapEmnapiContextDestroyForSettlement(
+      __emnapiCreateContext({ autoDestroy: false }),
+      __prepareEnvCleanup,
+      __isPreparingEnvCleanup,
+    )
     // emnapi 2.x still registers an unconditional process.once('beforeExit')
     // auto-destroy listener on Node hosts, and suppressDestroy() only
     // neutralizes its callback without removing it. This loader must stay
@@ -1288,6 +1679,18 @@ async function __createManagedEmnapiContext(__prepareEnvCleanup) {
       // Context.destroy() disables JS before cleanup hooks run, so settle
       // runtime-owned promises while this environment can still call JS.
       __prepareEnvCleanup?.()
+      if (__isPreparingEnvCleanup?.()) {
+        // Reached from inside the barrier, so \`Context.destroy()\` below would
+        // hit the wrapper's in-flight no-op. Recording that as a completed
+        // destroy is what makes the frame that *did* start the barrier skip the
+        // real one afterwards, leaving the context retained with its cleanup
+        // hooks unrun. Refuse instead: nothing is flagged, the context stays
+        // registered for managed beforeExit cleanup, and a later destroy still
+        // works. dispose() coalesces reentrancy before it can get here, so this
+        // is the backstop for any other caller that manages to.
+        throw __createLifecycleReentryError('dispose')
+      }
+${managedHostDisposeCall}\
       __result = __emnapiContext.destroy()
     } catch (error) {
       __finishDestroyInvocation()
@@ -1392,6 +1795,7 @@ async function __createManagedEmnapiContext(__prepareEnvCleanup) {
 
 async function __createInstance(
   __wasmInput,
+  __options,
   __beforeExitDestroy,
   __onManagedDestroyer,
 ) {
@@ -1401,31 +1805,40 @@ async function __createInstance(
     version: 'preview1',
   })
   // The wasm module is linked with \`--import-memory\`, so a Memory must be
-  // provided. It is allocated here in function scope (workerd bans global
-  // scope allocation) and is not shared (no threads, no SharedArrayBuffer).
-  // Allocate it before the emnapi context so a host memory-limit failure cannot
-  // leak a context that never reaches instantiation.
-  const __wasmMemory = new WebAssembly.Memory({
-    initial: ${initialMemory},
-    maximum: ${maximumMemory},
-  })
+  // provided. It is resolved here in function scope (workerd bans global scope
+  // allocation) and is never shared (no threads, no SharedArrayBuffer).
+  // Resolve it before the emnapi context so a rejected option bag or a host
+  // memory-limit failure cannot leak a context that never reaches
+  // instantiation.
+  const __wasmMemory = __resolveInstanceMemory(__options)
   let __lifecycleState = 'pending'
   let __destroyEmnapiContext
   let __destroyOwnedContext
   let __destroyManagedOwnedContext
   let __napiInstance
+${instanceHostState}\
   let __wasmEnvCleanupRan = false
   let __wasmEnvCleanupPrepared = false
+  let __wasmEnvCleanupPreparing = false
   let __wasmEnvCleanupDrained = false
   let __wasmEnvCleanupDrainPromise
+  const __isPreparingEnvCleanup = () => __wasmEnvCleanupPreparing
   const __prepareEnvCleanup = () => {
-    if (__wasmEnvCleanupPrepared) {
+    if (__wasmEnvCleanupPrepared || __wasmEnvCleanupPreparing) {
       return
     }
     const __prepareWasmEnvCleanup =
       __napiInstance?.exports.napi_prepare_wasm_env_cleanup
     if (typeof __prepareWasmEnvCleanup === 'function') {
-      __prepareWasmEnvCleanup()
+      // The addon settles the promises it cancels synchronously, under a
+      // non-reentrant lifecycle mutex: anything a promise hook calls from in
+      // here must not reach this export again.
+      __wasmEnvCleanupPreparing = true
+      try {
+        __prepareWasmEnvCleanup()
+      } finally {
+        __wasmEnvCleanupPreparing = false
+      }
       __wasmEnvCleanupRan = true
     }
     __wasmEnvCleanupPrepared = true
@@ -1472,6 +1885,63 @@ async function __createInstance(
     __wasmEnvCleanupDrainPromise = __tracked
     return __tracked
   }
+  let __disposed = false
+  const __runInstanceDisposal = async () => {
+    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
+    }
+    const __result = await (__beforeExitDestroy
+      ? __destroyManagedOwnedContext()
+      : __destroyOwnedContext())
+    // Only a completed destroy retires the instance; a throw above leaves
+    // the counter untouched so a retried dispose() cannot double-decrement.
+    if (!__disposed) {
+      __disposed = true
+      __liveInstances -= 1
+    }
+    return __result
+  }
+  let __instanceDisposePromise
+  /**
+   * The disposal frame runs the barrier, and the barrier settles the promises it
+   * cancels synchronously — so a promise hook firing inside it can call this
+   * same instance's dispose() again while the first call is still in its drain.
+   * That nested call finds the barrier flagged in flight, prepares nothing,
+   * drains nothing, and falls straight through to the context destroyer, whose
+   * \`Context.destroy()\` hits the wrapper's in-flight no-op. It would record a
+   * destruction that never happened, and the outer frame would then skip the
+   * real one: both disposals resolve, no cleanup hook runs, the context stays
+   * retained.
+   *
+   * Memoize before any of that starts, exactly like the eager loaders'
+   * \`__disposeWasiBinding\`, so there is only ever one disposal frame per
+   * instance and a reentrant caller awaits it instead of racing it. Cleared on
+   * rejection: a drain that failed has to stay retryable.
+   */
+  const __disposeInstance = () => {
+    if (__instanceDisposePromise) {
+      return __instanceDisposePromise
+    }
+    let __resolveDispose
+    let __rejectDispose
+    const __disposePromise = new Promise((__resolve, __reject) => {
+      __resolveDispose = __resolve
+      __rejectDispose = __reject
+    })
+    __instanceDisposePromise = __disposePromise
+    __runInstanceDisposal().then(__resolveDispose, (__error) => {
+      __instanceDisposePromise = undefined
+      __rejectDispose(__error)
+    })
+    return __disposePromise
+  }
   const __destroyBeforeExit = __beforeExitDestroy
     ? async () => {
         if (__lifecycleState === 'failed') {
@@ -1497,7 +1967,10 @@ async function __createInstance(
     destroy,
     destroyForModuleLifecycle,
     registerCleanup: __registerCleanup,
-  } = await __createManagedEmnapiContext(__prepareEnvCleanup)
+  } = await __createManagedEmnapiContext(
+    __prepareEnvCleanup,
+    __isPreparingEnvCleanup,
+${managedHostDisposeArg}  )
   __destroyEmnapiContext = destroy
   __destroyOwnedContext = () => __destroyEmnapiContext()
   __destroyManagedOwnedContext = destroyForModuleLifecycle
@@ -1534,26 +2007,34 @@ ${emnapiInjectBuffer}\
         }
       },
     }))
+${installInstanceHosts}\
+    // \`instantiate()\` and \`createInstance().exports\` hand out this object; a
+    // named module export does not travel with it. After the instance host
+    // install, which hands the same object to addon-provided registration
+    // functions that may put anything on it, and inside this \`try\`, so a
+    // claimed name flips \`__lifecycleState\` to 'failed' and tears the instance
+    // down rather than escaping a half-built one.
+    ${NAPI_BINDING_TARGET_STAMP_FN}(__napiModule.exports, __napiBindingTarget)
     if (__lifecycleState === 'pending') {
       __lifecycleState = 'succeeded'
     }
+    __createdInstances += 1
+    __liveInstances += 1
     return {
       exports: __napiModule.exports,
-      async dispose() {
-        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()
+      get memory() {
+        return __wasmMemory
       },
+      get memoryBytes() {
+        // The Memory outlives the environment, so this stays readable after a
+        // FAILED dispose() (which leaves the instance undisposed and
+        // retryable). It reports 0 only once disposal has actually completed.
+        return __disposed ? 0 : __wasmMemory.buffer.byteLength
+      },
+      get disposed() {
+        return __disposed
+      },
+      dispose: __disposeInstance,
     }
   } catch (error) {
     __lifecycleState = 'failed'
@@ -1625,11 +2106,22 @@ ${emnapiInjectBuffer}\
 }
 
 /**
- * Create an independent instance. Call dispose() when the instance is no
- * longer needed so emnapi cleanup hooks run deterministically.
+ * Create an independent instance. Call and await dispose() when the instance
+ * is no longer needed so emnapi cleanup hooks run deterministically.
+ *
+ * The optional second argument selects this instance's linear memory: either
+ * \`memory\` (an unshared, single-use WebAssembly.Memory you allocated) or
+ * \`initialMemoryPages\` / \`maximumMemoryPages\`, never both. Omitted, the
+ * loader allocates WASM_MEMORY.initialPages..WASM_MEMORY.maximumPages.
+ *
+ * A provided Memory must come from this loader's own realm: the WASI and
+ * emnapi layers underneath identify one with a realm-local \`instanceof\`, so a
+ * Memory built in a \`node:vm\` context or another frame is rejected. Every
+ * Memory an instance runs on is single-use, the loader-allocated one included:
+ * \`instance.memory\` cannot be recycled into a second \`createInstance()\`.
  */
-export async function createInstance(__wasmInput) {
-  return __createInstance(__wasmInput)
+export async function createInstance(__wasmInput, __options) {
+  return __createInstance(__wasmInput, __options)
 }
 
 let __defaultModulePromise
@@ -1666,6 +2158,7 @@ export function instantiate(__wasmInput) {
     const __instancePromise = __modulePromise.then((__module) =>
       __createInstance(
         __module,
+        undefined,
         __disposeDefaultInstance,
         (__managedDestroyer) => {
           __defaultManagedDestroyers.set(
@@ -1814,21 +2307,90 @@ export function dispose() {
 
 export const createWasiDeferredBrowserBindingTypeDef = (
   packageName: string,
+  platformArchABI = 'wasm32-wasip1',
 ) => `export type WasiBinding = typeof import('${packageName}')
 
 export type WasiModuleInput =
   | WebAssembly.Module
   | PromiseLike<WebAssembly.Module>
 
+/** Run the instance on a linear memory the caller allocated. */
+export interface WasiCallerMemoryOptions {
+  /**
+   * A caller-allocated linear memory for this instance. It must be unshared
+   * and created in this loader's own realm — the WASI and emnapi layers
+   * underneath identify a Memory with a realm-local \`instanceof\`, so one from
+   * a \`node:vm\` context or another frame is rejected. It is single-use: once
+   * a validated initialization attempt has begun, the same Memory cannot be
+   * passed again — including after that attempt failed, and after the instance
+   * was disposed.
+   */
+  memory: WebAssembly.Memory
+  /** Not available beside \`memory\`: the loader allocates neither. */
+  initialMemoryPages?: never
+  /** Not available beside \`memory\`: the loader allocates neither. */
+  maximumMemoryPages?: never
+}
+
+/** Let the loader allocate the linear memory, optionally sized. */
+export interface WasiAllocatedMemoryOptions {
+  /** Not available beside the page counts: they size the loader's own Memory. */
+  memory?: never
+  /** @default WASM_MEMORY.initialPages */
+  initialMemoryPages?: number
+  /** @default WASM_MEMORY.maximumPages */
+  maximumMemoryPages?: number
+}
+
+/**
+ * Either memory form, never a mix of the two: the loader throws a TypeError
+ * on \`memory\` beside a page count. \`{}\` and an omitted argument select the
+ * loader defaults.
+ */
+export type WasiInstanceOptions =
+  | WasiCallerMemoryOptions
+  | WasiAllocatedMemoryOptions
+
+export interface WasiRuntimeStats {
+  /** Instances created by this evaluated loader module, not process-wide. */
+  createdInstances: number
+  /** Created instances whose dispose() has not completed. */
+  liveInstances: number
+  /** Declared initial address space, not committed memory. */
+  declaredInitialMemoryBytes: number
+}
+
 export interface WasiInstance {
   readonly exports: WasiBinding
+  /** This instance's linear memory. Claimed, so it cannot start another one. */
+  readonly memory: WebAssembly.Memory
+  /** Current linear-memory size; 0 once dispose() has completed. */
+  readonly memoryBytes: number
+  readonly disposed: boolean
   dispose(): Promise<void>
 }
 
+/** The memory descriptor compiled into this loader. */
+export const WASM_MEMORY: Readonly<{
+  initialPages: number
+  maximumPages: number
+  pageBytes: number
+  initialBytes: number
+  maximumBytes: number
+}>
+
+export function getDeferredRuntimeStats(): Readonly<WasiRuntimeStats>
+
 export function instantiate(wasmInput: WasiModuleInput): Promise<WasiBinding>
-export function createInstance(wasmInput: WasiModuleInput): Promise<WasiInstance>
+export function createInstance(
+  wasmInput: WasiModuleInput,
+  options?: WasiInstanceOptions,
+): Promise<WasiInstance>
 /** Dispose the singleton and retry retained failed-initialization cleanup. */
 export function dispose(): Promise<void>
+
+/** The WASI flavor this deferred loader instantiates. */
+export declare const __napiBindingTarget: '${platformArchABI}'
 `
 
 export const createWasiBinding = (
@@ -1842,7 +2404,20 @@ export const createWasiBinding = (
   // wasm artifact.
   platformArchABI = 'wasm32-wasi',
   packageWasmFileName = wasmFileName,
+  asyncRuntime = false,
 ) => {
+  const asyncRuntimeImport = asyncRuntime
+    ? `const {
+  installCurrentThreadHosts: __installCurrentThreadHosts,
+} = require('@napi-rs/async-runtime')
+`
+    : ''
+  const installAsyncRuntimeHosts = asyncRuntime
+    ? `  __currentThreadHostsDisposer = __installCurrentThreadHosts(
+    __napiModule.exports,
+  )
+`
+    : ''
   const workerImports = threads
     ? `const { Worker } = require('node:worker_threads')
 `
@@ -2005,6 +2580,9 @@ function __createWasiWorker(filename) {
   return `/* eslint-disable */
 /* auto-generated by NAPI-RS */
 
+const __napiBindingTarget = '${platformArchABI}'
+${BINDING_TARGET_STAMP_HELPER}
+
 const __nodeFs = require('node:fs')
 const __nodePath = require('node:path')
 const { WASI: __nodeWASI } = require('node:wasi')
@@ -2016,6 +2594,7 @@ ${workerRuntimeImport}\
   instantiateNapiModuleSync: __emnapiInstantiateNapiModuleSync,
 } = require('@napi-rs/wasm-runtime')
 const { createContext: __emnapiCreateContext } = require('@emnapi/runtime')
+${asyncRuntimeImport}\
 ${workerExecArgv}\
 
 const __cwd = process.cwd()
@@ -2059,7 +2638,7 @@ if (__nodeFs.existsSync(__wasmDebugFilePath)) {
 
 const __wasmFile = __nodeFs.readFileSync(__wasmFilePath)
 let __emnapiContext
-${emnapiContextLifecycle}
+${createEmnapiContextLifecycle(asyncRuntime)}
 const __wasiRollbackRegistrySymbol = Symbol.for('${WASI_ROLLBACK_REGISTRY_SYMBOL}')
 const __wasiRollbackRegistryKey =
   typeof __filename === 'string' ? __filename : __wasmFilePath
@@ -2233,7 +2812,11 @@ function __captureEmnapiAutoDestroyListener() {
 try {
   const __finishAutoDestroyCapture = __captureEmnapiAutoDestroyListener()
   try {
-    __emnapiContext = __emnapiCreateContext({ autoDestroy: false })
+    __emnapiContext = __wrapEmnapiContextDestroyForSettlement(
+      __emnapiCreateContext({ autoDestroy: false }),
+      __prepareWasmEnvCleanup,
+      __isPreparingWasmEnvCleanup,
+    )
     // emnapi 2.x still registers an unconditional once-listener for
     // beforeExit that auto-destroys the context, and suppressDestroy() only
     // neutralizes its callback without removing it. This loader owns cleanup
@@ -2273,6 +2856,23 @@ ${workerOption}\
     },
   }))
   __publishWasiDispose(__napiModule.exports)
+${installAsyncRuntimeHosts}\
+  // The CommonJS tail below aliases \`__napiModule.exports\`; a named module
+  // export does not travel with it, so carry the marker on the binding itself
+  // too. Three things pin the stamp to exactly this spot:
+  //   - inside this \`try\`, because the guard throws on a
+  //     \`#[napi(module_exports)]\` hook that claimed the name, and only the
+  //     catch below tears the environment — context, workers, exit listener —
+  //     back down;
+  //   - after the async runtime host install, which hands this same object to
+  //     addon-provided registration functions that may put anything on it;
+  //   - assigning onto the loader's own \`module.exports\`, which is still the
+  //     original object here, so an addon accessor with a refusing setter is
+  //     never written through. \`cjs-module-lexer\` — Node's CJS -> ESM named
+  //     export detection — reads the static \`module.exports.<name> =\` either
+  //     way, and the later \`module.exports = __napiModule.exports\` does not
+  //     undo that.
+  module.exports.${NAPI_BINDING_TARGET_EXPORT} = ${NAPI_BINDING_TARGET_STAMP_FN}(__napiModule.exports, __napiBindingTarget)
   __registerWasiExitListener()
 } catch (error) {
   const rollback = {