Support async futures in JS bindings

[tekumara]

The change turns JS async external calls from “awaited by the wrapper before Monty sees them” into proper Monty-managed external futures.

Previously, runMontyAsync() would call a JavaScript external function, and if the result was a Promise, it would simply await that promise in JavaScript before resuming Monty with a
concrete value. That worked for simple linear code, but it meant Monty never saw a pending future. As soon as Python code did something like:

  import asyncio
  results = await asyncio.gather(fetch_a(), fetch_b())

Monty could suspend with RunProgress::ResolveFutures, but the JS binding had no representation for that suspension point. It hit the old fallback:

  Some("Async futures (ResolveFutures) are not yet supported in the JS bindings".to_owned())

So the binding could advertise async support, but it was really only “JS awaits outside Monty”, not “Monty can drive async Python semantics”.

The new design exposes that missing VM state to JavaScript.

When a JS external function returns a promise, runMontyAsync() now does not await it immediately. Instead, it calls the new native method:

  snapshot.resumePending()

That resumes Monty with ExtFunctionResult::Future(callId). Monty then stores an internal ExternalFuture and continues running Python code. If the Python code later awaits that
future, or if asyncio.gather() blocks on several such futures, Monty yields a ResolveFutures state.

The JS binding now represents that state as a new class:

  MontyResolveFutures

It exposes:

  pendingCallIds
  resume({ results: [...] })
  dump()
  load()
  repr()

The wrapper keeps a map of JS promises keyed by Monty callId. When Monty yields MontyResolveFutures, the wrapper waits for one of the requested JS promises to settle, converts that
fulfillment or rejection into a Monty future result, and resumes Monty. That loop repeats until Monty completes or raises.

The key decision was to keep Monty as the scheduler for Python async semantics, rather than trying to emulate scheduling entirely in TypeScript. The Rust VM already knows which
futures are pending, which tasks are blocked, and how asyncio.gather() should resume. The binding’s responsibility is now just to correlate Monty callIds with host promises and feed
results back when requested.

I also added callId to MontySnapshot because the JS layer needs a stable identifier to associate a pending JS promise with the Monty external future that represents it. Without
exposing callId, the wrapper could call resumePending(), but it would not know how to match a later pendingCallIds request back to the original promise.

Another choice was to preserve the existing synchronous API shape as much as possible. Regular resume({ returnValue }) still works. Synchronous external functions still resume
immediately. Only promise-like results take the new resumePending() path. The public start/resume union is extended from:

  MontySnapshot | MontyNameLookup | MontyComplete

to:

  MontySnapshot | MontyNameLookup | MontyResolveFutures | MontyComplete

That reflects the actual VM state now instead of hiding it behind a NotImplemented error.

Tests were updated to use Python await for async JS external functions, because that is now the intended model: if a JS function returns a promise, Monty sees an awaitable external
future. There is a small backwards-compatibility fallback for the simple old pattern where an un-awaited external future is the final top-level result, but the documented behavior
is now to write:

  await fetch_data()

or:

  await asyncio.gather(fetch_a(), fetch_b())

The regression test specifically verifies that two gathered JS promises are active at the same time, proving that Monty is no longer serializing async external calls through the
wrapper.

Finally, the limitations docs were updated to make the binding behavior explicit: JavaScript promises are Monty external futures, Python should await them, and non-awaited promise usage is only supported in the simple top-level compatibility case.

[codspeed-hq]

Merging this PR will not alter performance

✅ 17 untouched benchmarks
⏩ 15 skipped benchmarks¹

---

_{Comparing tekumara:js-async-futures (8e04a27) with main (90ead8d)}

Footnotes

1. 15 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

No issues found across 6 files

_{Re-trigger cubic}