Historical Note: The __for_coll phantom binding mechanism described in this plan was removed by the rc-header-elem-dec plan (2026-03-22) and replaced with header-based element cleanup via elem_dec_fn in the V5 RC header. References to __for_coll below are historical.

Section 02: Fix Iterator elem_dec_fn (List, Map, Set)

Status: In Progress Goal: Pass the correct elem_dec_fn (generated by get_or_generate_elem_dec_fn(elem_ty)) to ori_iter_from_list() in emit_list_iter(), and pass the correct key_dec_fn/val_dec_fn to ori_iter_from_map() in emit_map_iter(), so that ANY path that calls ori_buffer_rc_dec or ori_map_buffer_rc_dec on the collection buffer — whether ori_iter_drop, the AIMS-emitted explicit RcDec, or any future path — correctly cleans up element-level RC children.

Context: This is a codegen-only change. The function get_or_generate_elem_dec_fn() already exists in compiler/ori_llvm/src/codegen/arc_emitter/element_fn_gen.rs and is used by other collection operations (e.g., emit_list_rc_dec, emit_cow_*). The fix is to call it in emit_list_iter() and emit_map_iter() instead of passing NULL. Sets are automatically covered because emit_auto_iter() routes TypeInfo::Set through emit_list_iter() (builtins/mod.rs:371). This section can be landed independently of Section 03 (for-yield RC scoping).

Design principle: The elem_dec_fn argument to ori_iter_from_list must ALWAYS be the real per-element drop function. The previous design assumed the AIMS-emitted explicit RcDec would always be the final dec (and that dec carried the real elem_dec_fn). This assumption is wrong — ori_iter_drop may be the final dec in for-yield, drop_early(), cross-function iterator passing, and iterator adapter chains.

02.1 Codegen Fix: Pass Real elem_dec_fn in emit_list_iter

File(s): compiler/ori_llvm/src/codegen/arc_emitter/builtins/collections/list_builtins.rs (emit_list_iter, line 115-140), compiler/ori_llvm/src/codegen/arc_emitter/element_fn_gen.rs (get_or_generate_elem_dec_fn)

The specific code change in emit_list_iter():

Before (NULL):

let elem_dec_fn = self.builder.const_null_ptr();

After (real function):

let elem_dec_fn = self.get_or_generate_elem_dec_fn(elem_ty);

This is already implemented in the current code (the fix was applied as part of the analysis). The task is to verify it is correct for all element types and add comprehensive tests.

get_or_generate_elem_dec_fn(elem_ty) checks scalarity first, then generates a generic dec body:

Scalar (int, float, bool, char, byte, void): returns NULL (const_null_ptr()) — no element cleanup needed. Uses classifier.is_scalar() check.
Non-scalar (str, [T], closures, structs, Option, Result, etc.): generates (or retrieves from elem_dec_fn_cache) a function named _ori_elem_dec$<type_idx> with signature void (ptr %elem). The body loads the element from the pointer and calls dec_value_rc(elem_val, element_type), which dispatches internally based on the type’s structure. For str, this decrements the heap data pointer’s RC; for structs, it decrements each RC-carrying field; for enums (Option, Result), it tag-switches and decrements the appropriate variant payload.
Verify emit_list_iter() calls self.get_or_generate_elem_dec_fn(elem_ty) instead of passing NULL — confirmed at list_builtins.rs:145 (2026-03-18)
Verify get_or_generate_elem_dec_fn returns a valid function pointer for each element type in the Section 05 test matrix: str, [int], Option, (int)->int, {name: str} — verified via LLVM IR: @"_ori_elem_dec$3" for str, null for int (2026-03-18)
Add an AOT test: [str] for-yield collects correctly with ORI_CHECK_LEAKS=1 reporting zero leaks — test_for_yield_str_identity + test_for_yield_str_to_lengths (2026-03-18)
Add an AOT test: [[int]] for-yield collects correctly with ORI_CHECK_LEAKS=1 reporting zero leaks — test_for_yield_nested_list (2026-03-18)
Add an AOT test: [Option<str>] for-yield collects correctly with ORI_CHECK_LEAKS=1 reporting zero leaks — test_for_yield_option_str (2026-03-18)
Verify LLVM IR: ori_iter_from_list call has non-null 5th argument for [str] — ptr @"_ori_elem_dec$3" confirmed (2026-03-18)
Verify LLVM IR: ori_iter_from_list call has null 5th argument for [int] — ptr null confirmed (2026-03-18)

02.2 Element Type Coverage Verification

File(s): compiler/ori_llvm/src/codegen/arc_emitter/element_fn_gen.rs

Verify that get_or_generate_elem_dec_fn() produces correct drop functions for every element type in the test matrix. For each type, the generated function must match the element’s layout and cleanup requirements.

Element Type	Expected elem_dec_fn Behavior
`int`	NULL (no cleanup) — `is_scalar()` returns true
`str`	`_ori_elem_dec$<idx>` — calls `dec_value_rc` which decs heap data pointer RC (SSO strings have no heap data, no-op)
`[int]`	`_ori_elem_dec$<idx>` — calls `ori_buffer_rc_dec(data, len, cap, elem_size=8, NULL)` on nested list
`[str]`	`_ori_elem_dec$<idx>` — calls `ori_buffer_rc_dec(data, len, cap, elem_size=24, str_elem_dec)` on nested list
`Option<str>`	`_ori_elem_dec$<idx>` — tag switch: tag==0 (Some) -> dec str payload’s heap data; tag==1 (None) -> no-op
`(int) -> int`	`_ori_elem_dec$<idx>` — calls `ori_rc_dec` on closure env pointer (field 1, not field 0 which is fn_ptr)
`{name: str}`	`_ori_elem_dec$<idx>` — generated struct dec: decs `name` field’s heap data RC
`{K: V}` map	Uses `key_dec_fn`/`val_dec_fn` via `ori_iter_from_map` (NOT `elem_dec_fn`). After Section 02.3: real dec fns from `get_or_generate_elem_dec_fn(key_ty/val_ty)`
`Set<T>`	Same as `[T]` — `emit_auto_iter` routes `TypeInfo::Set` through `emit_list_iter`, so the list `elem_dec_fn` fix covers sets automatically

Trace get_or_generate_elem_dec_fn for each element type in the table above and verify the generated LLVM function body matches the expected behavior — verified str (@"_ori_elem_dec$3"), int (null), [int] (null inner), Option<str> (generated) via LLVM IR dump (2026-03-18)
Add IR-level test: [str] iterator’s elem_dec_fn argument is _ori_elem_dec$<idx> — verified: ptr @"_ori_elem_dec$3" in IR (2026-03-18)
Add IR-level test: [int] iterator’s elem_dec_fn argument is null — verified: ptr null in IR (2026-03-18)
Add IR-level test: [Option<str>] iterator’s elem_dec_fn is a function — verified via AOT test test_for_yield_option_str passing (generated dec fn handles tag-switch) (2026-03-18)
Verify closure element dec loads and decs field 1 (env_ptr), not field 0 (fn_ptr) — deferred: closure list iteration not yet tested in AOT (requires closure-in-list support). get_or_generate_elem_dec_fn calls dec_value_rc which delegates to the type’s DropKind.ClosureEnv handler for field 1 (2026-03-18)
Verify struct element dec iterates all RC-carrying fields, not just field 0 — verified: dec_value_rc dispatches to DropKind.Struct which iterates all drop-requiring fields (2026-03-18)

02.3 Map Iterator: Pass Real key_dec_fn / val_dec_fn

File(s): compiler/ori_llvm/src/codegen/arc_emitter/builtins/collections/map_builtins.rs (emit_map_iter, lines 328-360)

Bug: emit_map_iter() passes const_null_ptr() for both key_dec_fn and val_dec_fn (lines 343-344). This is the exact same root cause as the list elem_dec_fn NULL bug. IterState::Map::Drop calls ori_map_buffer_rc_dec() with these NULLs, so when the map iterator’s Drop is the final dec, key/value cleanup is skipped.

Additional issue: The __for_coll phantom in loops.rs:174 only matches List | Set, NOT Map. Maps have NO ordering workaround today. This means maps with str keys are either silently leaking or getting lucky on dec ordering.

Fix: Replace NULL with real dec functions:

// Before:
let key_dec_fn = self.builder.const_null_ptr();
let val_dec_fn = self.builder.const_null_ptr();

// After:
let key_dec_fn = self.get_or_generate_elem_dec_fn(key_ty);
let val_dec_fn = self.get_or_generate_elem_dec_fn(val_ty);

Cleanup: Remove the dead code marker let _ = (key_ty, val_ty); at line 342 and update the doc comment (lines 325-327) to explain the correct ownership contract.

Replace NULL key_dec_fn with self.get_or_generate_elem_dec_fn(key_ty) in emit_map_iter() — applied at map_builtins.rs:349 (2026-03-18)
Replace NULL val_dec_fn with self.get_or_generate_elem_dec_fn(val_ty) in emit_map_iter() — applied at map_builtins.rs:350 (2026-03-18)
Remove let _ = (key_ty, val_ty); dead code marker — removed, key_ty/val_ty now used by get_or_generate_elem_dec_fn() (2026-03-18)
Rewrite doc comment on emit_map_iter() to explain real dec fns and collect_iter_element_defs() transitive propagation (2026-03-18)
Add AOT test: {str: int} map for-do iteration with zero leaks — test_map_str_key_for_do_full + test_map_str_key_for_do_break (2026-03-18)
Add AOT test: {int: str} map for-do iteration with zero leaks — test_map_str_val_for_do (2026-03-18)
Add AOT test: {str: str} map for-do iteration with zero leaks — test_map_str_key_str_val_for_do (2026-03-18)
Verify LLVM IR: ori_iter_from_map call has non-null key_dec_fn and null val_dec_fn for {str: int} — confirmed: ptr @"_ori_elem_dec$3" / ptr null (2026-03-18)

Prerequisite fix: collect_iter_element_defs() in helpers.rs extended with Phase 2.5 — transitive Project chain propagation. This marks destructured (k, v) from map tuples as borrowed, so AIMS skips RcDec on them, preventing double-free when real dec fns are passed.

02.4 Backward Compatibility with For-Do __for_coll

File(s): compiler/ori_arc/src/lower/control_flow/loops.rs (__for_coll phantom), compiler/ori_arc/src/lower/control_flow/for_loops/for_iterator.rs (exit block dummy reference)

With the real elem_dec_fn now passed to ori_iter_from_list, the for-do __for_coll phantom mechanism still works correctly. Previously, the phantom ensured the AIMS-emitted explicit RcDec (which carried the real elem_dec_fn from the RcDec instruction’s drop info) was the final dec. Now, both the iterator’s drop AND the AIMS dec carry the real elem_dec_fn. The ordering still matters for correctness:

Scenario: for-do on [str] with 3 elements.

alloc: list_data [rc=1]
rc_inc: list_data [rc=2]       # emit_list_iter gives iterator its ref
ori_iter_from_list(data, elem_dec_fn=str_dec)  # NOW passes real func
... 3x iter_next ...
ori_iter_drop -> ori_buffer_rc_dec(data, ..., str_dec)  # rc=2->1
  # CRITICAL: When rc goes from 2->1, elem_dec_fn does NOT run --
  # drop_elements_and_free only runs when rc reaches 0.
  # So rc=2->1 is just a dec, no cleanup. Correct.
RcDec(list_data) via AIMS      # rc=1->0, str_dec runs per element, buffer freed

The __for_coll phantom ensures the AIMS RcDec comes AFTER ori_iter_drop. With the real elem_dec_fn on both paths, whichever dec reaches zero will correctly clean up elements. The phantom ordering is no longer load-bearing for correctness — it is now a safety net, not the primary mechanism.

Run existing for-do tests with [str] elements — all pass (12,987 total, 0 failures) (2026-03-18)
Run existing for-do tests with [[int]] elements — all pass (2026-03-18)
Run ORI_TRACE_RC=1 on a for-do [str] program — RC trace balanced: 1 alloc, 2 incs (iterator + __for_coll phantom), 3 decs, 1 free. Extra inc/dec from __for_coll phantom is correct. (2026-03-18)
Verify __for_coll AIMS ordering via ARC IR dump — RcDec on map/list comes after ori_iter_drop in exit block. For maps: AIMS dec is at bb3, ori_iter_drop follows. (2026-03-18)
Run timeout 150 ./test-all.sh — 12,987 pass, 0 fail (2026-03-18)

02.R Third Party Review Findings

[TPR-02-001][high] compiler/ori_llvm/tests/aot/fat_ptr_iter.rs:1494 — Section 02 is marked complete while the section-owned [[int]] two-call regression remains ignored and still double-frees when enabled. Resolved: Validated on 2026-03-18. The fix in commit 55e292ad (pass real key_dec_fn/val_dec_fn to map iterator + transitive Project propagation) resolved the double-free. Test test_matrix_nested_list_two_calls now passes — #[ignore] removed. RC trace shows balanced alloc/free for all 4 allocations.
[TPR-02-002][high] compiler/ori_arc/src/lower/control_flow/for_yield.rs:330 — The new Section 03 workaround clears mutable tracking before lowering the for-yield body, which breaks assignment to outer mutable variables in AOT. Resolved: Accepted and integrated into Section 03 on 2026-03-18. Added regression test task (outer mutable mutation in for-yield) and fix task (replace clear_mutable_names() with proper mutable-variable threading) to Section 03.2 and 03.4. The clear_mutable_names() workaround is the Section 03 bug to fix, not a Section 02 concern — Section 02’s elem_dec_fn changes are correct independently.
[TPR-02-003][medium] plans/iter-rc-contract/section-02-elem-dec-fn.md:31 — The section still describes itself as a codegen-only change that can land independently of Section 03, but the current implementation and passing evidence now depend on untracked Section 03 work. Resolved: Accepted on 2026-03-18. Updated Section 03 status to in-progress to reflect partial work already done (clear_mutable_names() workaround, dead_cleanup.rs changes). Recorded the exact files modified in Section 03’s context.
[TPR-02-004][low] plans/iter-rc-contract/section-02-elem-dec-fn.md:156 — The recorded timeout 150 ./test-all.sh “green” evidence is not currently reproducible from this workspace. Resolved: Accepted on 2026-03-18. The test suite itself passed (12,989 pass / 0 fail), but test-all.sh exit code was 1 due to WASM playground step (missing sibling repo) and summary parsing errors. The Section 02 fixes are not affected — narrowed evidence claim to workspace-local suites only.
[TPR-02-005][minor] compiler/ori_arc/src/aims/emit_rc/arg_ownership.rs:93 — Monomorphization name separator ”$m$” is an inline string literal. Source of truth is compiler/ori_llvm/src/monomorphize/mod.rs:124. If the separator changes in one location without the other, monomorphized functions would fail ownership annotation, causing either leaked references (over-conservative RC) or use-after-free (under-conservative RC). Resolved: Fixed on 2026-03-19. Extracted MONO_SEPARATOR constant to ori_ir/src/lib.rs. Both ori_llvm/monomorphize/mod.rs and ori_arc/aims/emit_rc/arg_ownership.rs now use ori_ir::MONO_SEPARATOR.

02.N Completion Checklist

Section 02 Exit Criteria

emit_list_iter() passes the real elem_dec_fn for all element types. emit_map_iter() passes real key_dec_fn/val_dec_fn for all key/value types. Sets are covered by the emit_list_iter fix (shared code path). AOT tests verify correct element cleanup for str, nested list, Option, and map str-key elements. All existing for-do tests pass unchanged, confirming backward compatibility with the __for_coll phantom mechanism.