## Summary
Fixes a critical segmentation fault crash occurring during NAPI
finalizer cleanup when finalizers trigger GC operations. This crash was
reported with `node-sqlite3` and other NAPI modules during process exit.
## Root Cause
The crash was caused by **iterator invalidation** in
`napi_env__::cleanup()`:
1. Range-based for loop iterates over `m_finalizers`
(std::unordered_set)
2. `boundFinalizer.call(this)` executes finalizer callbacks
3. Finalizers can trigger JavaScript execution and GC operations
4. GC can add/remove entries from `m_finalizers` during iteration
5. **Iterator invalidation** → undefined behavior → segfault
## Solution
Added `JSC::DeferGCForAWhile deferGC(m_vm)` scope during entire
finalizer cleanup to prevent any GC operations from occurring during
iteration.
### Why This Approach?
- **Addresses root cause**: Prevents GC entirely during critical section
- **Simple & safe**: One-line RAII fix using existing JSC patterns
- **Minimal impact**: Only affects process cleanup (not runtime
performance)
- **Proven pattern**: Already used elsewhere in Bun's codebase
- **Better than alternatives**: Cleaner than Node.js manual iterator
approach
## Testing
Added comprehensive test (`test_finalizer_iterator_invalidation.c`) that
reproduces the crash by:
- Creating finalizers that trigger GC operations
- Forcing JavaScript execution during finalization
- Allocating objects that can trigger more GC
- Calling process exit to trigger finalizer cleanup
**Before fix**: Segmentation fault
**After fix**: Clean exit ✅
## Files Changed
- `src/bun.js/bindings/napi.h`: Core fix + include
- `test/napi/napi-app/test_finalizer_iterator_invalidation.c`: Test
addon
- `test/napi/napi-app/binding.gyp`: Build config for test addon
- `test/regression/issue/napi-finalizer-crash.test.ts`: Integration test
## Test Plan
- [x] Reproduces original crash without fix
- [x] Passes cleanly with fix applied
- [x] Existing NAPI tests continue to pass
- [x] Manual testing with node-sqlite3 scenarios
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Kai Tamkun <kai@tamkun.io>
0dc136149d
