@napi-rs/cli 3.10.3 → 3.10.5

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

@@ -831,6 +831,263 @@ test('a fresh WASI declaration narrows the inherited root union', async (t) => {
 const ROOT_BINDING_TARGET_DECLARATION =
   "export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'"
 
+test('an ESM root declaration derives the WASI declaration unless it cannot cross', async (t) => {
+  const { tmpDir, projectDir, typeDefDir } = t.context
+  await writeFile(
+    join(typeDefDir, 'sum.type'),
+    '{"kind":"fn","name":"sum","def":"function sum(a: number, b: number): number"}\n',
+  )
+  const { dts } = await generateTypeDef({
+    typeDefDir,
+    cwd: projectDir,
+    declareBindingTarget: true,
+  })
+
+  // A `"type": "module"` package's `index.d.ts` is an ESM declaration, and so
+  // is an explicit `.d.mts` — but the generated typedef carries nothing a
+  // `.d.cts` cannot re-declare, so the WASI declaration derives verbatim.
+  // (napi-rs#3531: an unconditional refusal failed every WASI build in a
+  // module package, including `--esm` ones.)
+  const sourcePath = join(projectDir, 'index.d.ts')
+  const destinationPath = join(projectDir, 'pkg.wasi.d.cts')
+  for (const esmSourcePath of [sourcePath, join(projectDir, 'index.d.mts')]) {
+    t.is(
+      prepareWasiBindingTypeDef(
+        dts,
+        esmSourcePath,
+        destinationPath,
+        true,
+        'module',
+      ),
+      dts,
+    )
+  }
+
+  // The threadless flavor still gets its node-global rewrites on the way, and
+  // what it emits is valid TypeScript beside the ESM source it came from.
+  const threadless = prepareWasiBindingTypeDef(
+    dts,
+    sourcePath,
+    destinationPath,
+    false,
+    'module',
+  )
+  const codes = await semanticDiagnosticCodes(join(tmpDir, 'esm-derived'), {
+    'index.d.ts': dts,
+    'pkg.wasi.d.cts': threadless,
+  })
+  t.deepEqual(codes['pkg.wasi.d.cts'], [])
+
+  // Only the constructs a CommonJS declaration cannot carry still refuse —
+  // each one named in the error, from `.d.ts` and `.d.mts` sources alike.
+  const hazards: Array<[what: string, source: string, barrier: string]> = [
+    [
+      'an `export default` declaration',
+      'export declare function sum(a: number): number\nexport default sum\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default class declaration',
+      'export default class Sum {}\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default function declaration',
+      'export default function sum(a: number): number\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default interface declaration',
+      'export default interface Sum { a: number }\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a default namespace declaration',
+      'export default namespace Sum { const a: number }\n',
+      'an `export default` declaration',
+    ],
+    [
+      'a `default` re-export',
+      'declare const sum: number\nexport { sum as default }\n',
+      'a `default` re-export',
+    ],
+    [
+      'a `default` re-export from a package',
+      "export { sum as default } from 'sums'\n",
+      'a `default` re-export',
+    ],
+    [
+      'a type-only `default` re-export',
+      'type Sum = number\nexport type { Sum as default }\n',
+      'a `default` re-export',
+    ],
+    [
+      'a `default` namespace re-export',
+      "export * as default from 'sums'\n",
+      'a `default` re-export',
+    ],
+    [
+      'a relative import specifier',
+      "import { sum } from './sum.js'\nexport declare function f(): typeof sum\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'an extensionless relative specifier',
+      "import { sum } from './sum'\nexport declare function f(): typeof sum\n",
+      "a relative './sum' specifier",
+    ],
+    [
+      'a relative export specifier',
+      "export { sum } from './sum.js'\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative export-star specifier',
+      "export * from './sums.js'\n",
+      "a relative './sums.js' specifier",
+    ],
+    [
+      'a relative import type specifier',
+      "import type { Sum } from './sum.js'\nexport declare function f(s: Sum): void\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative import() type',
+      "export declare function f(): import('./sum.js').Sum\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative import-equals specifier',
+      "import sum = require('./sum.js')\nexport declare function f(): typeof sum\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative ambient module specifier',
+      "declare module './sum.js' { export const sum: number }\n",
+      "a relative './sum.js' specifier",
+    ],
+    [
+      'a relative types reference',
+      "/// <reference types='./sum' />\nexport declare const sum: number\n",
+      'a relative \'/// <reference types="./sum" />\' directive',
+    ],
+    [
+      'attributes on a runtime statement',
+      "import sum from './sum.json' with { type: 'json' }\nexport declare const s: typeof sum\n",
+      '`with` attributes on a runtime module statement',
+    ],
+  ]
+  const esmSources: Array<
+    [path: string, packageType: 'module' | 'commonjs' | undefined]
+  > = [
+    [sourcePath, 'module'],
+    [join(projectDir, 'index.d.mts'), undefined],
+  ]
+  for (const [what, source, barrier] of hazards) {
+    for (const [esmSourcePath, packageType] of esmSources) {
+      const error = t.throws(
+        () =>
+          prepareWasiBindingTypeDef(
+            source,
+            esmSourcePath,
+            destinationPath,
+            true,
+            packageType,
+          ),
+        { instanceOf: Error },
+      )
+      t.true(
+        error?.message.includes(barrier),
+        `${what} names the offending construct, got: ${error?.message}`,
+      )
+    }
+  }
+
+  // Everything else a module package can write crosses honestly.
+  const honest: Record<string, string> = {
+    'bare and node: imports':
+      "import { Buffer } from 'buffer'\nimport type { ReadableStream } from 'node:stream/web'\nexport declare function f(b: Buffer, s: ReadableStream): void\n",
+    '.mjs specifiers':
+      "import { sum } from './sum.mjs'\nexport declare function f(): typeof sum\n",
+    '.cjs specifiers':
+      "import { sum } from './sum.cjs'\nexport declare function f(): typeof sum\n",
+    'an export assignment':
+      'declare const binding: { sum(a: number): number }\nexport = binding\n',
+    'a declare global block':
+      'declare global { namespace Legacy { const v: number } }\nexport {}\n',
+    'a bare ambient module':
+      "declare module 'legacy' { export const sum: number }\n",
+    'a .mjs ambient module':
+      "declare module './sum.mjs' { export const sum: number }\n",
+    'a default inside an ambient module':
+      "declare module 'legacy' { const sum: number\nexport default sum }\n",
+    'a type-only import with resolution-mode':
+      "import type { Sum } from './sum.js' with { 'resolution-mode': 'import' }\nexport declare function f(s: Sum): void\n",
+    'a type-only import pinned to require mode':
+      "import type { Sum } from './sum.js' with { 'resolution-mode': 'require' }\nexport declare function f(s: Sum): void\n",
+    'a type-only export with resolution-mode':
+      "export type { Sum } from './sum.js' with { 'resolution-mode': 'import' }\n",
+    'a json specifier':
+      "import sum from './sum.json'\nexport declare const s: typeof sum\n",
+    'a path reference':
+      "/// <reference path='./sum.d.ts' />\nexport declare const sum: number\n",
+    'a bare import() type':
+      "export declare function f(): import('buffer').Buffer\n",
+    'an import() type pinned to import mode':
+      "export declare function f(): import('./sum.js', { with: { 'resolution-mode': 'import' } }).Sum\n",
+    'a namespace export':
+      'export declare namespace Legacy { const sum: number }\n',
+  }
+  for (const [what, source] of Object.entries(honest)) {
+    t.notThrows(
+      () =>
+        prepareWasiBindingTypeDef(
+          source,
+          sourcePath,
+          destinationPath,
+          true,
+          'module',
+        ),
+      what,
+    )
+  }
+
+  // Nothing is scanned when the source is already CommonJS — a `.d.cts` (or a
+  // `.d.ts` in a `commonjs` package) reads the same beside its destination, so
+  // every hazard above carries over verbatim.
+  for (const [, source] of hazards) {
+    for (const [cjsSourcePath, packageType] of [
+      [join(projectDir, 'index.d.cts'), 'module'],
+      [sourcePath, 'commonjs'],
+      [sourcePath, undefined],
+    ] as const) {
+      t.notThrows(() =>
+        prepareWasiBindingTypeDef(
+          source,
+          cjsSourcePath,
+          destinationPath,
+          true,
+          packageType,
+        ),
+      )
+    }
+  }
+
+  // A specifier that can cross still rebases onto the destination directory
+  // — including a `declare module` augmentation name, which targets the file
+  // it spells out.
+  const relocated = prepareWasiBindingTypeDef(
+    "/// <reference path='./sum.d.ts' />\ndeclare module './sum.mjs' { export const sum: number }\nexport declare function f(): import('./sum.mjs').Sum\nexport { sum } from './sum.mjs'\n",
+    join(projectDir, 'types', 'index.d.mts'),
+    destinationPath,
+    true,
+  )
+  t.true(relocated.includes("declare module './types/sum.mjs'"))
+  t.true(relocated.includes("import('./types/sum.mjs')"))
+  t.true(relocated.includes("from './types/sum.mjs'"))
+  t.true(relocated.includes("reference path='./types/sum.d.ts'"))
+})
+
 test('a crate without type defs still declares the binding target', async (t) => {
   const { projectDir, typeDefDir } = t.context
 

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

@@ -1123,6 +1123,241 @@ for (const { name, code } of eagerWasiLoaderCases) {
   })
 }
 
+// `napi_prepare_wasm_env_cleanup` waits: it returns only once the addon's async
+// runtime has quiesced, and on a threaded artifact the work it waits for can be
+// waiting for a JavaScript turn from the very thread the export runs on — which
+// never comes, because that thread is inside the export. The addon exposes the
+// same teardown as `…_begin` / `napi_wasm_runtime_work_pending` / `…_finish` so
+// a loader can put real turns in the middle. Every shape that can yield has to
+// use it, and every shape has to keep working against an addon that has no such
+// exports.
+const TWO_PHASE_BARRIER_BY_FLAVOR = {
+  eager: {
+    detect:
+      /if \(typeof begin !== 'function' \|\|\s*typeof finish !== 'function'\) \{/,
+    poll: '}, __WASM_RUNTIME_WORK_POLL_INTERVAL_MS)',
+    finish: '.then(finishCleanup, finishCleanup)',
+    fallback: '__prepareWasmEnvCleanup()',
+    report: '__reportUnreachedWasmEnvSettlements()',
+    // The closer a caller that cannot yield uses to end a parked handshake,
+    // and the point at which the poll publishes it.
+    parked: '__finishParkedWasmEnvCleanup',
+    publishParked: '__finishParkedWasmEnvCleanup = finishCleanup',
+    clearParked: '__finishParkedWasmEnvCleanup = undefined',
+  },
+  deferred: {
+    detect:
+      /if \(typeof __begin !== 'function' \|\|\s*typeof __finish !== 'function'\) \{/,
+    poll: '}, __WASM_RUNTIME_WORK_POLL_INTERVAL_MS)',
+    finish: `return __pollWasmRuntimeWork(__workPending).then(
+      __finishEnvCleanup,
+      __finishEnvCleanup,
+    )`,
+    fallback: '__prepareEnvCleanup()',
+    report: '__reportUnreachedSettlements()',
+    parked: '__finishParkedEnvCleanup',
+    publishParked: '__finishParkedEnvCleanup = __finishEnvCleanup',
+    clearParked: '__finishParkedEnvCleanup = undefined',
+  },
+} as const
+
+for (const { name, code } of wasiLoaderCases) {
+  const barrier =
+    TWO_PHASE_BARRIER_BY_FLAVOR[
+      code.includes(EAGER_ROLLBACK_SIGNATURE) ? 'eager' : 'deferred'
+    ]
+  test(`WASI loader polls the two-phase wasm env cleanup: ${name}`, (t) => {
+    t.true(
+      code.includes('napi_prepare_wasm_env_cleanup_begin'),
+      'loader must start the teardown without joining',
+    )
+    t.true(
+      code.includes('napi_wasm_runtime_work_pending'),
+      'loader must poll the runtime between the two halves; without it there is nothing to wait on',
+    )
+    t.true(
+      code.includes('napi_prepare_wasm_env_cleanup_finish'),
+      'loader must still join: finish is the call that owes quiescence',
+    )
+    // Optional, exactly like every other export in this teardown: an addon
+    // built against a napi crate that predates the split keeps the single
+    // blocking call.
+    t.regex(code, barrier.detect, 'the split must be feature-detected')
+    t.true(
+      code.includes(barrier.fallback),
+      'a loader that finds no split must fall back to the single call',
+    )
+    // Unbounded, and deliberately so. The only way to end the poll early is to
+    // call `…_finish`, which joins on the JavaScript thread — the very thread
+    // the work it joins may be waiting for a turn from — so a budget would not
+    // end that wait, it would only move it somewhere the thread can no longer
+    // be reached. Same reason the async-work drain has no deadline. A host that
+    // breaks the "no blocking closure may wait on a JavaScript turn" rule keeps
+    // its disposal promise pending instead of wedging the thread.
+    t.false(
+      code.includes('__WASM_RUNTIME_DRAIN_TURNS'),
+      'the poll must not carry a turn budget',
+    )
+    t.is(
+      code.split('for (;;) {').length - 1,
+      1,
+      'the poll must be an unbounded loop',
+    )
+    t.true(
+      code.includes(barrier.poll),
+      'the poll must yield with a real referenced timer, not a macrotask spin',
+    )
+    // `__scheduleTimer` falls back to the macrotask scheduler when `setTimeout`
+    // is missing or throws — but not when it is present, returns a handle and
+    // never fires (fake timers; a host whose timers belong to an IO context
+    // that is gone). With no budget left to bail the poll out, that host would
+    // park it forever. Arm both until timers have actually arrived, then pace
+    // on the timer alone rather than spinning the zero-delay queue.
+    //
+    // Whether they arrive is a property of the poll, never of the module: a
+    // host can lose its timers between two disposals, and in the deferred
+    // shape every instance shares this module — one healthy instance must not
+    // disarm the fallback for the next one.
+    t.false(
+      code.includes('let __wasmRuntimePollTimerArrived'),
+      'the pacing state must not outlive the poll that learned it',
+    )
+    t.is(
+      code.split('function __createWasmRuntimePollPace()').length - 1,
+      1,
+      'one definition of the pacing state',
+    )
+    t.is(
+      code.split('__createWasmRuntimePollPace()').length - 1,
+      2,
+      'and exactly one caller: the poll loop, which owns it for its own run',
+    )
+    const yieldStart = code.indexOf('function __yieldWasmRuntimePollTurn(')
+    t.true(yieldStart > 0, 'the poll must yield through one shared turn helper')
+    const yieldTurn = code.slice(yieldStart, code.indexOf('\n}\n', yieldStart))
+    t.true(
+      yieldTurn.includes('__scheduleTimer(') &&
+        yieldTurn.includes('__scheduleMacrotask('),
+      'an undecided turn must arm both primitives, so an inert setTimeout cannot park the poll',
+    )
+    t.true(
+      yieldTurn.includes('pace.arrivals++'),
+      'the timer callback must count that timers work on this host',
+    )
+    t.true(
+      yieldTurn.includes(
+        'pace.arrivals < __WASM_RUNTIME_WORK_POLL_TRUSTED_ARRIVALS',
+      ),
+      'and one arrival must not be enough: it can be a timer armed before the host stopped running them',
+    )
+    // A poll that has settled onto the timer alone has nothing left to fall
+    // back on if the timers stop mid-poll — the turn that armed the dead timer
+    // is the turn that parks, and a parked poll schedules nothing that could
+    // notice. Every turn keeps a longer timer outstanding for that.
+    t.true(
+      yieldTurn.includes('__armWasmRuntimePollStallBackup('),
+      'every turn must keep a stall backup outstanding, armed while the timers still work',
+    )
+    const backupStart = code.indexOf(
+      'function __armWasmRuntimePollStallBackup(',
+    )
+    t.true(backupStart > 0, 'the backup must be one shared helper')
+    const stallBackup = code.slice(
+      backupStart,
+      code.indexOf('\n}\n', backupStart),
+    )
+    t.true(
+      stallBackup.includes('pace.arrivals = 0'),
+      'a turn the backup has to end proves the timers stopped: the poll goes back to arming both',
+    )
+    t.true(
+      stallBackup.includes('pace.settleTurn'),
+      'and the backup must end whichever turn is parked, not the one that armed it',
+    )
+    // By due time, never by how long the parked turn has been waiting. A host
+    // runs its timers in due order, so a backup that runs while a turn due a
+    // window earlier is still parked proves that turn's timer was dropped —
+    // and a healthy turn, whose timer runs first and clears `settleTurn`, is
+    // never touched. Measuring the wait instead has a phase hole: arms spaced
+    // further apart than the window leave the turn that parks between them
+    // with no backup young enough to rescue it.
+    t.regex(
+      stallBackup,
+      /pace\.turnTimerDueAt > (?:__)?dueAt - __WASM_RUNTIME_WORK_POLL_STALL_MS/,
+      'the backup must judge by due time, so there is no phase to fall through',
+    )
+    t.false(
+      stallBackup.includes('Date.now() -'),
+      'and it must not measure how long the parked turn has waited',
+    )
+    t.true(
+      yieldTurn.includes('pace.settleTurn = undefined'),
+      'a turn that ends must stop being the parked one, or a later backup reads a due time already answered',
+    )
+    t.regex(
+      yieldTurn,
+      /if \(__settled\??\) \{\s*return\s*\}|if \(settled\) \{\s*return\s*\}/,
+      'whichever primitive loses the race must resolve nothing: one poll per turn',
+    )
+    t.true(
+      code.includes(barrier.finish),
+      'finish must run whether the poll ended, timed out or could not run at all',
+    )
+    // The one caller that cannot yield is the raw `Context.destroy()` the
+    // wrapper intercepts, and the queue it leaves behind is discarded by the
+    // destroy that follows. Say so, once, without throwing.
+    t.true(
+      code.includes(barrier.report),
+      'the single-call barrier must report settlements nothing can reach any more',
+    )
+    // The window between the halves spans real event-loop turns, so a caller
+    // that cannot yield — the CJS 'exit' teardown, the managed beforeExit one —
+    // can land in the middle of one. It cannot wait for the poll; it has to
+    // close the handshake itself, because `…_finish` is the call that joins and
+    // lowers the barrier. Without this the context is destroyed with the
+    // barrier still raised, the runtime never joined and the destroy recorded
+    // as done.
+    t.is(
+      code.split(barrier.publishParked).length - 1,
+      1,
+      'the poll must publish a closer before it yields',
+    )
+    t.is(
+      code.split(barrier.clearParked).length - 1,
+      1,
+      'finishing the handshake must retract that closer exactly once',
+    )
+    const parkedIndex = code.indexOf(`const ${barrier.parked}`)
+    t.true(
+      parkedIndex > 0 || code.includes(`let ${barrier.parked}`),
+      'the closer must live outside the barrier, where a non-yielding caller can reach it',
+    )
+    // And the single call is where it is reached: every teardown path runs the
+    // barrier through it before destroying, so closing a parked handshake there
+    // covers all of them at once.
+    const isEager = barrier.parked === '__finishParkedWasmEnvCleanup'
+    const prepareStart = code.indexOf(
+      isEager
+        ? `function ${barrier.fallback.replace('()', '')}() {`
+        : `const ${barrier.fallback.replace('()', '')} = () => {`,
+    )
+    t.true(prepareStart > 0, 'the single-call barrier must be one function')
+    const prepareBody = code.slice(
+      prepareStart,
+      code.indexOf(isEager ? '\n}\n' : '\n  }\n', prepareStart),
+    )
+    const closerIndex = prepareBody.indexOf(barrier.parked)
+    t.true(
+      closerIndex > 0,
+      'the single call must close a parked handshake instead of skipping the barrier',
+    )
+    t.true(
+      closerIndex < prepareBody.indexOf('napi_prepare_wasm_env_cleanup'),
+      'and it must close it before looking the single-call export up: a parked handshake is already begun',
+    )
+  })
+}
+
 // 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,
@@ -1140,14 +1375,22 @@ const CONTEXT_DESTROY_WRAP_SIGNATURE =
 const preparingBarrierGuards = {
   shared: {
     probe: '__isPreparingWasmEnvCleanup',
+    // Both barrier entry points read it: the single call and the two-phase
+    // form, which keeps it raised across the turns it yields. The single call
+    // splits the check in two, because a handshake parked between the halves is
+    // one it closes rather than refuses — see the two-phase test above — so the
+    // shape below is the reentrancy half alone.
+    entryGuard: `  if (__emnapiWasmEnvCleanupPreparing) {
+    return
+  }`,
+    twoPhaseEntryGuard: `  if (__emnapiWasmEnvCleanupPrepared || __emnapiWasmEnvCleanupPreparing) {
+    return
+  }`,
     snippets: [
       'let __emnapiWasmEnvCleanupPreparing = false',
       `function __isPreparingWasmEnvCleanup() {
   return __emnapiWasmEnvCleanupPreparing
 }`,
-      `  if (__emnapiWasmEnvCleanupPrepared || __emnapiWasmEnvCleanupPreparing) {
-    return
-  }`,
       `    __emnapiWasmEnvCleanupPreparing = true
     try {
       prepare()
@@ -1158,12 +1401,15 @@ const preparingBarrierGuards = {
   },
   deferred: {
     probe: '__isPreparingEnvCleanup',
+    entryGuard: `    if (__wasmEnvCleanupPreparing) {
+      return
+    }`,
+    twoPhaseEntryGuard: `    if (__wasmEnvCleanupPrepared || __wasmEnvCleanupPreparing) {
+      return
+    }`,
     snippets: [
       'let __wasmEnvCleanupPreparing = false',
       'const __isPreparingEnvCleanup = () => __wasmEnvCleanupPreparing',
-      `    if (__wasmEnvCleanupPrepared || __wasmEnvCleanupPreparing) {
-      return
-    }`,
       `      __wasmEnvCleanupPreparing = true
       try {
         __prepareWasmEnvCleanup()
@@ -1267,6 +1513,20 @@ for (const { name, code, prepare, guard } of wrappedContextCreationCases) {
         `barrier must carry its in-flight guard exactly once: ${snippet}`,
       )
     }
+    // Both barrier entry points — the single call and the two-phase form —
+    // refuse to re-enter a barrier already in flight. The two-phase form still
+    // tests the pair in one condition; the single call tests the reentrancy
+    // half on its own, after it has dealt with a parked handshake.
+    t.is(
+      code.split(guard.entryGuard).length - 1,
+      1,
+      'the single call must refuse to re-enter a barrier already in flight',
+    )
+    t.is(
+      code.split(guard.twoPhaseEntryGuard).length - 1,
+      1,
+      'the two-phase barrier must refuse to re-enter a barrier already in flight',
+    )
     t.is(
       code.split(NESTED_DESTROY_NO_OP).length - 1,
       1,

package/src/api/build.ts

@@ -21,6 +21,7 @@ import type { BuildOptions as RawBuildOptions } from '../def/build.js'
 import {
   CLI_VERSION,
   commitFileSystemTransaction,
+  commonJsDeclarationBarrier,
   copyFileAtomic,
   type Crate,
   debugFactory,
@@ -41,7 +42,9 @@ import {
   removeNodeStreamWebTypeImports,
   rewriteUnboundNodeGlobalTypeQueries,
   rewriteTypeImportReferences,
+  checkSelfsign,
   scanExportedName,
+  signFileAtomic,
   type Target,
   targetToEnvVar,
   tryInstallCargoBinary,
@@ -253,7 +256,7 @@ export function checkAsyncRuntimeHostContract({
   }
   if (!asyncRuntime && missingHostExports.length === 0) {
     return {
-      warning: `${packageName} exports the napi-async-runtime host contract but napi.wasm.asyncRuntime is not enabled. The generated WASI loaders will not install the CurrentThread task and timer hosts, so async exports will never make progress unless the host is installed by hand.`,
+      warning: `${packageName} exports the napi-async-runtime host contract but napi.wasm.asyncRuntime is not enabled. The generated WASI loaders will not install the CurrentThread task and timer hosts, so a binding running the CurrentThread flavor (the default on every wasm target) will make no progress unless the hosts are installed by hand. A wasm32-wasip1-threads binding that configures MultiThread does not need them.`,
     }
   }
   return {}
@@ -795,6 +798,16 @@ export function bindingTargetDeclarationPredicate(input: {
     (input.rootLoaderCandidate && (input.hasWasiFallback || exports.length > 0))
 }
 
+/**
+ * The `.d.cts` content for a WASI flavor loader, derived from the root
+ * declaration this build wrote.
+ *
+ * An ESM source (`*.d.mts`, or `*.d.ts` in a `"type": "module"` package) is
+ * re-declared verbatim when nothing in it changes meaning under CommonJS
+ * interpretation — which is everything a generated typedef and most
+ * `--dts-header`s contain. {@link commonJsDeclarationBarrier} names the
+ * constructs that still refuse, and why.
+ */
 export function prepareWasiBindingTypeDef(
   source: string,
   sourcePath: string,
@@ -803,12 +816,15 @@ export function prepareWasiBindingTypeDef(
   packageType?: 'module' | 'commonjs',
 ) {
   if (
-    sourcePath.endsWith('.d.mts') ||
-    (sourcePath.endsWith('.d.ts') && packageType === 'module')
+    sourcePath.endsWith('.mts') ||
+    (sourcePath.endsWith('.ts') && packageType === 'module')
   ) {
-    throw new Error(
-      `Cannot emit the CommonJS WASI declaration ${destinationPath} from the ESM declaration ${sourcePath}. Use a .d.cts --dts path for WASI builds in module packages.`,
-    )
+    const barrier = commonJsDeclarationBarrier(source)
+    if (barrier !== undefined) {
+      throw new Error(
+        `Cannot emit the CommonJS WASI declaration ${destinationPath} from the ESM declaration ${sourcePath}: ${barrier} cannot be re-declared in a CommonJS declaration. Use a .d.cts --dts path for WASI builds from ESM sources.`,
+      )
+    }
   }
   const targetSource = hasThreads
     ? source
@@ -1124,6 +1140,7 @@ export async function buildProject(rawOptions: BuildOptions) {
 
   const options: ParsedBuildOptions = {
     dtsCache: true,
+    ohosSign: true,
     ...rawOptions,
     format: resolveBuildFormat(rawOptions),
     cwd: rawOptions.cwd ?? process.cwd(),
@@ -2452,6 +2469,40 @@ class Builder {
       } else {
         await copyFileAtomic(src, dest)
         artifactReplaced = true
+        // OpenHarmony devices refuse to load unsigned `.so` files, so inject
+        // the fs-verity `.codesign` self-signature unless `--no-ohos-sign`.
+        if (
+          this.target.platform === 'openharmony' &&
+          this.options.ohosSign !== false
+        ) {
+          debug('Self-signing OpenHarmony artifact:')
+          debug('  %i', dest)
+          try {
+            // Force mode: the OHOS SDK linker can already self-sign artifacts
+            // when its opt-in code-signing is enabled — strip that signature
+            // and re-sign rather than failing on the existing `.codesign`
+            // section.
+            signFileAtomic(dest, true)
+            // Re-verify the signature we just wrote so a corrupt or
+            // mis-injected `.codesign` section is surfaced immediately.
+            const { ok, reason } = checkSelfsign(readFileSync(dest))
+            if (!ok) {
+              debug.warn(
+                `OpenHarmony self-sign verification failed: ${dest}: ${reason}`,
+              )
+            }
+          } catch (e) {
+            // Self-signing is best-effort: HarmonyOS only ships on aarch64,
+            // and the algorithm (like the official binary-sign-tool) is only
+            // exercised against aarch64 artifacts — warn instead of failing
+            // the whole build when e.g. an x86_64 artifact cannot be signed.
+            // signElf rejects before writing anything, so `dest` still holds
+            // the copied artifact.
+            debug.warn(
+              `Skip OpenHarmony self-signing: ${dest}: ${(e as Error).message}`,
+            )
+          }
+        }
       }
       this.outputs.push({
         kind: dest.endsWith('.node') ? 'node' : isWasm ? 'wasm' : 'exe',