Docs: agent handover and AOT correctness inventory (2026-08-17)

[PurHur]

Two documents from a session that re-established ground truth on a tree 3,069 commits past the previous handover.

docs/AGENT-HANDOVER-2026-08-17.md

• The compiler could not produce a working binary. aot-smoke: 0 passed, 8 failed — every case failing at link with undefined reference to memset.1, because GcCollectCyclesRuntime::ensureExternal() called addFunction() without a getNamedFunction() check and LLVM emitted a body-less memset.1. Fixed in Fix: AOT link fails for EVERY binary — duplicate memset declaration #31894 (merged), 0/8 → 8/8.
• Two "separate" AOT defects were that same bug. var_dump aborting rc=134 and Exception::getMessage() segfaulting both now match Zend exactly.
• Why it went unnoticed. compiler-gate.yml had failed 19 of its last 20 master pushes, always in apply-patches.sh on a corrupt hunk header — so it never reached aot-smoke.sh, the one check that would have caught it. A gate permanently red for an irrelevant reason carries as much information as one permanently green. Partial fix in Fix corrupt hunk header that has been aborting the master gate for 19+ runs #31909.
• An explicit trap for whoever picks up the patch chain: the next failing patch has the same arithmetic inconsistency but a different cause. Correcting its header would look like a fix and verify nothing.
• What is verified vs what is not, kept deliberately separate.
• Operational notes: this is the production box; per-agent helper-cache dirs; never composer install against a tree agents are using; whole-corpus compliance stays manual.

docs/roadmap/AOT-CORRECTNESS-PLAN.md

85 probes across two language areas produced 44 mismatches — roughly one in two, on ordinary PHP.

Grouped by likely root cause rather than listed flat, because several crashes plausibly share one:

group	contents
1	float→string conversion — five crashes, incl. one that segfaults the compiler itself
2	integer overflow does not promote to float (silent wrong arithmetic)
3	static property storage — incl. a read of uninitialised memory returning an unstable integer
4	invalid emitted IR (module verification failures)
5	unimplemented lowering (honest errors, lower priority)
6	inherited property defaults (#31895) — verified

With a suggested order, and the confound stated precisely: the hunt ran at load 129–228 on 16 cores, which would invalidate a wall-clock timeout but not the deterministic signatures actually observed (exit 2/255 with specific compiler errors, SIGSEGV, SIGABRT). No hang findings were reported.

Provenance is marked throughout — only Group 6 was re-run by hand; the rest are probe-reported and say so.

Note

RELEASE-PLAN.md is left untouched and is stale: it still claims "P1.1 CI on lib/, ext/ — done, green on master", which was false for a long stretch. It should be corrected once the gate genuinely reports.

🤖 Generated with Claude Code