[guybedford]

This makes the sync argument of #28022 an explicit opt-in, as an __async options list, in place of recognising it by the name of a body's last parameter.

__async may now be a list of options. 'auto' is __async: 'auto' as before, and 'sync' has the body told, in a trailing sync parameter, whether it must complete synchronously:

__syscall_poll__async: ['auto', 'sync'],
__syscall_poll: (fds, nfds, timeout, sync) => { ... },

• An 'auto' function no longer looks at its parameter names; listing 'sync' is what provides the argument, and a listed 'sync' whose last parameter is not named sync is a build error, as are an empty list and an unknown option. __sig is no longer consulted for this.
• ['sync'] alone is the function that blocks only when proxied from a pthread: it is never a suspending import, so under ASYNCIFY/JSPI sync is true, and false only on behalf of a sync-proxied pthread caller, which awaits a returned Promise. This is the contract of fd_write waiting on a full pipe (Blocking pipe writes from pthreads wait for the reader #28083), which must stay a plain import for every printf caller; it requires __proxy: 'sync'.
• __async: true and __async: 'auto' are unchanged. __syscall_poll and __syscall_epoll_pwait list ['auto', 'sync'].
• Docs in the "Marking JS library functions as async" section are updated accordingly.

Tests: jslib.test_jslib_async_auto_sync gains ['sync']-only variants in plain, ASYNCIFY and PROXY_TO_PTHREAD builds, and jslib.test_jslib_async_options_errors covers the four build errors.

Made with AI assistance under my review

[gemini-code-assist]

Code Review

This pull request introduces support for specifying __async options as an array (e.g., ['auto', 'sync'] or ['sync']) in JS libraries, allowing more granular control over when a function can return a Promise or must complete synchronously. It updates the documentation, jsifier, syscall library, module loading, and tests to support this new feature. Feedback on the changes suggests improving error handling in expandAsyncOptions to prevent cascading errors when an unknown async option is encountered.

[guybedford]

This is a little too messy - I think default on is the better alternative, and opt-in remains preferable to that. So sticking with the status quo.