Language: foreach by-reference — AOT lowering (phase 2 of #1222)

[PurHur]

Category

language

Problem

#1222 closed VM + JIT lowering for foreach ($arr as $k => &$v). docs/capabilities-syntax.md still marks AOT = no for foreach by-reference: native phpc build binaries fall back or abort when scripts use reference foreach on hot paths (bootstrap inventory warnings on lib/ patterns).

php-src reference

• php/php-src Zend/zend_execute.c — ZEND_FE_FETCH_R, reference fetch handlers
• php/php-src Zend/zend_compile.c — foreach with IS_VAR_REF value

Repro

Use existing compliance test/compliance/cases/language/foreach_by_ref*.phpt (or add foreach_by_ref_aot.phpt):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
./vendor/bin/phpunit --filter foreach_by_ref
# AOT: compile fixture and run native binary — must match Zend output
'

Today: VM/JIT green; AOT column no in capability matrix.

Scope (this repo)

Layer	Files
JIT/AOT	lib/JIT.php — reference foreach loop IR (mirror VM indirect cells)
AOT	lib/AOT/, runtime helpers for hashtable iterator + indirect write-back
Policy	lib/JIT/SelfHostBuiltinPolicy.php — remove AOT block if present
Tests	test/fixtures/aot/cases/foreach_by_ref.phpt
Docs	script/capability-syntax.php — flip AOT to yes when green

Done when

• AOT fixture foreach_by_ref.phpt passes in AotTest / ci-local llvm tail
• docs/capabilities-syntax.md foreach by-reference row: AOT = yes
• php script/bootstrap-inventory.php --check unchanged or improved (no new blockers)

Links

• Parent: Language: foreach by-reference ($k => &$v) #1222 (closed — VM/JIT)
• Related: by-ref params Language: Reference assignment and by-ref parameters #140, list refs feat(vm,jit): closure use(), try/finally VM, JIT closure IR (#72, #2114) #3081
• North star: #1492

[PurHur]

claim: cursor-agent-lane-c — starting this run

[PurHur]

Merged via PR #4367.

Verification: AOT packed + assoc foreach by-ref (246 / 23); vendor/bin/phpunit test/aot/AotTest.php --filter foreach_by_ref — OK (2 tests).

Changes: string-key ITER_VALID ordinal fix in IteratorHelper; borrowedValueEntry skips invalid valueDelref on merged ref pointers; AOT PHPT fixtures; capabilities-syntax AOT=yes.