@napi-rs/cli 3.9.1 → 3.10.1

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

@@ -1,11 +1,16 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import ava, { type ExecutionContext } from 'ava'
 import { parseSync } from 'oxc-parser'
+import ts from 'typescript'
 
 import { createCjsBinding, createEsmBinding } from '../templates/js-binding.js'
 import {
   createWasiBinding,
   createWasiBrowserBinding,
   createWasiDeferredBrowserBinding,
+  createWasiDeferredBrowserBindingTypeDef,
 } from '../templates/load-wasi-template.js'
 import {
   createWasiBrowserWorkerBinding,
@@ -14,6 +19,8 @@ import {
 
 const test = ava
 
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
 // Snapshot tests for full template output
 
 test('createWasiBrowserBinding default', (t) => {
@@ -68,6 +75,63 @@ test('createWasiBrowserBinding threadless keeps sync init and no pool', (t) => {
   t.true(binding.includes('__emnapiInstantiateNapiModuleSync(__wasmFile'))
 })
 
+test('threadless loaders embed the initial memory they are given', (t) => {
+  const unshared = `new WebAssembly.Memory({
+  initial: 1027,
+  maximum: 65536,
+})`
+
+  const nodeLoader = createWasiBinding(
+    'test',
+    '@scope/test',
+    1027,
+    65536,
+    false,
+  )
+  t.true(nodeLoader.includes(`const __wasmMemory = ${unshared}`))
+  t.false(nodeLoader.includes('shared: true'))
+
+  const browserLoader = createWasiBrowserBinding(
+    'test-wasi',
+    1027,
+    65536,
+    false,
+    false,
+    false,
+    false,
+    false,
+  )
+  t.true(browserLoader.includes(`const __wasmMemory = ${unshared}`))
+  t.false(browserLoader.includes('shared: true'))
+
+  // The deferred loader publishes its descriptor instead of inlining it, and
+  // allocates from it in function scope (workerd bans global scope allocation).
+  const deferred = createWasiDeferredBrowserBinding('test', 1027, 65536)
+  t.true(
+    deferred.includes(`export const WASM_MEMORY = Object.freeze({
+  initialPages: 1027,
+  maximumPages: 65536,`),
+  )
+  t.true(
+    deferred.includes(`    const __allocated = new WebAssembly.Memory({
+      initial:
+        __options != null && __options.initialMemoryPages !== undefined
+          ? __options.initialMemoryPages
+          : WASM_MEMORY.initialPages,`),
+  )
+  t.false(deferred.includes('shared: true'))
+
+  // the threaded loader still gets its own, shared descriptor
+  const threaded = createWasiBinding('test', '@scope/test', 16384, 65536, true)
+  t.true(
+    threaded.includes(`const __sharedMemory = new WebAssembly.Memory({
+  initial: 16384,
+  maximum: 65536,
+  shared: true,
+})`),
+  )
+})
+
 test('createWasiBrowserBinding with errorEvent', (t) => {
   t.snapshot(
     createWasiBrowserBinding(
@@ -96,6 +160,47 @@ test('createWasiBrowserBinding with errorEvent and fs', (t) => {
   )
 })
 
+test('createWasiBrowserBinding with asyncRuntime hosts', (t) => {
+  t.snapshot(
+    createWasiBrowserBinding(
+      'test-wasi',
+      4000,
+      65536,
+      false,
+      false,
+      false,
+      false,
+      false,
+      'wasm32-wasip1',
+      true,
+    ),
+  )
+})
+
+// The deferred loader is the published `./workerd` entry and the only loader
+// whose module namespace is part of the package's public API, so its bytes get
+// the same snapshot treatment as the browser loaders'.
+test('createWasiDeferredBrowserBinding default', (t) => {
+  t.snapshot(createWasiDeferredBrowserBinding('test-wasi'))
+})
+
+test('createWasiDeferredBrowserBinding with async-runtime hosts and buffer', (t) => {
+  t.snapshot(
+    createWasiDeferredBrowserBinding(
+      'test-wasi',
+      1027,
+      65536,
+      true,
+      'wasm32-wasip1',
+      true,
+    ),
+  )
+})
+
+test('createWasiDeferredBrowserBindingTypeDef', (t) => {
+  t.snapshot(createWasiDeferredBrowserBindingTypeDef('./test-wasi.wasip1.cjs'))
+})
+
 test('createWasiBrowserWorkerBinding default', (t) => {
   t.snapshot(createWasiBrowserWorkerBinding(false, false))
 })
@@ -143,6 +248,36 @@ const browserBindingCases: Array<{
     args: ['test', 4000, 65536, false, true, false, true],
   },
   { name: 'all options', args: ['test', 4000, 65536, true, true, true, true] },
+  {
+    name: 'asyncRuntime',
+    args: [
+      'test',
+      4000,
+      65536,
+      false,
+      false,
+      false,
+      false,
+      true,
+      'wasm32-wasi',
+      true,
+    ],
+  },
+  {
+    name: 'all options + asyncRuntime',
+    args: [
+      'test',
+      4000,
+      65536,
+      true,
+      true,
+      true,
+      true,
+      true,
+      'wasm32-wasi',
+      true,
+    ],
+  },
 ]
 
 for (const { name, args } of browserBindingCases) {
@@ -221,6 +356,69 @@ for (const { name, code } of cjsBindingCases) {
 // emitted flavors it builds (node cjs threadless, deferred/workerd)
 // behaviorally; the other flavors are never instantiated by any test, so assert
 // the shape here as well.
+// `napi.wasm.asyncRuntime` output. The seven-export / contract-v4 / liveness /
+// rollback checks all live in `@napi-rs/async-runtime`; the loader only has to
+// call it at the right moment and tear it down at the right moment.
+const asyncRuntimeLoaderCases: Array<{
+  name: string
+  code: string
+  install: string
+}> = [
+  {
+    name: 'node cjs',
+    code: createWasiBinding(
+      'test',
+      '@scope/test',
+      4000,
+      65536,
+      true,
+      'wasm32-wasi',
+      'test',
+      true,
+    ),
+    install: "require('@napi-rs/async-runtime')",
+  },
+  {
+    name: 'node cjs threadless',
+    code: createWasiBinding(
+      'test',
+      '@scope/test',
+      4000,
+      65536,
+      false,
+      'wasm32-wasip1',
+      'test',
+      true,
+    ),
+    install: "require('@napi-rs/async-runtime')",
+  },
+  {
+    name: 'browser esm',
+    code: createWasiBrowserBinding(
+      'test',
+      4000,
+      65536,
+      false,
+      false,
+      false,
+      false,
+      true,
+      'wasm32-wasi',
+      true,
+    ),
+    install: "from '@napi-rs/async-runtime'",
+  },
+]
+
+const asyncRuntimeDeferredCode = createWasiDeferredBrowserBinding(
+  'test',
+  1024,
+  65536,
+  false,
+  'wasm32-wasip1',
+  true,
+)
+
 const wasiLoaderCases: Array<{ name: string; code: string }> = [
   { name: 'node cjs', code: createWasiBinding('test', '@scope/test') },
   {
@@ -229,8 +427,498 @@ const wasiLoaderCases: Array<{ name: string; code: string }> = [
   },
   { name: 'browser esm', code: createWasiBrowserBinding('test') },
   { name: 'deferred/workerd', code: createWasiDeferredBrowserBinding('test') },
+  ...asyncRuntimeLoaderCases.map(({ name, code }) => ({
+    name: `${name} + asyncRuntime`,
+    code,
+  })),
+  {
+    name: 'deferred/workerd + asyncRuntime',
+    code: asyncRuntimeDeferredCode,
+  },
 ]
 
+// The flag is off by default, so every existing generated loader keeps its
+// current bytes when a project bumps the CLI. The six template snapshots are
+// the byte-level proof; this is the cheap named regression net.
+for (const { name, code } of [
+  { name: 'node cjs', code: createWasiBinding('test', '@scope/test') },
+  { name: 'browser esm', code: createWasiBrowserBinding('test') },
+  { name: 'deferred/workerd', code: createWasiDeferredBrowserBinding('test') },
+]) {
+  test(`asyncRuntime is off by default: ${name}`, (t) => {
+    t.false(code.includes('@napi-rs/async-runtime'))
+    t.false(code.includes('__disposeCurrentThreadHosts'))
+    t.false(code.includes('installCurrentThreadHosts'))
+  })
+}
+
+for (const { name, code, install } of asyncRuntimeLoaderCases) {
+  test(`asyncRuntime loader installs and tears down the hosts: ${name}`, (t) => {
+    assertValidJS(t, code, name)
+    t.true(code.includes(install))
+    // The package owns the seven-export / contract-v4 / liveness / rollback
+    // checks; the loader must not re-implement any of them.
+    t.true(code.includes('__installCurrentThreadHosts('))
+    t.false(code.includes('reserveCurrentThreadHostRegistration'))
+    t.false(code.includes('getCurrentThreadTaskHostContractVersion'))
+
+    // Install runs after the dispose symbol is published and INSIDE the try,
+    // so a mismatch throw reaches the existing rollback.
+    const installIndex = code.indexOf(
+      '__currentThreadHostsDisposer = __installCurrentThreadHosts(',
+    )
+    t.true(
+      installIndex > code.indexOf('__publishWasiDispose(__napiModule.exports)'),
+    )
+    t.true(
+      installIndex < code.indexOf('\n} catch (error) {\n', installIndex - 1),
+    )
+
+    // Teardown runs before the context is destroyed, on every path, because
+    // __destroyEmnapiContext is the single funnel dispose()/rollback/'exit'
+    // all reach.
+    const destroyBody = code.slice(
+      code.indexOf('function __destroyEmnapiContext() {'),
+      code.indexOf('function __terminateWasiWorkers() {'),
+    )
+    t.true(destroyBody.includes('__disposeCurrentThreadHosts()'))
+    t.true(
+      destroyBody.indexOf('__disposeCurrentThreadHosts()') <
+        destroyBody.indexOf('__emnapiContext.destroy()'),
+    )
+    // …and after the drain: __startWasiDisposal prepares + drains before it
+    // ever calls __continueWasiDisposal -> __destroyEmnapiContext.
+    t.false(destroyBody.includes('__drainWasmEnvCleanup'))
+  })
+}
+
+// `@emnapi/wasi-threads` records a worker exit as expected only when ITS thread
+// manager performed the termination. A bare `worker.terminate()` reaches the
+// manager's own 'exit' listener, which reports the exit as a worker failure and
+// rethrows inside the emit — aborting the `once('exit')` that backs the
+// terminate promise, so `dispose()` never settles.
+for (const { name, code } of [
+  { name: 'node cjs', code: createWasiBinding('test', '@scope/test') },
+  { name: 'browser esm', code: createWasiBrowserBinding('test') },
+]) {
+  test(`pool workers are terminated through the thread manager: ${name}`, (t) => {
+    const start = code.indexOf('function __terminateWasiWorkers() {')
+    t.true(start > 0)
+    const body = code.slice(
+      start,
+      code.indexOf('function __finishWasiDisposal() {'),
+    )
+    const mark = body.indexOf('threadManager.terminateWorker(worker)')
+    const terminate = body.indexOf('result = worker.terminate()')
+    t.true(terminate > 0)
+    t.true(mark > 0, 'the termination has to be marked on the thread manager')
+    t.true(mark < terminate, 'and marked before the worker is terminated')
+    // Not `terminateAllThreads()`: it recreates the pool it just shut down.
+    t.false(body.includes('terminateAllThreads'))
+    // `terminateWorker` leaves a reporter behind that logs every message still
+    // queued on the port, which Node flushes on exit.
+    t.true(body.includes('worker.onmessage = undefined'))
+    // The manager is resolved through the helper, not read off `__napiModule`:
+    // the rollback runs on the one path where that binding was never assigned.
+    t.true(body.includes('const threadManager = __getWasiThreadManager()'))
+    t.false(body.includes('__napiModule.PThread'))
+  })
+}
+
+// The pool workers are unreferenced on purpose, and emnapi unreferences them
+// again when one reports `async-thread-ready`, so a pending termination has no
+// handle of its own to hold the loop open with.
+for (const { name, code } of [
+  { name: 'node cjs', code: createWasiBinding('test', '@scope/test') },
+  { name: 'browser esm', code: createWasiBrowserBinding('test') },
+]) {
+  test(`a pending termination holds the event loop open: ${name}`, (t) => {
+    const body = code.slice(
+      code.indexOf('function __terminateWasiWorkers() {'),
+      code.indexOf('function __finishWasiDisposal() {'),
+    )
+    t.true(
+      body.includes(
+        '__keepEventLoopAliveUntil(Promise.all(pending)).then(finish)',
+      ),
+      'the terminate promises have to be awaited under a keep-alive',
+    )
+    // …and the keep-alive is released the moment the work settles, so it can
+    // never outlive the disposal that asked for it.
+    const keepAlive = code.slice(
+      code.indexOf('function __keepEventLoopAliveUntil(work) {'),
+    )
+    t.true(keepAlive.indexOf('clearTimer(timer)') > 0)
+    t.true(keepAlive.indexOf('release()') < keepAlive.indexOf('return value'))
+    // Nothing puts the stubbed `ref` functions back: doing so is what raced
+    // emnapi's own unreference.
+    t.false(code.includes('__wasiWorkerRefRestorers'))
+    t.false(code.includes('__restoreWasiWorkerRef'))
+  })
+}
+
+test('the node loader keeps its pool workers unreferenced for life', (t) => {
+  const code = createWasiBinding('test', '@scope/test')
+  t.true(code.includes('worker[kPublicPort].ref = () => {}'))
+  t.true(code.includes('worker[kHandle].ref = () => {}'))
+  t.true(code.includes('worker.unref()'))
+  // An idle binding must not hold the process open, and disposal does not
+  // reverse that — `__keepEventLoopAliveUntil` covers the termination instead.
+  t.false(code.includes('.ref = publicPortRef'))
+  t.false(code.includes('.ref = handleRef'))
+})
+
+// `examples/custom-async-runtime` asserts a threadless loader never mentions
+// `Worker`, so nothing in the *shared* prelude may name the class — comments
+// included. That lane needs a wasm build to fail; this does not.
+for (const { name, code } of [
+  {
+    name: 'node cjs threadless',
+    code: createWasiBinding('test', '@scope/test', 4000, 65536, false),
+  },
+  {
+    name: 'browser esm threadless',
+    code: createWasiBrowserBinding(
+      'test',
+      4000,
+      65536,
+      false,
+      false,
+      false,
+      false,
+      false,
+    ),
+  },
+  { name: 'deferred/workerd', code: createWasiDeferredBrowserBinding('test') },
+]) {
+  test(`threadless loaders never name Worker: ${name}`, (t) => {
+    t.notRegex(code, /\bWorker\b/)
+    t.notRegex(code, /node:worker_threads/)
+  })
+}
+
+test('asyncRuntime deferred loader registers per instance', (t) => {
+  const code = asyncRuntimeDeferredCode
+  assertValidJS(t, code, 'deferred asyncRuntime')
+  // Per-instance helpers, NOT installCurrentThreadHosts: each instance owns
+  // its own env and needs an exact disposer, not a realm-global dedup.
+  t.true(code.includes('__registerWorkerdCurrentThreadTaskHost('))
+  t.true(code.includes('__registerWorkerdTimerHost('))
+  t.false(code.includes('installCurrentThreadHosts'))
+  // Task host first, timer host second; disposal is the reverse.
+  t.true(
+    code.indexOf('const __disposeTaskHost =') <
+      code.indexOf('const __disposeTimerHost ='),
+  )
+  const disposer = code.slice(code.indexOf('__disposeInstanceHosts = () => {'))
+  t.true(
+    disposer.indexOf('__disposeTimerHost()') <
+      disposer.indexOf('__disposeTaskHost()'),
+  )
+  // Hooked next to __prepareEnvCleanup, which every destroy path calls.
+  const managedDestroy = code.slice(
+    code.indexOf('      __prepareEnvCleanup?.()'),
+  )
+  t.true(
+    managedDestroy.indexOf('__disposeHosts?.()') <
+      managedDestroy.indexOf('__result = __emnapiContext.destroy()'),
+  )
+})
+
+// The deferred loader's module namespace is the published `./workerd` entry's
+// public API. `WASM_MEMORY` and `getDeferredRuntimeStats` are new names in it,
+// and `createInstance`'s option bag is the only way a host sizes an instance
+// under a hard isolate cap.
+test('deferred loader is syntactically valid in both host modes', (t) => {
+  assertValidJS(t, createWasiDeferredBrowserBinding('test'), 'deferred')
+  assertValidJS(
+    t,
+    createWasiDeferredBrowserBinding(
+      'test',
+      1027,
+      65536,
+      true,
+      'wasm32-wasip1',
+      true,
+    ),
+    'deferred + hosts',
+  )
+})
+
+test('deferred loader publishes the memory floor it was configured with', (t) => {
+  const code = createWasiDeferredBrowserBinding('test', 1027, 40000)
+  t.true(code.includes('export const WASM_MEMORY = Object.freeze({'))
+  t.true(code.includes('initialPages: 1027'))
+  t.true(code.includes('maximumPages: 40000'))
+  t.true(code.includes('initialBytes: 1027 * 65536'))
+  t.true(code.includes('maximumBytes: 40000 * 65536'))
+  t.true(code.includes('export function getDeferredRuntimeStats()'))
+  // workerd bans allocation in global scope, so the single `new
+  // WebAssembly.Memory` stays inside the per-instance resolver.
+  t.is(code.split('new WebAssembly.Memory(').length - 1, 1)
+  t.true(
+    code.indexOf('function __resolveInstanceMemory(') <
+      code.indexOf('new WebAssembly.Memory('),
+  )
+})
+
+test('deferred loader claims caller memory exactly once and rejects shared memory', (t) => {
+  const code = createWasiDeferredBrowserBinding('test')
+  t.true(code.includes('const __claimedMemories = new WeakSet()'))
+  t.true(code.includes('__claimedMemories.add(__provided)'))
+  t.true(
+    code.includes('requires an unshared WebAssembly.Memory'),
+    'a SharedArrayBuffer-backed memory must be rejected, not silently accepted',
+  )
+  t.true(
+    code.includes(
+      'Pass either memory or initialMemoryPages/maximumMemoryPages, not both',
+    ),
+  )
+  // The claim is taken before instantiation can fail, so a failed attempt
+  // cannot hand the same half-written bytes to a second instance.
+  const resolver = code.slice(
+    code.indexOf('function __resolveInstanceMemory('),
+    code.indexOf('\n}\n', code.indexOf('function __resolveInstanceMemory(')),
+  )
+  t.true(resolver.includes('__claimedMemories.add(__provided)'))
+  // The loader-allocated Memory is claimed too: the handle publishes it as
+  // `instance.memory`, and two live instances on one linear memory each
+  // reinitialize the state the other is running on.
+  t.true(resolver.includes('__claimedMemories.add(__allocated)'))
+})
+
+test('deferred loader rejects a cross-realm memory before claiming it', (t) => {
+  const code = createWasiDeferredBrowserBinding('test')
+  const resolver = code.slice(
+    code.indexOf('function __resolveInstanceMemory('),
+    code.indexOf('\n}\n', code.indexOf('function __resolveInstanceMemory(')),
+  )
+  // The intrinsic getters accept a genuine Memory from any realm, but
+  // `WASI.setMemory` and emnapi identify one with a realm-local `instanceof`.
+  t.true(resolver.includes('if (!(__provided instanceof WebAssembly.Memory))'))
+  t.true(
+    resolver.includes(
+      'memory must be a WebAssembly.Memory created in the same realm as this loader',
+    ),
+  )
+  // Every rejection must precede the claim, or a corrected retry would be
+  // refused as a reuse of a Memory that never ran anything.
+  t.true(
+    resolver.indexOf('__provided instanceof WebAssembly.Memory') <
+      resolver.indexOf('__claimedMemories.add(__provided)'),
+  )
+  t.true(
+    resolver.indexOf(
+      'Pass either memory or initialMemoryPages/maximumMemoryPages, not both',
+    ) < resolver.indexOf('__claimedMemories.add(__provided)'),
+  )
+})
+
+test('deferred instance handle reports its memory and retires exactly once', (t) => {
+  const code = createWasiDeferredBrowserBinding('test')
+  const handleStart = code.indexOf(
+    '    return {\n      exports: __napiModule.exports,',
+  )
+  t.true(
+    handleStart !== -1,
+    'the instance handle must be returned as a literal',
+  )
+  const handle = code.slice(
+    handleStart,
+    code.indexOf('  } catch (error) {', handleStart),
+  )
+  t.true(handle.includes('get memory() {'))
+  t.true(handle.includes('get memoryBytes() {'))
+  t.true(handle.includes('get disposed() {'))
+  // The handle delegates to the coalescing wrapper, so the retirement
+  // bookkeeping lives in the one disposal body that wrapper runs.
+  t.true(handle.includes('dispose: __disposeInstance,'))
+  const disposalStart = code.indexOf(
+    '  const __runInstanceDisposal = async () => {',
+  )
+  t.true(disposalStart !== -1, 'the disposal body must be a named arrow')
+  const disposal = code.slice(
+    disposalStart,
+    code.indexOf('\n  }\n', disposalStart),
+  )
+  // The counter moves only after the destroy resolves, so a dispose() that
+  // throws stays retryable without double-decrementing.
+  t.true(
+    disposal.indexOf('await (__beforeExitDestroy') <
+      disposal.indexOf('__liveInstances -= 1'),
+  )
+  t.true(disposal.includes('if (!__disposed) {'))
+})
+
+test('deferred loader keeps the singleton on the loader-owned memory', (t) => {
+  const code = createWasiDeferredBrowserBinding('test')
+  // `instantiate()` takes no option bag, so it must pass the options slot
+  // explicitly rather than shifting `__disposeDefaultInstance` into it.
+  t.true(
+    code.includes(`__createInstance(
+        __module,
+        undefined,
+        __disposeDefaultInstance,`),
+  )
+  t.true(code.includes('return __createInstance(__wasmInput, __options)'))
+})
+
+test('deferred loader pulls its hosts from the isolate-safe subpath', (t) => {
+  const code = createWasiDeferredBrowserBinding(
+    'test',
+    1024,
+    65536,
+    false,
+    'wasm32-wasip1',
+    true,
+  )
+  // The barrel (`index.cjs`) also requires `current-thread-hosts.cjs`, the
+  // Node-lane relay a worker bundle never runs and CJS cannot tree-shake.
+  t.true(code.includes("} from '@napi-rs/async-runtime/workerd'"))
+  t.false(code.includes("from '@napi-rs/async-runtime'\n"))
+})
+
+test('deferred loader type definition covers the new surface', (t) => {
+  const typeDef = createWasiDeferredBrowserBindingTypeDef('./test.wasip1.cjs')
+  // The two memory forms are separate interfaces, each declaring the other
+  // form's properties as `never`, so the combination `__resolveInstanceMemory`
+  // always throws on cannot be spelled by a typed caller.
+  t.true(typeDef.includes('export interface WasiCallerMemoryOptions {'))
+  t.true(typeDef.includes('  memory: WebAssembly.Memory'))
+  t.true(typeDef.includes('  initialMemoryPages?: never'))
+  t.true(typeDef.includes('  maximumMemoryPages?: never'))
+  t.true(typeDef.includes('export interface WasiAllocatedMemoryOptions {'))
+  t.true(typeDef.includes('  memory?: never'))
+  t.true(typeDef.includes('  initialMemoryPages?: number'))
+  t.true(typeDef.includes('  maximumMemoryPages?: number'))
+  t.true(
+    typeDef.includes(`export type WasiInstanceOptions =
+  | WasiCallerMemoryOptions
+  | WasiAllocatedMemoryOptions`),
+  )
+  t.false(typeDef.includes('export interface WasiInstanceOptions {'))
+  t.true(typeDef.includes('readonly memoryBytes: number'))
+  t.true(typeDef.includes('readonly disposed: boolean'))
+  t.true(typeDef.includes('export const WASM_MEMORY: Readonly<{'))
+  t.true(
+    typeDef.includes(
+      'export function getDeferredRuntimeStats(): Readonly<WasiRuntimeStats>',
+    ),
+  )
+  t.true(
+    typeDef.includes(`export function createInstance(
+  wasmInput: WasiModuleInput,
+  options?: WasiInstanceOptions,
+): Promise<WasiInstance>`),
+  )
+  // `createWasiDeferredBindingTypeDef` rewrites this exact string when the
+  // project builds without type definitions.
+  t.true(typeDef.includes("typeof import('./test.wasip1.cjs')"))
+})
+
+const DEFERRED_TYPE_CHECK_OPTIONS: ts.CompilerOptions = {
+  strict: true,
+  noEmit: true,
+  // The generated `.d.ts` is the file under test, so it must not be skipped.
+  // Only the default lib is.
+  skipLibCheck: false,
+  skipDefaultLibCheck: true,
+  target: ts.ScriptTarget.ESNext,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+}
+
+/**
+ * A consumer module for the generated deferred `.d.ts`, wrapping the given
+ * `createInstance()` calls in the declarations they need.
+ */
+const deferredConsumerSource = (calls: string) =>
+  `import { createInstance } from './loader.js'
+
+declare const wasmModule: WebAssembly.Module
+declare const memory: WebAssembly.Memory
+
+${calls}
+`
+
+/**
+ * TypeScript's verdict on such a consumer, as a list of diagnostic codes. The
+ * default lib still comes off disk through the real host; the generated
+ * typedef, the binding it imports, and the consumer are served from memory, so
+ * the check needs no temporary directory. Mirrors the semantic-check host in
+ * `build.spec.ts`.
+ */
+const deferredConsumerDiagnostics = (calls: string) => {
+  const root = `${__dirname.replaceAll('\\', '/')}/__deferred_typecheck__`
+  const files = new Map([
+    [
+      `${root}/loader.d.ts`,
+      createWasiDeferredBrowserBindingTypeDef('./test.wasip1.cjs'),
+    ],
+    [`${root}/test.wasip1.d.cts`, 'export declare const binding: number\n'],
+    [`${root}/consumer.ts`, deferredConsumerSource(calls)],
+  ])
+  const host = ts.createCompilerHost(DEFERRED_TYPE_CHECK_OPTIONS, true)
+  const readRealSourceFile = host.getSourceFile.bind(host)
+  const realFileExists = host.fileExists.bind(host)
+  const realReadFile = host.readFile.bind(host)
+  const realDirectoryExists = host.directoryExists?.bind(host)
+  host.getSourceFile = (fileName, languageVersion, ...rest) => {
+    const virtual = files.get(fileName)
+    return virtual === undefined
+      ? readRealSourceFile(fileName, languageVersion, ...rest)
+      : ts.createSourceFile(fileName, virtual, languageVersion, true)
+  }
+  host.fileExists = (fileName) =>
+    files.has(fileName) || realFileExists(fileName)
+  host.readFile = (fileName) => files.get(fileName) ?? realReadFile(fileName)
+  if (realDirectoryExists) {
+    host.directoryExists = (directoryName) =>
+      directoryName === root || realDirectoryExists(directoryName)
+  }
+  const program = ts.createProgram({
+    rootNames: [`${root}/consumer.ts`],
+    options: DEFERRED_TYPE_CHECK_OPTIONS,
+    host,
+  })
+  return ts.getPreEmitDiagnostics(program).map((d) => `TS${d.code}`)
+}
+
+test('deferred createInstance() options type-check per memory form', (t) => {
+  // Every form the loader accepts at runtime. `{}` and an omitted argument
+  // must stay legal: the allocated form is all-optional.
+  t.deepEqual(
+    deferredConsumerDiagnostics(`void createInstance(wasmModule)
+void createInstance(wasmModule, undefined)
+void createInstance(wasmModule, {})
+void createInstance(wasmModule, { memory })
+void createInstance(wasmModule, { initialMemoryPages: 1 })
+void createInstance(wasmModule, { initialMemoryPages: 1, maximumMemoryPages: 2 })`),
+    [],
+  )
+})
+
+test('deferred createInstance() rejects memory beside a page count', (t) => {
+  // `__resolveInstanceMemory` throws a TypeError on either mix, so neither
+  // may type-check. `memory` selects the caller form, whose page properties
+  // are `?: never` — i.e. `undefined` — so the checker rejects the offending
+  // property in place rather than the whole call: TS2322, "Type 'number' is not
+  // assignable to type 'undefined'".
+  t.deepEqual(
+    deferredConsumerDiagnostics(
+      'void createInstance(wasmModule, { memory, initialMemoryPages: 1024 })',
+    ),
+    ['TS2322'],
+  )
+  t.deepEqual(
+    deferredConsumerDiagnostics(
+      'void createInstance(wasmModule, { memory, maximumMemoryPages: 2048 })',
+    ),
+    ['TS2322'],
+  )
+})
+
 test('Node WASI loader uses an accessible host root on Android', (t) => {
   const code = createWasiBinding('test', '@scope/test')
   assertValidJS(t, code, 'Node WASI loader')
@@ -317,6 +1005,264 @@ function initializationRollbackBody(code: string): string {
   return code.slice(deferredStart, code.indexOf('throw error', deferredStart))
 }
 
+// The loaders order their own teardown barrier-then-destroy, but the emnapi
+// context is a live object: an embedder or test harness holding it, or emnapi's
+// own `beforeExit` auto-destroy on a host where `suppressDestroy()` is absent,
+// can call `Context.destroy()` directly. `destroy()` disables JavaScript calls
+// before it runs cleanup hooks, so a raw call discards the very settlements the
+// barrier exists to cancel and deliver. Own the ordering on the object: every
+// flavor shadows `destroy` once, at creation, before anything can reach it.
+const CONTEXT_DESTROY_WRAP_SIGNATURE =
+  'function __wrapEmnapiContextDestroyForSettlement('
+
+// The shared barrier's own in-flight flag, and the probe the wrapper reads it
+// through. It cannot live in the wrapper: `dispose()` runs the barrier itself
+// and only then calls `destroy()`, so a wrapper-local flag would still be clear
+// while the barrier is running and would let a reentrant destroy through.
+const preparingBarrierGuards = {
+  shared: {
+    probe: '__isPreparingWasmEnvCleanup',
+    snippets: [
+      'let __emnapiWasmEnvCleanupPreparing = false',
+      `function __isPreparingWasmEnvCleanup() {
+  return __emnapiWasmEnvCleanupPreparing
+}`,
+      `  if (__emnapiWasmEnvCleanupPrepared || __emnapiWasmEnvCleanupPreparing) {
+    return
+  }`,
+      `    __emnapiWasmEnvCleanupPreparing = true
+    try {
+      prepare()
+    } finally {
+      __emnapiWasmEnvCleanupPreparing = false
+    }`,
+    ],
+  },
+  deferred: {
+    probe: '__isPreparingEnvCleanup',
+    snippets: [
+      'let __wasmEnvCleanupPreparing = false',
+      'const __isPreparingEnvCleanup = () => __wasmEnvCleanupPreparing',
+      `    if (__wasmEnvCleanupPrepared || __wasmEnvCleanupPreparing) {
+      return
+    }`,
+      `      __wasmEnvCleanupPreparing = true
+      try {
+        __prepareWasmEnvCleanup()
+      } finally {
+        __wasmEnvCleanupPreparing = false
+      }`,
+    ],
+  },
+} as const
+
+// A nested `destroy()` must answer `undefined` without touching the real one:
+// no fallthrough, no deferral. `Context.destroy()` is typed `void`, so nothing
+// observable is lost, and the frame that started the barrier destroys the
+// moment it returns.
+const NESTED_DESTROY_NO_OP = `        if (isPreparingEnvCleanup?.()) {
+          return
+        }
+        prepareEnvCleanup?.()`
+
+const wrappedContextCreationCases: Array<{
+  name: string
+  code: string
+  prepare: string
+  guard: (typeof preparingBarrierGuards)[keyof typeof preparingBarrierGuards]
+}> = [
+  {
+    name: 'node cjs',
+    code: createWasiBinding('test', '@scope/test'),
+    prepare: '__prepareWasmEnvCleanup',
+    guard: preparingBarrierGuards.shared,
+  },
+  {
+    name: 'node cjs threadless',
+    code: createWasiBinding('test', '@scope/test', 4000, 65536, false),
+    prepare: '__prepareWasmEnvCleanup',
+    guard: preparingBarrierGuards.shared,
+  },
+  {
+    name: 'browser esm',
+    code: createWasiBrowserBinding('test'),
+    prepare: '__prepareWasmEnvCleanup',
+    guard: preparingBarrierGuards.shared,
+  },
+  {
+    name: 'deferred/workerd',
+    code: createWasiDeferredBrowserBinding('test'),
+    prepare: '__prepareEnvCleanup',
+    guard: preparingBarrierGuards.deferred,
+  },
+]
+
+for (const { name, code, prepare, guard } of wrappedContextCreationCases) {
+  test(`WASI loader runs the barrier on a raw context.destroy(): ${name}`, (t) => {
+    assertValidJS(t, code, name)
+    t.is(
+      code.split(CONTEXT_DESTROY_WRAP_SIGNATURE).length - 1,
+      1,
+      'loader must define the destroy wrapper exactly once',
+    )
+    // No unwrapped context may escape: there is exactly one createContext call
+    // and it is the wrapper's argument.
+    t.is(
+      code.split('__emnapiCreateContext({ autoDestroy: false })').length - 1,
+      1,
+      'loader must create exactly one emnapi context',
+    )
+    t.true(
+      code
+        .replace(/\s+/g, ' ')
+        .includes(
+          '__emnapiContext = __wrapEmnapiContextDestroyForSettlement( ' +
+            `__emnapiCreateContext({ autoDestroy: false }), ${prepare}, ${guard.probe}, )`,
+        ),
+      'the createContext result must be wrapped before anything can reach it',
+    )
+    // Ordering is the whole point: barrier first, real destroy second.
+    const wrapperStart = code.indexOf(CONTEXT_DESTROY_WRAP_SIGNATURE)
+    const wrapper = code.slice(
+      wrapperStart,
+      code.indexOf('\n}\n', wrapperStart),
+    )
+    t.true(
+      wrapper.indexOf('prepareEnvCleanup?.()') <
+        wrapper.indexOf('Reflect.apply(destroy, this, arguments)'),
+      'the barrier must run before the real destroy, while the env can still call into JavaScript',
+    )
+  })
+
+  // The barrier settles the promises it cancels *synchronously*, under a
+  // lifecycle mutex the addon cannot acquire twice. A `promiseHooks.onSettled`
+  // handler — or the `async_hooks` hook `AsyncLocalStorage` installs — that
+  // calls `destroy()` therefore re-enters the wrapper from inside the barrier,
+  // and a second trip into the export aborts the wasm instance outright. The
+  // flag lives in the barrier, not in the wrapper, so the same guard covers the
+  // `dispose()` path, where the barrier runs before `destroy()` is ever called.
+  test(`WASI loader makes a destroy reentered from the barrier a no-op: ${name}`, (t) => {
+    for (const snippet of guard.snippets) {
+      t.is(
+        code.split(snippet).length - 1,
+        1,
+        `barrier must carry its in-flight guard exactly once: ${snippet}`,
+      )
+    }
+    t.is(
+      code.split(NESTED_DESTROY_NO_OP).length - 1,
+      1,
+      'a destroy reentered while the barrier is in flight must return without running the barrier or the real destroy',
+    )
+    const wrapperStart = code.indexOf(CONTEXT_DESTROY_WRAP_SIGNATURE)
+    const wrapper = code.slice(
+      wrapperStart,
+      code.indexOf('\n}\n', wrapperStart),
+    )
+    t.true(
+      wrapper.indexOf('isPreparingEnvCleanup?.()') <
+        wrapper.indexOf('Reflect.apply(destroy, this, arguments)'),
+      'the reentry check must come before the real destroy',
+    )
+  })
+}
+
+// The nested-destroy no-op above is only safe because the frame that started
+// the barrier destroys as soon as the barrier returns. The deferred loader's
+// instance `dispose()` is the one frame that does not: it runs the barrier and
+// then yields for the settlement drain. So a promise hook firing inside that
+// barrier can call the same instance's `dispose()` again, reach the context
+// destroyer while the outer frame is still parked in its drain, and have the
+// wrapper's no-op recorded as a completed destroy — after which the outer frame
+// skips the real one and the context is retained with its cleanup hooks unrun.
+// dispose() has to coalesce, the way the eager loaders' `__disposeWasiBinding`
+// does, and the memo has to be in place *before* the barrier runs.
+test('deferred WASI loader coalesces a reentrant instance dispose()', (t) => {
+  const code = createWasiDeferredBrowserBinding('test')
+  assertValidJS(t, code, 'deferred/workerd')
+  t.is(
+    code.split('let __instanceDisposePromise').length - 1,
+    1,
+    'the instance must carry exactly one disposal memo',
+  )
+  const disposeStart = code.indexOf('const __disposeInstance = () => {')
+  t.true(disposeStart > 0, 'dispose() must go through a coalescing wrapper')
+  const disposeWrapper = code.slice(
+    disposeStart,
+    code.indexOf('\n  }\n', disposeStart),
+  )
+  t.true(
+    disposeWrapper.includes(`    if (__instanceDisposePromise) {
+      return __instanceDisposePromise
+    }`),
+    'a reentrant dispose() must join the disposal already running',
+  )
+  // The memo has to be published before the disposal body — and therefore
+  // before the barrier — runs, or a hook that fires inside the barrier still
+  // finds it unset and starts a second frame.
+  t.true(
+    disposeWrapper.indexOf('__instanceDisposePromise = __disposePromise') <
+      disposeWrapper.indexOf('__runInstanceDisposal()'),
+    'the memo must be published before the disposal body runs',
+  )
+  // Still retryable: the drain can reject on its own (a host `setImmediate`
+  // that throws), and dispose() has to be callable again after that.
+  t.true(
+    disposeWrapper.includes(`      __instanceDisposePromise = undefined
+      __rejectDispose(__error)`),
+    'a failed disposal must clear the memo so dispose() stays retryable',
+  )
+  // No second entry point into the disposal body: the instance exposes the
+  // coalescing wrapper itself, not an inline method that re-runs it.
+  t.true(
+    code.includes('      dispose: __disposeInstance,'),
+    'the instance must expose the coalescing wrapper as its dispose()',
+  )
+  t.false(
+    code.includes('      async dispose() {'),
+    'the instance must not carry a second inline dispose() method',
+  )
+  t.is(
+    code.split('__prepareForDisposal()').length - 1,
+    2,
+    'only the disposal body and the initialization rollback may prepare for disposal',
+  )
+})
+
+// Belt and braces for any caller that still reaches the managed destroyer from
+// inside the barrier: a `Context.destroy()` the wrapper skipped must never be
+// recorded as a completed destroy, or every later destroy — the outer disposal
+// frame's and managed beforeExit cleanup's alike — is skipped with it.
+test('deferred WASI loader never records a skipped destroy as completed', (t) => {
+  const code = createWasiDeferredBrowserBinding('test')
+  const destroyStart = code.indexOf('const __destroy = (')
+  t.true(destroyStart > 0, 'deferred loader must define a managed destroyer')
+  const destroyer = code.slice(
+    destroyStart,
+    code.indexOf('\n  const __destroyForModuleLifecycle', destroyStart),
+  )
+  t.true(
+    destroyer.includes(`      if (__isPreparingEnvCleanup?.()) {`),
+    'the managed destroyer must detect that the barrier is in flight',
+  )
+  const guardIndex = destroyer.indexOf('if (__isPreparingEnvCleanup?.()) {')
+  const destroyIndex = destroyer.indexOf('__result = __emnapiContext.destroy()')
+  t.true(
+    guardIndex < destroyIndex,
+    'the in-flight check must come before the destroy it would skip',
+  )
+  t.true(
+    destroyer
+      .slice(guardIndex, destroyIndex)
+      .includes(`throw __createLifecycleReentryError('dispose')`),
+    'a destroy the wrapper would skip must fail loudly instead of flagging the context disposed',
+  )
+  t.true(
+    destroyIndex < destroyer.indexOf('__disposed = true'),
+    'nothing may be flagged disposed before the real destroy is attempted',
+  )
+})
+
 test('createCjsBinding uses one statement dialect', (t) => {
   const code = createCjsBinding('test', '@scope/test', ['sum'], '1.0.0', [
     'wasm32-wasi',
@@ -338,6 +1284,412 @@ test('createCjsBinding uses one statement dialect', (t) => {
   )
 })
 
+test('the root CommonJS loader stamps before it aliases the addon', (t) => {
+  // The guard is safe against an addon accessor — `hasOwnProperty` and a read —
+  // but an assignment is not: a `#[napi(module_exports)]` hook can expose a
+  // getter reporting the value about to be stamped and a setter that throws.
+  // So the lexer-visible assignment has to land on the loader's own
+  // `module.exports`, while it is still the original object.
+  const cjs = createCjsBinding('test', '@scope/test', ['sum'], '1.0.0')
+  assertValidJS(t, cjs, 'root cjs stamp before alias')
+  const stamp = cjs.indexOf(ROOT_CJS_STAMP_CALL)
+  t.true(stamp > -1, 'the root loader must stamp through the guard')
+  t.true(
+    stamp < cjs.indexOf('\nmodule.exports = nativeBinding'),
+    'the stamp must precede the alias, or it assigns onto the addon',
+  )
+  // the guard still stamps the object the loader hands out
+  t.false(cjs.includes('__napiStampBindingTarget(module.exports,'))
+})
+
+test('native loaders export the artifact that actually loaded', (t) => {
+  const flavors = ['wasm32-wasi', 'wasm32-wasip1']
+  const cjs = createCjsBinding('test', '@scope/test', ['sum'], '1.0.0', flavors)
+  assertValidJS(t, cjs, 'cjs binding target')
+  t.true(cjs.includes("let __napiLoadedBindingTarget = 'native'"))
+  t.true(cjs.includes(ROOT_CJS_STAMP_CALL))
+  // one assignment per candidate: 2 flavors x (local loader + flavor package)
+  for (const flavor of flavors) {
+    t.is(
+      cjs.split(`__napiLoadedBindingTarget = '${flavor}'`).length - 1,
+      2,
+      `${flavor} must be recorded on both its local and package candidates`,
+    )
+  }
+  // the target is never read back off the WASI module
+  t.false(cjs.includes('wasiBinding.__napiBindingTarget'))
+
+  const esm = createEsmBinding('test', '@scope/test', ['sum'], '1.0.0', flavors)
+  assertValidJS(t, esm, 'esm binding target')
+  t.true(
+    esm.includes(
+      'export const __napiBindingTarget = __napiLoadedBindingTarget',
+    ),
+  )
+  // zero-ident packages take the `export default` branch and must keep it
+  const esmNoIdents = createEsmBinding(
+    'test',
+    '@scope/test',
+    [],
+    '1.0.0',
+    flavors,
+  )
+  assertValidJS(t, esmNoIdents, 'esm binding target without idents')
+  t.true(
+    esmNoIdents.includes(
+      'export const __napiBindingTarget = __napiLoadedBindingTarget',
+    ),
+  )
+})
+
+test('a napi export may not shadow __napiBindingTarget', (t) => {
+  t.throws(
+    () => createEsmBinding('test', '@scope/test', ['__napiBindingTarget']),
+    {
+      message: /reserved by the generated binding loader/,
+    },
+  )
+  t.throws(
+    () => createCjsBinding('test', '@scope/test', ['__napiBindingTarget']),
+    {
+      message: /reserved by the generated binding loader/,
+    },
+  )
+})
+
+test('WASI loaders self-identify their flavor', (t) => {
+  t.true(
+    createWasiBinding('test', '@scope/test').includes(
+      "const __napiBindingTarget = 'wasm32-wasi'",
+    ),
+  )
+  t.true(
+    createWasiBinding(
+      'test',
+      '@scope/test',
+      4000,
+      65536,
+      false,
+      'wasm32-wasip1',
+    ).includes("const __napiBindingTarget = 'wasm32-wasip1'"),
+  )
+  t.true(
+    createWasiBrowserBinding('test').includes(
+      "export const __napiBindingTarget = 'wasm32-wasi'",
+    ),
+  )
+  t.true(
+    createWasiBrowserBinding(
+      'test',
+      4000,
+      65536,
+      false,
+      false,
+      false,
+      false,
+      false,
+    ).includes("export const __napiBindingTarget = 'wasm32-wasip1'"),
+  )
+  t.true(
+    createWasiDeferredBrowserBinding('test').includes(
+      "export const __napiBindingTarget = 'wasm32-wasip1'",
+    ),
+  )
+})
+
+const STAMP_HELPER_DECL =
+  'function __napiStampBindingTarget(exportsObject, target) {'
+const WASI_STAMP_CALL =
+  '__napiStampBindingTarget(__napiModule.exports, __napiBindingTarget)'
+// The CJS loaders assign the guard's return value instead of calling it as a
+// statement: `cjs-module-lexer` only reports `__napiBindingTarget` as a named
+// export when it can see `module.exports.<name> =`, and Node's CJS->ESM named
+// export detection is that lexer.
+const ROOT_CJS_STAMP_CALL =
+  'module.exports.__napiBindingTarget = __napiStampBindingTarget(nativeBinding, __napiLoadedBindingTarget)'
+// The node WASI loader stamps the emnapi exports object — the one the CommonJS
+// tail then aliases — while assigning through `module.exports` for the lexer.
+const WASI_CJS_STAMP_LINE = `module.exports.__napiBindingTarget = ${WASI_STAMP_CALL}`
+// the call inside the initialization try, not the function declaration
+const WASI_EXIT_LISTENER_CALL = '\n  __registerWasiExitListener()'
+// nothing may write the marker onto a user-controlled exports object without
+// going through the guard, so an assignment is only legal when the guard call
+// is its right-hand side
+const UNGUARDED_MODULE_EXPORTS_STAMP =
+  /module\.exports\.__napiBindingTarget = (?!__napiStampBindingTarget\()/
+
+test('browser and deferred loaders carry the flavor on the binding they hand out', (t) => {
+  // `export default __napiModule.exports` and `instantiate()` hand out the raw
+  // emnapi exports object, which a named module export does not travel with.
+  const browser = createWasiBrowserBinding('test')
+  assertValidJS(t, browser, 'browser binding target on exports')
+  t.true(browser.includes(WASI_STAMP_CALL))
+  const deferred = createWasiDeferredBrowserBinding('test')
+  assertValidJS(t, deferred, 'deferred binding target on exports')
+  t.is(
+    deferred.split(WASI_STAMP_CALL).length - 1,
+    1,
+    'every instance created by __createInstance must be marked exactly once',
+  )
+  // the marker is assigned before the instance escapes to the caller
+  t.true(
+    deferred.indexOf(WASI_STAMP_CALL) <
+      deferred.indexOf('exports: __napiModule.exports'),
+  )
+})
+
+test('every mutating loader stamps the binding target through the guard', (t) => {
+  const cases: Array<{ name: string; code: string; call?: string }> = [
+    {
+      name: 'root cjs',
+      code: createCjsBinding('test', '@scope/test', ['sum'], '1.0.0'),
+      call: ROOT_CJS_STAMP_CALL,
+    },
+    {
+      name: 'wasi node cjs',
+      code: createWasiBinding('test', '@scope/test'),
+      call: WASI_CJS_STAMP_LINE,
+    },
+    {
+      name: 'wasi browser esm',
+      code: createWasiBrowserBinding('test'),
+      call: WASI_STAMP_CALL,
+    },
+    {
+      name: 'wasi deferred esm',
+      code: createWasiDeferredBrowserBinding('test'),
+      call: WASI_STAMP_CALL,
+    },
+  ]
+  for (const { name, code, call } of cases) {
+    assertValidJS(t, code, `${name} stamp guard`)
+    t.is(
+      code.split(STAMP_HELPER_DECL).length - 1,
+      1,
+      `${name} must emit the guard exactly once`,
+    )
+    if (call) {
+      t.is(
+        code.split(call).length - 1,
+        1,
+        `${name} must stamp exactly once, through the guard`,
+      )
+    }
+    // [[Define]], not [[Set]]: an ordinary assignment walks the prototype
+    // chain, so an inherited accessor on a user-controlled exports object could
+    // swallow the marker or throw and fail an otherwise successful load
+    t.true(
+      code.includes(
+        "Object.defineProperty(exportsObject, '__napiBindingTarget'",
+      ),
+      `${name} must define the marker as an own data property`,
+    )
+    t.false(
+      code.includes('exportsObject.__napiBindingTarget = target'),
+      `${name} must not stamp the marker through an ordinary assignment`,
+    )
+    // an addon's exports object is user-controlled: nothing may write the
+    // marker onto it without going through the guard
+    t.false(
+      UNGUARDED_MODULE_EXPORTS_STAMP.test(code),
+      `${name} must not assign the marker onto module.exports directly`,
+    )
+    t.false(
+      code.includes('__napiModule.exports.__napiBindingTarget ='),
+      `${name} must not assign the marker onto the emnapi exports directly`,
+    )
+  }
+})
+
+test('the node WASI loader stamps inside the rollback boundary', (t) => {
+  // Anything the guard throws — a conflicting `#[napi(module_exports)]` export,
+  // or an addon accessor whose setter refuses the write — has to land in the
+  // initialization `try`. From outside it the throw escapes with the emnapi
+  // context built and the process 'exit' listener installed, so a failed
+  // `require()` leaks an initialized WASI environment nothing can reach.
+  const code = createWasiBinding('test', '@scope/test')
+  assertValidJS(t, code, 'wasi node cjs rollback boundary')
+  const initializationCatch = '\n} catch (error) {'
+  t.is(
+    code.split(initializationCatch).length - 1,
+    1,
+    'the top-level initialization catch must be unambiguous',
+  )
+  // exactly one, so nothing can stamp a second time outside the boundary
+  t.is(code.split('module.exports.__napiBindingTarget =').length - 1, 1)
+  const stamp = code.indexOf(WASI_CJS_STAMP_LINE)
+  t.true(stamp > code.indexOf('__publishWasiDispose(__napiModule.exports)'))
+  t.true(stamp < code.indexOf(WASI_EXIT_LISTENER_CALL))
+  t.true(stamp < code.indexOf(initializationCatch))
+  // and the rollback the catch runs is the one that tears the environment down
+  t.true(code.includes('__runWasiInitializationRollback(rollback)'))
+})
+
+/**
+ * Every loader that stamps an addon-owned exports object, with the marker that
+ * ends its initialization guard and the host installation that must precede the
+ * stamp. A host install hands that same object to addon-provided registration
+ * functions, which can put anything on it — including this marker — so a stamp
+ * placed before them reads a state that is not final.
+ */
+const HOST_INSTALL_ORDER_CASES = [
+  {
+    name: 'wasi node cjs',
+    build: (asyncRuntime: boolean) =>
+      createWasiBinding(
+        'test',
+        '@scope/test',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        asyncRuntime,
+      ),
+    stamp: WASI_CJS_STAMP_LINE,
+    hostInstall: '__installCurrentThreadHosts(',
+    endOfGuard: WASI_EXIT_LISTENER_CALL,
+  },
+  {
+    name: 'wasi browser esm',
+    build: (asyncRuntime: boolean) =>
+      createWasiBrowserBinding(
+        'test',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        asyncRuntime,
+      ),
+    stamp: WASI_STAMP_CALL,
+    hostInstall: '__installCurrentThreadHosts(',
+    endOfGuard: '\n} catch (error) {',
+  },
+  {
+    name: 'wasi deferred esm',
+    build: (asyncRuntime: boolean) =>
+      createWasiDeferredBrowserBinding(
+        'test',
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        asyncRuntime,
+      ),
+    stamp: WASI_STAMP_CALL,
+    hostInstall: '__registerWorkerdCurrentThreadTaskHost(',
+    endOfGuard: "__lifecycleState === 'pending'",
+  },
+] as const
+
+for (const {
+  name,
+  build,
+  stamp,
+  hostInstall,
+  endOfGuard,
+} of HOST_INSTALL_ORDER_CASES) {
+  test(`${name} stamps the binding object after its host installation`, (t) => {
+    const withHosts = build(true)
+    assertValidJS(t, withHosts, `${name} asyncRuntime stamp order`)
+    const hostInstallAt = withHosts.indexOf(hostInstall)
+    t.true(hostInstallAt > -1, 'the asyncRuntime host install must be emitted')
+    const stampAt = withHosts.indexOf(stamp)
+    t.true(stampAt > hostInstallAt, 'the stamp must follow the host install')
+    t.true(
+      stampAt < withHosts.indexOf(endOfGuard),
+      'the stamp must stay inside the initialization guard',
+    )
+
+    // and without an async runtime the stamp keeps that same place: last thing
+    // before the guard closes, so nothing can reshape the object behind it
+    const withoutHosts = build(false)
+    assertValidJS(t, withoutHosts, `${name} stamp order`)
+    t.is(withoutHosts.indexOf(hostInstall), -1)
+    t.true(withoutHosts.indexOf(stamp) < withoutHosts.indexOf(endOfGuard))
+  })
+}
+
+test('the deferred loader marks the binding without requiring an extensible exports object', (t) => {
+  const deferred = createWasiDeferredBrowserBinding('test')
+  assertValidJS(t, deferred, 'deferred guarded stamp')
+  // a `#[napi(module_exports)]` hook may have sealed or frozen this object
+  t.true(deferred.includes('if (!Object.isExtensible(exportsObject)) {'))
+  // and it may have claimed the name, which is a hard error, not a silent
+  // overwrite — with a stable `code` to branch on
+  t.true(
+    deferred.includes(
+      "Object.prototype.hasOwnProperty.call(exportsObject, '__napiBindingTarget')",
+    ),
+  )
+  t.true(deferred.includes("error.code = 'ERR_NAPI_BINDING_TARGET_CONFLICT'"))
+})
+
+test('every emitted loader says what its own entry reports after a skipped stamp', (t) => {
+  // The runtime is pinned by build.spec.ts (`a frozen addon keeps
+  // __napiBindingTarget importable, just undefined`): both CommonJS entries
+  // replace `module.exports` with the object the stamp was skipped on, so the
+  // value is absent there, while the ESM loaders keep a module-level export.
+  // The comment shipped inside every loader has to describe that split rather
+  // than promise the module export survives everywhere.
+  for (const [name, code] of [
+    ['root cjs', createCjsBinding('test', '@scope/test', ['sum'], '1.0.0')],
+    ['wasi node cjs', createWasiBinding('test', '@scope/test')],
+    ['wasi browser esm', createWasiBrowserBinding('test')],
+    ['wasi deferred esm', createWasiDeferredBrowserBinding('test')],
+  ] as const) {
+    assertValidJS(t, code, `${name} skip contract`)
+    t.false(
+      code.includes('module export still reports it'),
+      `${name} must not claim every entry still reports the target`,
+    )
+    t.true(
+      code.includes('while the CommonJS entries hand back'),
+      `${name} must say the CommonJS entries lose the value`,
+    )
+  }
+
+  // and the root CommonJS loader's own note about its lexer-visible assignment:
+  // that assignment lands on the loader's own `module.exports`, so it always
+  // succeeds and the alias on the next line is what discards it
+  const cjs = createCjsBinding('test', '@scope/test', ['sum'], '1.0.0')
+  t.false(
+    cjs.includes('is a silent no-op'),
+    'the assignment is not a no-op; its target is extensible',
+  )
+  t.true(
+    cjs.includes('The assignment itself always succeeds'),
+    'the root CommonJS loader must not call its own assignment a no-op',
+  )
+  t.true(
+    cjs.includes('own, still extensible `module.exports`'),
+    'the root CommonJS loader must name its real assignment target',
+  )
+})
+
+test('NAPI_RS_NATIVE_LIBRARY_PATH keeps the flavor its override reports', (t) => {
+  const adoption = `__napiLoadedBindingTarget =
+        overrideBinding && typeof overrideBinding.__napiBindingTarget === 'string'
+          ? overrideBinding.__napiBindingTarget
+          : 'native'`
+  for (const [name, code] of [
+    ['cjs', createCjsBinding('test', '@scope/test', ['sum'], '1.0.0')],
+    ['esm', createEsmBinding('test', '@scope/test', ['sum'], '1.0.0')],
+  ] as const) {
+    assertValidJS(t, code, `${name} override binding target`)
+    t.true(code.includes(adoption), `${name} must adopt the override's target`)
+    // the override result must not be returned before it is inspected
+    t.false(
+      code.includes('return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)'),
+      `${name} must bind the override before returning it`,
+    )
+  }
+})
+
 test('WASI worker template matches the CJS/ESM quote and semicolon dialect', (t) => {
   t.true(WASI_WORKER_TEMPLATE.includes("import fs from 'node:fs'"))
   t.false(WASI_WORKER_TEMPLATE.includes('from "node:fs"'))