Repository navigation
Description
Parent: #474
Related: #480, #493, #874, #885, #888
Problem
Promise rejection-tracker state currently changes before the corresponding realm queue publication:
- settlement sets
rejection_queued = true, unlocks the Promise, then performs a fallible unhandled-queue append; - first post-notification handler attachment sets
rejection_handled_notified = true, unlocks the Promise, then performs a fallible handled-queue append.
If either append returns OutOfMemory, the Promise can claim the notification is queued/already accounted for while no queue root exists. zig-js supports bounded-heap recovery, so aborting the current evaluation does not justify permanently losing or duplicating the host event.
A reserve-before-commit transaction is insufficient: native resolving functions consume their shared once-only bit before calling resolve/reject, so reservation OOM could leave a pending Promise whose exact settlement cannot be retried. #874 therefore owns the shared allocation-free FIFO representation; this issue owns the Promise-state/publication transaction across Promise.lock and realm_lock.
Required implementation
- Publish unhandled and later-handled tracker state through the allocation-free Promises: bound host rejection queue draining #874 FIFO, removing the allocator failure boundary entirely.
- Use one explicit canonical
realm_lock → Promise.locktransaction, with a Promise-lock probe followed by revalidation after acquiring the canonical order. - Commit the queue root, GC insertion barrier, and corresponding Promise state before releasing either lock.
- Preserve exact FIFO/reentrant ordering, one-time unhandled delivery, early-handled skipping, later
rejectionHandleddelivery, precise tracing/relocation, and shared-realm synchronization. - Keep the ordinary fulfilled and already-handled fast paths free of realm-lock acquisition.
No-workaround rules
- No swallowed OOM, best-effort notification loss, unbounded emergency reserve, global serialization, event cap, retry loop that can duplicate callbacks, or Context-destruction-only recovery.
- Do not clear a state bit after failure unless a deterministic later operation is guaranteed to republish the exact pending event.
- Do not leave a fallible allocator operation between consuming a once-only capability and publishing required rejection-tracker state.
Acceptance
- Deterministic failing-allocator witnesses prove both unhandled and later-handled publication perform zero allocations while flags and FIFO membership commit exactly.
- Repeated settlement, pre-notification handling, post-notification handling, empty queues, and reentrant callbacks deliver or suppress each event exactly once.
- Concurrent handler attachment cannot deadlock, lose, reorder, or duplicate notification under no-GIL execution.
- Moving/concurrent GC rewrites and roots the intrusive queue; Promise remains in its 256-byte allocation class; bounded-heap recovery and Context teardown remain exact.
- Private rejection dispatch, relevant threadfuzz, full units, and suppression-free TSan pass.
- Exact Promise Test262 coverage has zero regressions; documentation makes no unsupported throughput or OOM guarantee.
Security boundary
Rejection fanout and allocation pressure are script-controlled. The engine must fail closed without corrupting tracker state, retaining an unrooted managed pointer, or silently suppressing a host-visible event after recovery. The distinct Promise-to-microtask scheduling transaction remains tracked by #885.
Activity
chrisbbreuer commentedon Sep 5, 2026
Design audit update: the safer candidate is a reserve-before-commit transaction, not an intrusive Promise link.
Proposed lock/order proof:
realm_lock, reserve one physical FIFO slot fallibly, then takePromise.lock, revalidate that the Promise is still pending/unhandled, and commit settlement state +rejection_queued+appendAssumeCapacitybefore releasing either lock. Allocation failure occurs before any Promise state transition, leaving the Promise retryable and the queue unchanged.Promise.lockwithout mutating, release it, takerealm_lock, reserve one handled slot, reacquirePromise.lock, and revalidate. Only then setis_handled/rejection_handled_notifiedand publish withappendAssumeCapacity. Competing handlers converge because the recheck occurs under the canonicalrealm → Promiseorder already used by host drain/GC.An intrusive FIFO would remove allocation but add a managed link to every Promise, affect slab sizing, and require the concurrent marker to walk the entire chain before dequeue can clear links. That is unnecessary risk unless reservation proves insufficient. No implementation is being mixed into the currently running #875 revision.
chrisbbreuer commentedon Sep 5, 2026
A deeper call-site audit invalidated the reserve-before-commit candidate described above. Native resolving functions set their shared
promise_resolving_alreadybit before callingresolve/reject; therefore an OOM returned by a rejection-queue reservation could leave the Promise pending while its once-only capability is already spent. A later exact retry is not guaranteed, so “leave settlement pending on reservation failure” is not an atomic recovery design.The implementation is now using the issue’s allocation-free option:
realm_lock → Promise.lockpublication after a probe/revalidation, committing the tracker flag and queue root together with no allocator boundary;This simultaneously removes #874’s front-shift cost and #884’s fallible publication boundary. The full compile/runtime evidence is still pending behind the isolated #875 lifecycle sweep; acceptance boxes will be updated only after those gates pass.
chrisbbreuer commentedon Sep 5, 2026
Collector-boundary audit: the rejection FIFO and its Promise-state publication are allocation-free, but the generic GC insertion barrier is not yet an unconditional OOM proof. The owned
zig-gcimplementation can win a mark claim and then silently lose a falliblebarrier_buf/mark_stackappend; because the mark bit is already set, the terminal root rescan does not necessarily retrace that cell's outgoing graph.That collector-wide defect is now tracked explicitly in #888 with failing-allocator, abort-state, TSan, and full-GC acceptance. It is not being disguised as a Promise-specific workaround. For #884, the durable Context queue root and Promise tracker flags still commit together without a caller-visible allocator boundary; final acceptance will state the #888 dependency accurately rather than claiming the existing generic barrier is OOM-infallible.
docs(abi): reconcile the Home rejection tracker render manifest (#884)
chrisbbreuer commentedon Sep 8, 2026
The Home integration evidence now has a matching rendered manifest in 09279120 — docs(abi): reconcile the Home rejection tracker render manifest (#884).
The earlier source change in 4a1e5d8 added two intended sentences, but its manifest captured incomplete rendered bytes. Rendering the exact parent reproduces its checked 247,143-byte/hash entry; the current page differs only by those two sentences and matches Linux CI's 247,277-byte output. Regenerated with the pinned owner BunPress renderer; only that page entry and the tree hash changed. Checked docs:build and all 328 documentation links now pass. No new implementation/performance claim or manual generated-text edit; flips 0 test262 cases.
chrisbbreuer commentedon Sep 21, 2026
Closing as implemented and accepted.
The rejection tracker transaction and intrusive FIFO landed in
4a1e5d82; the Home render manifest was reconciled by09279120. Its collector dependency #888 is now implemented, accepted, and closed.Final evidence:
rejection tracker publication is allocation-free and state exact: 1/1 in Debug and 1/1 under TSan. The forced-failure allocator records zero allocation attempts for unhandled publication, repeated settlement, pre-handled rejection, and later-handled publication.rejection queue is wide allocation-free FIFO: 1/1 in Debug and 1/1 under TSan, including 4,096 queued Promises, empty transitions, clear/unlink, and reentrant suffix ordering.Promise fits the 256-byte GC slab: 1/1; the successor overlays the mutually exclusive awaiting slot and preserves the production allocation class.realm_lock, and relocation rewrites the endpoints plus each linked successor. Context teardown unlinks the queues while the precise heap is live.The implementation leaves fulfilled and already-handled fast paths free of the realm lock and contains no retry loop, emergency reserve, event cap, or fallible queue publication boundary.