PR Review: OTP-compatible maps helpers

Scope

Reviewed the following four commits as one change set (HEAD~4..HEAD):

• 6c712108a — maps: Add take, update_with, with, without
• 213ed8f16 — maps: Add filtermap, intersect, intersect_with, groups_from_list, is_iterator_valid
• 33c004c06 — maps:take/2 nif
• 7b34dfeee — maps: align helpers with OTP behavior

Files reviewed:

• libs/estdlib/src/maps.erl
• src/libAtomVM/nifs.c
• src/libAtomVM/nifs.gperf
• tests/libs/estdlib/test_maps.erl
• CHANGELOG.md

The Erlang behavior was compared with the BEAM source in /Users/petermm/OSScontrib/otp at OTP-29.0.3 (maint-29, commit 40ea544c97aa8492596f35a88286ea80326510ec), including invalid callback precedence, malformed iterators, ordered iterators, callback order, and groups_from_list/2,3 exception behavior. Oracle was also asked to independently review correctness, GC safety, malformed iterator handling, and OTP compatibility.

Verdict

Approve — no actionable correctness findings.

The implementation preserves the intended OTP behavior, and the native maps:take/2 implementation correctly roots and reloads terms across a potentially moving GC. The iterator NIF validates numeric positions and the complete ordered-key list before accessing map storage. Invalid iterator errors are translated to {badmap, OriginalIterator} without masking callback exceptions.

Findings

No blocking or non-blocking defects found.

Areas specifically checked

• maps:take/2 roots both arguments across GC, repeats the key lookup after GC, reserves enough heap for the copied map and result tuple, and handles allocation failures.
• maps:next/1 rejects negative and out-of-range numeric positions, improper ordered-key lists, and ordered iterators containing absent keys.
• filter/2, filtermap/2, fold/3, foreach/2, and map/2 preserve callback order for ordered iterators and only translate iterator badarg failures into badmap errors.
• intersect/2 and intersect_with/3 preserve the value and combiner argument ordering when the smaller map is the second input.
• update_with/3,4, with/2, and without/2 implement the tested OTP error precedence.
• groups_from_list/2,3 validates the full list before invoking callbacks and preserves callback exceptions from the try ... of body.

Applied test suggestion

Added explicit groups_from_list/2,3 regression tests confirming that exceptions from both key and value callbacks propagate unchanged rather than being converted to badarg. This protects the subtle try ... of exception boundary used by the OTP-compatible implementation.

Verification

• git diff --check HEAD~4..HEAD — passed.
• Full test_estdlib.avm archive on AtomVM — passed, including test_maps.
• Added callback-exception regression tests for groups_from_list/2,3 — passed on AtomVM.
• Source and differential edge-case checks against the local OTP 29.0.3 BEAM checkout — matched the intended behavior.
• Oracle review — no actionable findings; identified only unverified hardening/coverage risks, not defects.

The full estdlib run emits expected crash reports from tests that intentionally exercise process failure paths and skips unavailable platform facilities; it finishes with every listed test module, including test_maps, returning ok.