ReviewOS

zig-utils/zig-js

ABI: bridge private Promise reactions to JSHostFn callbacks

#253
Closed chris opened this 9 days ago ·
9 days ago

Parent: #140 Profiles: #163, #164 Roadmap: #134

Implement the exact Home/Bun private-JSC Promise reaction bridge exported as JSC__JSValue___then.

Acceptance:

  • Accept native JSPromise values from either supported realm in the same VM and ignore non-Promise values without invoking callbacks.
  • Register distinct fulfillment and rejection JSHostFn callbacks through the engine's native Promise reaction queue.
  • Invoke the selected callback exactly once with a JSC64 CallFrame containing settlement value as argument 0 and the retained context JSValue as argument 1.
  • Preserve asynchronous FIFO microtask ordering for already-settled and later-settled promises; never invoke inline.
  • Keep callback functions, context values, source promises, and queued arguments alive through GC until delivery, then release reaction storage normally.
  • Preserve sibling-realm behavior, reentrant callback behavior, pending-exception boundaries, and exact no-op behavior for non-Promise inputs.
  • Add the export to both pinned inventories, the compiled consumer link/runtime fixture, API/ABI docs, and README evidence.
  • Regenerate both audits with zero unclassified entries and publish exact counts before closing.

Bun__attachAsyncStackFromPromise is intentionally separate: it reconstructs generator/await stack metadata rather than registering Promise reactions.

9 days ago

Implemented and published on main in two focused commits:

  • 7b774bca — runtime, exact GC roots, inventories, and compiled fixture
  • 657cbba8 — README and API/ABI integration evidence

Validation:

  • Home: 260/431 implemented, 171 pending, zero unclassified
  • Bun core: 254/421 implemented, 167 pending, zero unclassified
  • Compiled Home consumer: 259/259 symbols linked; runtime matrix passed

The fixture covers already-settled and later-settled fulfillment, rejection, no-inline delivery, exact two-argument JSC64 CallFrames, sibling realms, GC retention, FIFO nested registration, callback throws with preservation of later jobs, non-Promise/null-callback no-ops, and first-pending-exception preservation. The benchmark report remains current and linked from the README because this embedding-only path is outside the measured interpreter workload.

9 days ago

All acceptance criteria are green on main through 657cbba.

Sign in to comment on this issue.