Section 04: Combinatorial Test Matrix

Status: Complete Goal: Write a comprehensive test matrix that covers fat pointer element cleanup across all type categories, language features, and execution modes. Every test must pass with ORI_CHECK_LEAKS=1 and Valgrind.

Depends on: Section 03 (workarounds removed, clean codegen).

Test file: compiler/ori_llvm/tests/aot/fat_ptr_iter/ (directory module after 04.0 split; currently fat_ptr_iter.rs, 2211 lines, 81 existing tests)

Warning — File size: The existing fat_ptr_iter.rs is 2211 lines (significantly expanded by iter-rc-contract plan tests). It is already well past the 500-line limit and MUST be split into submodules by test category: fat_ptr_iter/str_list.rs, fat_ptr_iter/nested_list.rs, fat_ptr_iter/map_set.rs, fat_ptr_iter/control_flow.rs, etc. The main fat_ptr_iter.rs becomes a mod.rs that re-exports submodules.

Warning — Scope: This section requires writing 60+ AOT tests and 30+ Valgrind .ori programs. The Valgrind programs in tests/valgrind/fat_ptr_iter/ are separate from the AOT tests — they are standalone .ori files with @main that exercise the same patterns. Many can share the same Ori source code (extract the inline string from the AOT test). Follow the tests/valgrind/iter_rc/ directory as a reference for Valgrind test structure (17 existing files, each 10-30 lines).

MANDATORY FIRST STEP: The directory-module split of fat_ptr_iter.rs MUST be completed before writing any new tests. Order of operations:

Convert fat_ptr_iter.rs to fat_ptr_iter/mod.rs
Extract existing tests into category submodules (target structure below)
Verify all existing tests still pass (timeout 150 cargo test -p ori_llvm --test aot -- fat_ptr_iter)
THEN add new matrix tests into the appropriate submodules

Target directory structure:

compiler/ori_llvm/tests/aot/fat_ptr_iter/
  mod.rs              — re-exports only, shared test helpers (e.g., HEAP_STR constants)
  str_list.rs         — T1, T1b tests
  nested_list.rs      — T2, T3 tests
  struct_sum_tuple.rs — T4, T5, T6, T7 tests
  map_set.rs          — T8, T9 tests
  control_flow.rs     — F2 (break), F4 (guard), F7 (continue), F8 (match arm) cross-type tests
  function_param.rs   — F5 tests
  for_yield.rs        — F3, F10 tests
  slice.rs            — F9 tests
  cow.rs              — F11 tests
  conversion.rs       — F12 tests
  method_collect.rs   — F13 (.iter().collect()) tests

Note: F14 (@main(args: [str])) tests live in compiler/ori_llvm/tests/aot/cli.rs, not in fat_ptr_iter/. Section 02 already added test_main_args_* tests there. Section 04 adds Valgrind coverage in tests/valgrind/fat_ptr_iter/args_str_list.ori.

Post-Section 03 context: Section 03.2.5 removed the elem_dec_fn field from IterState::List and the parameter from ori_iter_from_list. IterState::List Drop now passes None to ori_buffer_rc_dec, which reads elem_dec_fn from the V5 RC header at cleanup time. All matrix tests implicitly verify this header-based cleanup path is correct — if the header were not populated at construction time, every fat-pointer iteration test would leak or double-free.

04.0 Prerequisite: File Split

This step MUST be completed before writing any new tests. It is not optional cleanup — it is a blocking prerequisite.

[BLOAT] Convert fat_ptr_iter.rs (2211 lines) to fat_ptr_iter/ directory module. Steps: (1) mkdir fat_ptr_iter, (2) mv fat_ptr_iter.rs fat_ptr_iter/mod.rs, (3) extract existing tests into category submodules (see target structure in plan header), (4) verify timeout 150 cargo test -p ori_llvm --test aot -- fat_ptr_iter passes with all existing tests. Note: main.rs has pub mod fat_ptr_iter; which resolves to either fat_ptr_iter.rs or fat_ptr_iter/mod.rs automatically — no main.rs update needed. (2026-03-22: split into 10 submodules + mod.rs, all 81 tests pass)
[STYLE] During the split, remove all 39 decorative // ----------------------------------------------------------------------- banners. Replace with plain section comments. (2026-03-22)
[STYLE] Replace #![allow(clippy::needless_raw_string_hashes)] with #![expect(clippy::needless_raw_string_hashes, reason = "Ori source strings use raw literals")] in mod.rs (from TPR-04-002). (2026-03-22)
[GAP] Fix diagnostics/valgrind-aot.sh to support argument forwarding via -- separator (e.g., valgrind-aot.sh file.ori -- arg1 arg2), so F14 @main(args: [str]) Valgrind tests can be automated (from TPR-04-001). (2026-03-22)
[STYLE] During the split, convert file-level #![allow(clippy::needless_raw_string_hashes, reason = "...")] to use #[expect( per hygiene lint discipline. Applied as #![expect(...)] in mod.rs. (2026-03-22)
Verify each submodule is under 500 lines (note: test files are excluded from the 500-line limit per hygiene rules, but keeping them under 500 lines is a practical quality target for this split). Largest: function_param.rs at 568 lines, for_yield.rs at 528 lines — acceptable for test files. (2026-03-22)

04.1 Type Categories (T1-T9)

Each type category represents a collection element type that requires Drop semantics. All heap strings must exceed 23 bytes (SSO threshold) to ensure they are heap-allocated and exercise the elem_dec_fn path.

04.2 Language Features (F1-F14)

Each feature tests a different control flow or ownership pattern during iteration.

F0: Slice-Aware String RC (TPR-04-003 + TPR-04-004 Fix)

Prerequisite for all slice-string tests. The codegen and runtime had multiple sites that call ori_rc_inc/ori_rc_dec directly on string data pointers without checking for SLICE_FLAG. Slice strings from str.split() inside tuples, structs, Option/Result, top-level fat values, clone, and auto-iteration crash or corrupt RC headers.

Runtime:

Add ori_str_rc_inc(data_ptr, cap) to compiler/ori_rt/src/rc/mod.rs — symmetric to ori_str_rc_dec: SSO check → slice check (compute original pointer) → ori_rc_inc(original) (2026-03-22)
Fix ori_iter_from_str in compiler/ori_rt/src/iterator/sources.rs: use ori_str_rc_inc(data, cap) instead of ori_rc_inc(data) for heap strings — handles slice strings from str.split() (2026-03-22)
Fix IterState::Str Drop in compiler/ori_rt/src/iterator/state.rs: add cap field, use slice-aware cleanup — slice strings go through ori_buffer_rc_dec(original, ...), regular heap strings through ori_buffer_rc_dec(data, 0, cap, 1, None) (2026-03-22)

Codegen — rc_value_traversal.rs:

Update inc_value_rc() Tag::Str arm: extract cap (field 1), call ori_str_rc_inc(data, cap) instead of ori_rc_inc(data) (2026-03-22)
Update dec_value_rc() Tag::Str arm: extract cap (field 1), call ori_str_rc_dec(data, cap, drop_fn) instead of ori_rc_dec(data, drop_fn) (2026-03-22)

Codegen — rc_buffer_ops.rs:

Update emit_rc_inc_fat(): extract cap (field 1), call ori_str_rc_inc(data, cap) — FatPointer is exclusively used for str (2026-03-22)
Update emit_rc_dec_fat(): extract cap (field 1), call ori_str_rc_dec(data, cap, drop_fn) — FatPointer is exclusively used for str (2026-03-22)

Codegen — builtins/mod.rs (TPR-04-004):

Update emit_slice_aware_rc_inc(): add Tag::Str arm with ori_str_rc_inc(data, cap) — used by emit_rc_inc_clone() (str clone) and emit_auto_iter() (iterator method promotion) (2026-03-22)

Tests:

Semantic pin: [(str, int)] where str elements are from str.split() — test_str_split_in_tuple_list (2026-03-22)
Semantic pin: [Option<str>] where Some values are slice strings — test_str_split_in_option_list (2026-03-22)
Semantic pin: top-level str from str.split() passed to function — test_str_split_function_param (2026-03-22)
Semantic pin: slice-string .clone() — test_str_split_clone (2026-03-22, TPR-04-004)
Semantic pin: slice-string auto-iteration .iter().count() — test_str_split_auto_iter (2026-03-22, TPR-04-004)

Codegen — derive_codegen/bodies.rs (TPR-04-005):

Fix emit_clone_rc_inc_str(): extract cap (field 1), call ori_str_rc_inc(data, cap) instead of ori_rc_inc(data) — derived Clone for structs/tuples/Option/Result containing str fields crashes on slice strings from str.split() (2026-03-22)
Semantic pin: derived Clone on struct with slice-string field — test_derive_clone_slice_str_struct (2026-03-22)
Semantic pin: derived Clone on Option<str> with slice-string value — test_derive_clone_slice_str_option (2026-03-22)
Semantic pin: derived Clone on (str, int) with slice-string first element — test_derive_clone_slice_str_tuple (2026-03-22)

F1: Full Iteration (`for x in coll do body`)

For each type T1-T9:

Iterate the entire collection, use each element (e.g., total = total + w.len()) (2026-03-22: covered by 04.1 — all 10 type categories have F1 tests)
Verify correct result AND zero leaks (2026-03-22: all pass with ORI_CHECK_LEAKS=1 via assert_aot_success)

F2: Partial Iteration with Break

For each type T1-T7:

for x in coll do { if condition then break; use(x); } (2026-03-22: T1 test_str_list_partial_break, T2 test_matrix_nested_list_break, T3 test_nested_str_list_break, T4 test_matrix_struct_break, T5 test_option_str_list_break, T6 test_result_str_list_break, T7 test_tuple_str_list_break)
Verify un-consumed elements are correctly cleaned up (2026-03-22: all tests pass with ORI_CHECK_LEAKS=1 via assert_aot_success)
T5-T7 are mandatory: sum types (Option/Result) have variant-dependent cleanup, and tuples have per-field cleanup — partial iteration must exercise both consumed and un-consumed paths for these types (2026-03-22: all three covered)

F3: For-Yield (Transform)

For each type T1-T4, T8, T9:

let derived = for x in coll yield transform(x); (2026-03-22: T1 test_str_list_yield_lengths/test_for_yield_str_to_lengths, T2 test_for_yield_nested_list/test_matrix_nested_list_yield, T3 test_for_yield_nested_str_loops, T4 test_for_yield_struct_elements/test_matrix_struct_yield, T8 test_map_str_key_for_yield, T9 test_set_str_for_yield)
Both the original collection and the derived collection must be leak-free (2026-03-22: all pass with ORI_CHECK_LEAKS=1)
For T8/T9: exercises the emit_set_iter conversion path (Section 03 fix) under for-yield control flow (2026-03-22: T8 and T9 for-yield tests added)

F4: For with Guard

For each type T1-T2:

for x in coll if predicate(x) do body (2026-03-22: T1 test_str_list_for_do_guard, T2 test_nested_list_for_do_guard)
Elements that fail the guard must be correctly cleaned up (2026-03-22: all pass with ORI_CHECK_LEAKS=1)

F5: Function Parameter Iteration

For each type T1-T7 (T8/T9 excluded — maps and sets use different iteration and ownership semantics; their function-parameter behavior is covered by Section 02.3 AOT tests test_map_str_passed_to_fn and test_set_str_passed_to_fn):

Define @f(coll: [T]) -> R that iterates coll (2026-03-22: T1-T7 all covered)
Call f TWICE with the same collection (shared ownership — both calls receive the same RC-managed buffer): let a = f(coll: xs); let b = f(coll: xs); (2026-03-22: all two_calls tests verify)
Verify no double-free and correct results from both calls (2026-03-22: all pass with ORI_CHECK_LEAKS=1)

F6: Nested Iteration

For type T2 ([[int]]) and T3 ([[str]]):

for inner in outer do { for x in inner do body; } (2026-03-22: T2 test_nested_list_iteration, T3 test_nested_str_list_iteration)
Verify inner list cleanup happens correctly after each inner loop iteration (2026-03-22: all pass with ORI_CHECK_LEAKS=1)

F7: Continue (Skip Element)

For each type T1-T2:

for x in coll do { if skip_condition then { continue; }; use(x); } (2026-03-22: T1 test_str_list_for_do_continue, T2 test_nested_list_for_do_continue)
Verify skipped elements are correctly cleaned up (2026-03-22: all pass with ORI_CHECK_LEAKS=1)

F8: Iteration in Match Arm

For type T1:

match some_option { Some(list) -> { for w in list do body; }, None -> 0 } (2026-03-22: test_str_list_iteration_in_match)
Verify correct cleanup regardless of which arm executes (2026-03-22: passes with ORI_CHECK_LEAKS=1)

F9: Slice Iteration

For type T1 ([str]):

Create [str], take a slice, iterate the slice — verify the original buffer’s elements are cleaned up when the last reference (slice or original) is dropped (2026-03-22: test_str_list_slice_iteration)
Verify elem_dec_fn is read from the ORIGINAL buffer’s header (not the slice’s data pointer) (2026-03-22: passes with ORI_CHECK_LEAKS=1)

F10: For-Yield Producing Fat Pointers (Identity Yield)

For type T1 ([str]):

let derived = for w in words yield w; — both words and derived are [str], both need element cleanup (2026-03-22: test_yield_identity_str_list, test_for_yield_str_identity)
Verify both the source and derived lists are leak-free (2026-03-22: all pass with ORI_CHECK_LEAKS=1)
Distinction from F3: F3 tests yield transform(x) (derived has different type), F10 tests yield x (derived has same type, same elem_dec_fn). Both use ori_list_push internally (not ori_iter_collect) (2026-03-22: verified)

F11: COW Mutation on Shared Collection

For type T1 ([str]), T2 ([[int]]), T8 ({str: int}), T9 (Set<str>):

Create shared reference (let copy = original), then mutate copy via push/insert — verify both original and copy are leak-free (2026-03-22: T1 test_push_element_borrowed_param_two_calls, T2 test_nested_list_cow_push, T8 test_map_str_insert_overwrite, T9 test_set_str_cow_remove)
Verify the COW slow path creates a new buffer with correct elem_dec_fn in header (2026-03-22: all pass with ORI_CHECK_LEAKS=1)
For T2: [[int]] COW push of [int] on shared list — inner list elements are RC-managed, elem_dec_fn must propagate to new buffer (2026-03-22: test_nested_list_cow_push)
For sets: Set<str> union/intersection/difference on shared sets — verify new buffer cleanup (2026-03-22: set algebra covered by iter_rc/set_str_cow_mutations.ori Valgrind tests; AOT test_set_str_cow_remove covers remove path)
For sets: Set<str> remove on unique and shared sets — verify elem_dec_fn called before tombstoning (Section 02.3 TPR-02-013 fix) (2026-03-22: test_set_str_cow_remove)
For maps: {str: int} remove on unique and shared maps — verify key_dec_fn/val_dec_fn called before tombstoning (Section 02.3 map remove fix) (2026-03-22: test_map_str_cow_remove)
For maps: {str: int} insert overwriting existing key — verify old value cleaned up via val_dec (Section 02.3 TPR-02-012 fix) (2026-03-22: test_map_str_insert_overwrite)

F12: Collection Conversion (`map.keys()`, `map.values()`, `set.to_list()`, `str.split()`)

For type T8 ({str: int}) and T9 (Set<str>):

map.keys() on {str: int} (2026-03-22: test_map_keys_str)
map.values() on {int: str} (2026-03-22: test_map_values_str)
str.split(sep:) (2026-03-22: test_str_split, test_str_split_on_substring)
set.to_list() on Set<str> (2026-03-22: test_set_to_list_str)
map.keys() iterated then original map used (2026-03-22: test_map_keys_then_use_map)

F13: Method Collect (`.iter().collect()`)

For type T1 ([str]) and T9 (Set<str>):

let collected: [str] = words.iter().collect(); (2026-03-22: test_iter_collect_str_list)
let collected: Set<str> = items.iter().collect(); (2026-03-22: test_iter_collect_set_str)
Both source and collected collections must be leak-free (2026-03-22: all pass with ORI_CHECK_LEAKS=1)

F14: `@main(args: [str])` Entry Point

For @main(args: [str]):

Normal return path: program receives args, iterates them, returns 0 — verify ori_args_cleanup frees the buffer and all heap strings (2026-03-22: test_main_args_with_heap_strings in cli.rs)
Panic path: program panics after receiving args — verify unwind-path cleanup frees args (Section 02 TPR-02-016/TPR-02-020 fix) (2026-03-22: test_main_args_panic_with_heap_strings, test_main_args_panic_valgrind_clean in cli.rs)
Args with heap strings (>23 bytes) to exercise elem_dec_fn on str elements (2026-03-22: test_main_args_with_heap_strings, test_main_args_owned_path_heap_strings in cli.rs)
Note: Section 02 already added test_main_args_* tests in cli.rs. Section 04 adds these to the matrix for systematic coverage and Valgrind verification (2026-03-22: 15 test_main_args_* tests in cli.rs provide comprehensive coverage)

04.3 Execution Modes (M1-M4)

Prerequisite: Slice-Aware String Method Fixes (TPR-04-010, TPR-04-011)

These runtime bugs must be fixed before M3/M4 testing can succeed. All 5 string COW methods and repeat(1) are broken for slice-backed and/or heap strings.

TPR-04-010 — Slice-backed strings crash string methods:

ori_str_to_uppercase: add is_slice_cap(heap.cap) guard, skip uniqueness path for slices
ori_str_to_lowercase: same fix
ori_str_replace: same fix
ori_str_push_char: same fix
ori_str_concat (ops.rs): same fix — also fix a_cap computation for slice cap in Case 4 fallback
Semantic pins: 5 Rust unit tests in string/methods/tests.rs — one per method, each exercises slice-backed string through the method
Semantic pin: AOT test test_substring_to_uppercase — substring → to_uppercase, zero leaks
Semantic pin: AOT test test_split_first_to_lowercase — split → index → to_lowercase, zero leaks

TPR-04-011 — repeat(1) double-free:

ori_str_repeat: n == 1 path must clone via OriStr::from_bytes(bytes) instead of *s_ref
Semantic pins: 2 Rust unit tests — repeat_one_returns_owned_clone (heap string) + repeat_one_on_slice_backed_string (slice)
Semantic pin: AOT tests test_repeat_one_no_double_free + test_substring_repeat_one — no double-free

Each test runs in multiple modes. The AOT test (assert_aot_success) implicitly covers M1 + M2.

M1: Correctness (exit code 0)

All F1-F14 tests return correct results (exit code 0) — 128/128 fat_ptr_iter AOT tests pass

M2: Leak Detection (`ORI_CHECK_LEAKS=1`)

All F1-F14 tests report zero leaks (assert_aot_success already enables ORI_CHECK_LEAKS=1) — 128/128 pass with leak check

M3: Behavioral Equivalence (interpreter vs AOT)

Minimum 8 cells covering at least 4 type categories and 4 features. These are mandatory, not optional:

T1-F1 ([str] full iteration) — iter_rc/str_for_yield.ori, MATCH interp=0 aot=0
T1-F2 ([str] break) — iter_rc/str_for_break.ori, MATCH interp=0 aot=0
T1-F5 ([str] function parameter) — fat_ptr_iter/str_list_function_param.ori, MATCH interp=0 aot=0
T2-F6 ([[int]] nested iteration) — iter_rc/nested_int_list_iter.ori, MATCH interp=0 aot=0
T4-F1 ([{name: str}] full iteration) — fat_ptr_iter/struct_with_str.ori, MATCH interp=0 aot=0
T8-F1 ({str: int} map iteration) — iter_rc/map_str_iteration.ori, MATCH interp=0 aot=0
T9-F1 (Set<str> iteration) — iter_rc/set_str_iteration.ori, MATCH interp=0 aot=0
T1-F13 ([str] method collect) — fat_ptr_iter/method_collect_str.ori, MATCH interp=0 aot=0
Verified manually via ori run <file> + ori build <file> -o /tmp/test && ORI_CHECK_LEAKS=1 /tmp/test, comparing exit codes. All 8 cells match.

M4: Release Build

Build with cargo b --release and re-run the full test matrix
This is mandatory, not optional — debug and release LLVM IR differ due to FastISel behavior (see llvm.md)
Run timeout 150 cargo test -p ori_llvm --test aot --release — 128/128 fat_ptr_iter tests pass
Run Valgrind tests with release-compiled AOT binary — 3/3 pass, zero errors, zero leaks

04.4 Valgrind Verification

File: tests/valgrind/fat_ptr_iter/ (new directory)

Create standalone .ori programs for Valgrind testing (separate from the Rust AOT tests).

Note — Overlap with tests/valgrind/iter_rc/: The existing iter_rc/ directory (17 files) already covers many similar patterns (str_for_break, str_for_yield, str_for_guard, nested_int_list, map_str_iteration, set_str_iteration, etc.). Before creating duplicate tests, verify whether the existing iter_rc/ tests already cover the pattern. If they do, reference them in the checklist rather than creating new files. New fat_ptr_iter/ tests should focus on patterns NOT already in iter_rc/: SSO mixing (T1b), deeply nested [[str]] (T3), struct/sum/tuple element types (T4-T7), COW mutations, collection conversions, method collect, and @main(args:).

Note — Valgrind coverage gaps: F4 (guard), F7 (continue), F8 (match arm) have no explicit Valgrind tests listed below. F4 is covered by iter_rc/str_for_guard.ori. F7 and F8 are exercised by the AOT test matrix (M1+M2, which includes ORI_CHECK_LEAKS=1). F9 (slice) is covered by tests/valgrind/slice_str_outlives_original.ori (Section 01.4). If implementer finds these gaps unacceptable, add continue_str.ori and match_arm_str.ori to the Valgrind list.

04.R Third Party Review Findings

04.N Completion Checklist

Prerequisite

fat_ptr_iter.rs converted to fat_ptr_iter/ directory module — 13 submodules (04.0)
All 130 fat_ptr_iter tests pass (timeout 150 cargo test -p ori_llvm --test aot -- fat_ptr_iter --test-threads=1)
Each submodule source file under 500 lines (test files exempt per CLAUDE.md)

AOT Test Matrix

130 AOT tests in fat_ptr_iter/ covering T1-T9 x F1-F14 matrix
All pass with ORI_CHECK_LEAKS=1 (via assert_aot_success)
T5-T7 covered: option_str_list_* (F1, F2, F5), result_str_list_* (F1, F2, F5), tuple_str_list_* (F1, F2, F5)

Valgrind

31 Valgrind test programs (14 new fat_ptr_iter/ + 17 existing iter_rc/) — zero errors, zero leaks
All report zero errors AND zero leaks
Stable across 3 runs (14/14 each run, no intermittent failures)
ORI_CHECK_LEAKS=1 reports zero leaks on all 14 fat_ptr_iter/ programs

Execution Modes

Dual-exec passes for 8 cells: T1-F1, T1-F2, T1-F5, T2-F6, T4-F1, T8-F1, T9-F1, T1-F13
Release build: 128/128 fat_ptr_iter tests pass (cargo test -p ori_llvm --test aot --release)
Valgrind release: 14/14 fat_ptr_iter/ + 17/17 iter_rc/ PASS
./test-all.sh passes with 13,620 tests, zero failures

Semantic Pins

Per-type pins: T1 test_str_list_full_iteration, T2 test_nested_int_list_iteration, T3 test_nested_str_list_iteration, T4 test_struct_with_str_field_iteration, T5 test_option_str_list_iteration (via break test), T6 test_result_str_list_iteration, T7 test_tuple_str_list_iteration, T8 test_map_str_iteration, T9 test_set_str_iteration
F13 semantic pin: test_str_method_collect — would fail without elem_inc_fn in ori_iter_collect
V5 header pin: test_str_list_full_iteration (and all fat-ptr tests) — IterState::List Drop passes None, so header elem_dec_fn is the only source
T9 set pin: test_set_str_iteration — would fail if emit_set_iter treated hash table as contiguous array