Add moonrun async fs wasm host

.gitmodules

@@ -2,3 +2,6 @@
 	path = crates/moonutil/resources/error_codes
 	url = https://github.com/moonbitlang/moonbit-docs.git
 	branch = markdown-build
+[submodule "third_party/moonbitlang_async"]
+	path = third_party/moonbitlang_async
+	url = https://github.com/moonbitlang/async.git

CONTEXT.md

@@ -0,0 +1,60 @@
+# MoonBuild Async Wasm Runtime
+
+This context names the concepts used to describe `moonrun` support for running `moonbitlang/async` on the wasm backend.
+
+## Language
+
+**Semantic Stub Boundary**:
+The operation-level contract exposed by `moonbitlang/async` native stubs, independent of native pointer layout or runtime object representation.
+_Avoid_: Raw C ABI boundary
+
+**Mapped Parity**:
+A compatibility goal where wasm host behavior is tracked against native async stub operations without requiring a literal translation of the C files.
+_Avoid_: Rewrite, line-by-line port
+
+**Host Handle**:
+An integer resource identity that the wasm guest can store and pass back while the host owns the underlying resource.
+_Avoid_: Raw fd, raw HANDLE, externref
+
+**Guest Owner Struct**:
+A wasm-side value that keeps MoonBit-owned data reachable while the host has a pending operation referring to its guest-memory range.
+_Avoid_: Pinned guest pointer
+
+**Guest String Path**:
+An async path argument passed from wasm to `moonrun` as a borrowed MoonBit `String` pointer plus a length measured in UTF-16 code units.
+The guest must not pre-encode these paths as UTF-8 `Bytes`; `moonrun` converts the UTF-16 units into `OsString`, using the host's native path representation.
+_Avoid_: UTF-8 path bytes, C string path
+
+**Source Provenance Import**:
+A `moonbit_v0` import declared together with the async C-stub source file and native symbol it tracks.
+_Avoid_: Untraceable host helper
+
+**Ported Symbol Origin**:
+A V8-free Rust host implementation entry that records the async C-stub file and native symbol it is ported from. Active mapped imports must have both registry provenance and implementation provenance.
+_Avoid_: Source comments that tests cannot verify
+
+**Async Sys Module**:
+A V8-free, source-shaped Rust module that owns the behavior of a native async C-stub operation. It may use `AsyncHost` for shared runtime state, resource tables, guest-memory helpers, or shared ABI representation types, but the operation logic belongs in the sys module.
+_Avoid_: Thin wrappers around behavior hidden in `AsyncHost`
+
+**Current Guest Memory**:
+The `WebAssembly.Memory` object exposed as `moonbit_v0.memory` by the JS glue after instance creation or imported-memory discovery.
+Host calls reacquire the current backing store for each import and never retain borrowed guest slices.
+_Avoid_: Cached raw wasm pointer
+
+**Async Monotonic Time**:
+The wasm host value returned for async `ms_since_epoch`. It has millisecond precision and is monotonic from an arbitrary process-local origin; callers may compare values by subtraction, but the absolute value is not meaningful.
+_Avoid_: Wall-clock epoch
+
+## Boundary Decisions
+
+- `moonrun` keeps V8 as the first adapter, but async host state remains outside V8 types.
+- `AsyncHost` owns shared runtime state, resource tables, guest-memory helpers, and shared ABI representation types. `async_sys` owns ported operation behavior.
+- `moonbit_v0` imports strip the native `moonbitlang_async_` prefix and do not add an `async_` prefix.
+- Native C stubs are the semantic reference. Rust code should stay structurally close to the source files, but it does not link against `moonbit.h` object layouts.
+- Wasm async time uses a monotonic host clock from an unspecified origin. Native C stubs currently use platform wall-clock APIs, but async timer semantics only require elapsed millisecond differences.
+- The async wasm host currently supports only Unix-family and Windows hosts. Other host families are compile-time unsupported.
+- Variable-length data crosses the boundary through guest offsets and explicit lengths. Async jobs store host-owned buffers plus guest offsets, then copy into freshly reacquired guest memory during a later host call.
+- Async path arguments are the exception to byte-buffer transport: they cross as Guest String Paths so Windows reaches `OsString`/wide OS calls without a guest UTF-8 encode followed by host UTF-16 re-encode.
+- V8 memory growth can replace the observable memory backing store. The runtime must not lend guest pointers to OS APIs that need pinned buffers across `memory.grow`; use host-owned pinned buffers and copy to/from wasm memory instead.
+- Windows APIs that require stable buffers should receive host-owned memory, not raw wasm memory. This includes overlapped IO and other APIs where the OS may retain a pointer until asynchronous completion.

TODO.md

@@ -0,0 +1,41 @@
+# Async Wasm Runtime Audit TODO
+
+## Narrative
+
+And PR #1772 adds the `moonrun` host runtime needed for `moonbitlang/async` on the wasm backend, with a declared MVP surface around filesystem, fd, c_buffer, os_error, env, time, thread_pool, and limited process support.
+
+But upstream async wasm tests have been failing, and serializing timing-sensitive tests can hide scheduler or ABI bugs rather than proving the Rust host runtime faithfully preserves the native C-stub semantics.
+
+Therefore prioritize ABI, ownership, and completion correctness before relying on test serialization as evidence of stability.
+
+## Priority List
+
+1. [ ] Fix ABI and guest-memory lifetime safety.
+   And wasm jobs pass borrowed guest pointers that must remain valid until host completion.
+   But `Job::file_time_by_path` does not retain the output `FileTime`, and several copy-out paths are not transactional.
+   Therefore retain every guest owner needed by pending jobs and make `run_job`, `fetch_completion`, and `pipe` validate or roll back on copy-out failure.
+
+2. [ ] Prevent hangs and lost completions.
+   And the wasm event loop depends on every running worker job eventually publishing a completion.
+   But stale or freed job handles can currently make a worker return without queueing a completion.
+   Therefore make worker failure paths publish a completion or surface a deterministic error so the event loop cannot wait forever.
+
+3. [ ] Audit supported-surface parity only.
+   And the PR intentionally supports an MVP subset of async host imports.
+   But poll, direct IO, sockets, TLS, named pipes, and some spawn-job APIs are registered as unsupported.
+   Therefore verify parity for the supported surface and document unsupported imports as explicit scope boundaries.
+
+4. [ ] Check process behavior separately.
+   And wasm process support is partly custom glue rather than a direct C-stub port.
+   But Unix signaled child status, Windows argv quoting, Windows handle inheritance, and silently ignored spawn options can diverge from native behavior.
+   Therefore either match native semantics or fail loudly for unsupported process options.
+
+5. [ ] Stabilize tests after correctness fixes.
+   And upstream async tests include timing-sensitive cases.
+   But `--no-parallelize` or `--max-concurrent-tests` only reduces scheduling pressure.
+   Therefore apply serialization as a stability measure after ABI and completion bugs are addressed.
+
+6. [ ] Add focused regression coverage.
+   And upstream package success gives useful end-to-end confidence.
+   But it does not stress malformed guest ranges, too-small logical buffers, failed copy-outs, lost completions, or ownership mistakes.
+   Therefore add targeted tests for invalid guest buffers, file-time copy-out, completion fetch failure, pipe output failure, `file_time_by_path` ownership, and process edge cases.

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_fs/app/main/fs_smoke.mbt

@@ -0,0 +1,18 @@
+///|
+async test "write and read file through async fs" {
+  let path = "async-fs-smoke.txt"
+  @fs.write_file(path, b"wasm async fs", create_mode=CreateOrTruncate)
+  let content = @fs.read_file(path).text()
+  inspect(content, content="wasm async fs")
+  {
+    let file = @fs.open(path, mode=ReadWrite)
+    defer file.close()
+    file.write_at(b"IO", position=5)
+    let buf = FixedArray::make(2, b'\x00')
+    let n = file.read_at(buf, position=5)
+    inspect(n, content="2")
+    json_inspect(buf.unsafe_reinterpret_as_bytes()[:n], content="IO")
+  }
+  let content = @fs.read_file(path).text()
+  inspect(content, content="wasm IOync fs")
+}

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_fs/app/main/moon.pkg.json

@@ -0,0 +1,3 @@
+{
+  "import": [ "moonbitlang/async", "moonbitlang/async/fs" ]
+}

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_fs/app/moon.mod.template

@@ -0,0 +1,11 @@
+name = "moon/async_fs_workspace"
+
+version = "0.1.0"
+
+import {
+  "moonbitlang/async@0.19.1",
+}
+
+options(
+  source: ".",
+)

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_fs/moon.work.template

@@ -0,0 +1,5 @@
+members = [
+  "./app",
+  "@@ASYNC_MEMBER@@",
+]
+preferred_target = "wasm"

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_timer/app/main/moon.pkg.json

@@ -0,0 +1,3 @@
+{
+  "import": [ "moonbitlang/async" ]
+}

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_timer/app/main/timer.mbt

@@ -0,0 +1,5 @@
+///|
+async test "timer sleep resumes" {
+  @async.sleep(1)
+  println("timer resumed")
+}

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_timer/app/moon.mod.template

@@ -0,0 +1,11 @@
+name = "moon/async_timer_workspace"
+
+version = "0.1.0"
+
+import {
+  "moonbitlang/async@0.19.1",
+}
+
+options(
+  source: ".",
+)

crates/moon/tests/test_cases/moon_test/async_wasm_workspace_timer/moon.work.template

@@ -0,0 +1,5 @@
+members = [
+  "./app",
+  "@@ASYNC_MEMBER@@",
+]
+preferred_target = "wasm"