ReviewOS

zig-utils/zig-js

ABI: implement private Promise creation, downcasts, and wrapping

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

Parent: #140 Tracks: #163, #164 Depends on: #180

Implement the coherent native Promise and aliased InternalPromise creation/downcast/wrapping slice shared by the pinned Home and Bun private-JSC profiles.

Exact ABI scope

  • JSC__AnyPromise__wrap
  • JSC__JSPromise__create
  • JSC__JSPromise__rejectedPromise
  • JSC__JSPromise__rejectedPromiseValue
  • JSC__JSPromise__resolvedPromise
  • JSC__JSPromise__resolvedPromiseValue
  • JSC__JSPromise__wrap
  • JSC__JSValue__asInternalPromise
  • JSC__JSValue__asPromise
  • JSC__JSValue__createInternalPromise

Acceptance

  • Create fresh pending promises in the selected global realm with the selected Promise.prototype.
  • Treat JSInternalPromise as the pinned ABI alias of JSPromise; both downcasts accept only live native Promise cells from any live VM and reject primitives, ordinary objects, exception cells, and empty values.
  • Make pointer-returning and encoded-value constructors preserve the exact promise cell/handle contract.
  • Make resolved/rejected constructors store the exact supplied value directly without thenable assimilation; same-VM sibling values are accepted and foreign-VM values fail with a VM-shared TypeError.
  • Match JSPromise__wrap: consume callback exceptions into rejection, reject returned Error instances, pass through returned native promises unchanged, and directly fulfill ordinary callback results.
  • Match AnyPromise__wrap: settle the supplied pending native promise, consume callback exceptions into rejection, reject returned Error instances, and use normal Promise resolution for ordinary results including thenable assimilation and self-resolution rejection.
  • Cover callback reentrancy, exception identity/clearing, value identity, realm/prototype selection, already-settled targets, and invalid handles in the combined compile-link-runtime fixture.
  • Regenerate Home/Bun inventories, keep exact ABI verification green, update README/ABI documentation and parent issue evidence, and publish focused validation results.

JSC__JSValue___then and application-specific async/rejection notification hooks are intentionally outside this child because they require the separate host-function/reaction callback ABI rather than this creation and settlement boundary.

9 days ago

Implemented and documented on main in 550b2eb and 2e8a300.

Evidence:

  • zig build test-home-private-abi -Doptimize=Debug: Home inventory 71 implemented / 361 pending; combined fixture 69/69 linked and runtime matrix passed.
  • zig build home-private-abi-audit bun-private-abi-audit c-api-audit: Home 71/432, Bun 71/422, public 117/117, extensions 19, private exports 71.
  • Covered selected-realm prototypes; pending/direct fulfilled/direct rejected creation; direct thenable storage; JSPromise/InternalPromise downcasts; sibling and foreign VM behavior; Promise passthrough; Error and thrown-value rejection identity; callback exception clearing/reentrancy; AnyPromise assimilation, self-resolution, settled-target no-op, and invalid-target failure.
  • README, Home integration guide, API guide, and ABI guide now publish the 71/361 Home and 71/351 Bun totals plus the exact Promise semantics. Benchmark scores remain unchanged because this ABI-only slice does not alter benchmark workloads.

Sign in to comment on this issue.