🗺️ ROADMAP: Self-host + web-capable PHP subset (living)

[PurHur]

Living ROADMAP (high-signal, phased)

Merge gates are local/Docker only — no GitHub Actions (#394 ✅).
Harness-safe: make test-harness, ./script/docker-ci-local.sh, ./script/docker-exec.sh.

North star: #1492 (M3→M5 self-host)

Development focus (Jul 2026): optimize for fast M5 feedback — not north-star5-verify --strict on every PR (~1h). Daily gates: make north-star5-verify-fast (~1–2 min), make bootstrap-selfhost-vm-driver-execute-probe (~20ms). Reserve --strict for pre-merge bootstrap/gen-0/vendor-prelink PRs. Doc: docs/bootstrap-m5-fast-path.md · Cursor rule: .cursor/rules/m5-fast-development.mdc.

---

User release roadmap (next: v1.1.0)

Meta: #8739 (reopen on tag day) · Latest tag: v1.0.0 (2026-05-29) · Pre-release: v1.1.0-dev.1 (2026-07-04)

Field	Value
Target version	v1.1.0
Target window	Jul 2026 (after --full readiness green)
Theme	M5 fast-path stability for users; stdlib/JIT parity batch since v1.0.0 (enum, property hooks, DOM ext, preg_match JIT, spl_autoload, php-in-php helpers, stream/getenv JIT, docs sync)

Must-ship checklist

• #8737 — ship release-readiness.sh user-release gate presenter
• #8738 — fix php-types-never-type.patch on fresh vendor/ install
• #9066 — fix check-selfhost-spine-coverage-sync gate ✅ (regressed → Release v1.1.0: fix spine-coverage regression — GeneratorYieldSourceMarker.php missing from spine #10367 → closed)
• #9931 — fix php-cfg-new-first-class-callable.patch ✅ (2026-06-20)
• #10367 — spine: add GeneratorYieldSourceMarker.php ✅ (2026-06-20)
• #10368 — regenerate stale docs/bootstrap-inventory.md ✅ (2026-06-22)
• #10542 — spine: add NestedJitCompileScope.php ✅ (2026-06-22)
• #11205 — regenerate docs/capabilities.md ✅ (2026-06-24)
• #11206 — fix examples 000–009 AOT smoke ✅ (2026-06-24; regressed → Release v1.1.0: fix examples 000–009 AOT smoke regression (001-SimpleWeb munmap_chunk) #12039)
• #11565 — spine: add IniIntrospectionRuntime.php ✅ (2026-06-25)
• #12039 — fix examples 000–009 AOT smoke ✅ (2026-06-26)
• #12040 — fix examples web smoke ✅ (2026-06-26)
• #12564 — spine: sync array_intersect_key/diff_key/diff_assoc JIT runtimes ✅ (2026-06-27)
• #13101 — vm-driver-probe after north-star5-fast ✅ (2026-06-29, PR Fix vm-driver-probe fallback when prelinked gen-0 seed fails (#13101) #13110)
• #13571 — fix examples 000–009 AOT smoke (exit 139 on 000-HelloWorld; regressed from Release v1.1.0: fix examples 000–009 AOT smoke regression (001-SimpleWeb munmap_chunk) #12039) ✅ (closed 2026-06-29)
• #13995 — fix examples 000–009 AOT smoke (001-SimpleWeb exit 134 munmap_chunk(): invalid pointer) ✅ (closed; CallArgv/nested-JIT fixes Bootstrap: CallArgv LLVM global leaks across JIT Context — bootstrap-aot-link segfault (#197) #14459–Defer nested-JIT standalone init for bootstrap AOT compile (#14472) #14480)
• #14484 — spine: add ext/dom/NodeHasAttributes.php ✅ (2026-07-01)
• #15415 — fix corrupt php-cfg-loop-resolver-continue-switch-warning.patch hunk ✅ (2026-07-03)
• #15416 — regenerate docs/capabilities.md ✅ (2026-07-03)
• #15417 — fix examples 000–009 AOT smoke exit 139 on 000-HelloWorld ✅ (2026-07-03)
• #15973 — spine: add lib/JIT/Builtin/WeakRefNativeOpsJit.php ✅ (2026-07-04, PR Bootstrap: sync WeakRefNativeOpsJit spine entries (#15973) #15983)
• #16374 — spine: add ext/standard/JitStreamSupportsFeatureArg.php ✅ (2026-07-05, PR Bootstrap: spine sync JitStreamSupportsFeatureArg.php (#16374) #16381)
• #16909 — spine: add lib/VM/Builtin/ReflectionEnumFromName.php ✅ (2026-07-07, Stdlib: ReflectionEnum::fromName() static factory missing (PHP 8.2+, ext/reflection/php_reflection.c) #16877 regression)
• #9225 — examples 000–009 AOT smoke ✅ (regressed → Release v1.1.0: fix examples 000–009 AOT smoke regression (LLVM Module.php) #11206 → Release v1.1.0: fix examples 000–009 AOT smoke regression (001-SimpleWeb munmap_chunk) #12039)
• #9226 — examples web smoke ✅ (regressed → Release v1.1.0: fix examples web smoke regression (001-SimpleWeb serve readiness) #12040)
• #10369 — docs/capabilities sync ✅ (regressed → Release v1.1.0: regenerate docs/capabilities.md (capability-matrix --check drift) #11205 → closed)
• #17157 — regenerate docs/capabilities.md ✅ (2026-07-08)
• #17158 — fix examples 007-ThrowsWeb web smoke POST invalid ✅ (2026-07-08)
• #17405 — spine: clamp/date wrappers + MathClamp ✅ (2026-07-08)
• #17521 — spine: ReflectionFunctionIsGenerator + ReflectionMethodIsGenerator ✅ (2026-07-09, PR Bootstrap: spine sync ReflectionFunction/Method::isGenerator (#17521) #17536)
• #17522 — fix examples 009-FastCGIWeb AOT smoke PATH_INFO exit 134 ✅ (2026-07-09)
• #17627 — spine: ext/dom/FragmentConstruct.php ✅ (2026-07-10, PR Bootstrap: spine sync ext/dom/FragmentConstruct.php (#17627) #17636)
• #18195 — spine: ldap_escape helpers (LdapRuntime, JitLdapEscape, LdapEscapeJitHelper) ✅ (2026-07-12, PR Bootstrap: spine sync ldap_escape helpers (#18195) #18208/Self-host: sync spine for ldap_escape + xml SAX PHP-in-PHP units (#18195) #18213)
• #18550 — spine: sync 12 inventory files (wddx + nested JIT + multipart) ✅ (2026-07-13, PR spine sync batch)
• #18831 — regenerate docs/capabilities.md ✅ (2026-07-14, PR Release: regenerate docs/capabilities.md (capability-matrix drift) #18836; verified green 2026-07-15)
• #18832 — fix examples 001-SimpleWeb AOT smoke (QUERY_STRING=name=Smoke ignored) ✅ (2026-07-15, PR AOT: restore user-script htmlspecialchars stub — fix 001-SimpleWeb QUERY_STRING (closes #18832) #19142/AOT: restore ObOutputExecCaptureLlvm defer — fix user-script segfault (#18832 follow-up) #19144)
• #19504 — fix examples 003-MiniWebApp AOT smoke (exit 134 free(): invalid pointer) ✅ (closed 2026-07-16; regressed → Release v1.1.0: fix examples 003-MiniWebApp AOT smoke (exit 134 munmap_chunk) (re-#19504) #20507)
• #19978 — spine: sync isAnonymousClass() inventory (5 files; Add isAnonymousClass() for PHP 8.4 forward profile (#19969) #19970 fallout) ✅ (closed 2026-07-17)
• #19979 — fix examples 006-FileUploadWeb AOT smoke (multipart upload needle) ✅ (closed 2026-07-17)
• #19980 — regenerate docs/capabilities.md (capability-matrix gate) ✅ (closed 2026-07-17; 1217 builtins)
• #20507 — fix examples 003-MiniWebApp AOT smoke (exit 134 munmap_chunk(): invalid pointer; re-Release v1.1.0: fix examples 003-MiniWebApp AOT smoke (exit 134 free(): invalid pointer) #19504) ✅ (closed 2026-07-18, PR AOT: drop dead thankyou nest from MiniWebApp layout (#20507) #20552)
• #20752 — spine: Locale canonicalize/parse/compose after Stdlib: Locale canonicalize/parseLocale/composeLocale/getKeywords (#20738) #20750 ✅ (closed 2026-07-19)
• #20923 — fix examples 009-FastCGIWeb AOT smoke (missing PATH_INFO diagnostic; re-Release v1.1.0: fix examples 009-FastCGIWeb AOT smoke (PATH_INFO exit 134 realloc) #17522; release-blocker; filed 2026-07-19) ✅ (closed 2026-07-19)
• #21403 — regenerate docs/capabilities.md + docs/bootstrap-inventory.md (re-Release v1.1.0: regenerate docs/capabilities.md (capability-matrix gate) #19980; release-blocker; filed 2026-07-20)
• #22138 — spine: ReflectionClassIsCloneable.php (Stdlib: ReflectionClass::isCloneable() missing — __clone visibility (ext/reflection/php_reflection.c) #22109; release-blocker; filed 2026-07-22) ✅ (closed 2026-07-22)
• #22139 — fix bootstrap-selfhost-link LLVM verify on compiler_minimal (gen-0 Foundation: compiled-driver reuse has no lowering-source freshness guard — Tier-1 workflow can silently test stale codegen (script/bootstrap-resolve-compile-invoke.sh) #21855 drift; release-blocker; filed 2026-07-22) ✅ (closed 2026-07-22)
• #22638 — fix phpc build module verification (4 lowering defects; 266/266 helper units degraded) ✅ (closed 2026-07-23, PR Fix AOT module verification: four JIT lowering defects (#22638) #22643)
• #22845 — fix examples 003-MiniWebApp AOT smoke (empty $appName / missing MiniWebApp needle; re-Release v1.1.0: fix examples 003-MiniWebApp AOT smoke (exit 134 munmap_chunk) (re-#19504) #20507) ✅ (closed 2026-07-24, PR AOT: MiniWebApp htmlspecialchars + include $appName (#22845) #22871)
• #23426 — regenerate docs/capabilities.md (capability-matrix gate; re-Release v1.1.0: regenerate docs/capabilities.md + docs/bootstrap-inventory.md (re-#19980) #21403; release-blocker; filed 2026-07-26)
• #23427 — fix examples 005-SessionsWeb AOT smoke (POST flash exit 134 free(): invalid pointer; release-blocker; filed 2026-07-26)
• CHANGELOG draft (#9227 closed — stub on master; refresh before tag)

Pillar 1 (Trust) — #10533: 🟢 quick gates 5/5 green (user_release_ready: yes quick @ 3fce0ade3, inventory 6571/6571, link + helloworld OK, north-star5-fast ok). gen0_provenance: stale warn only (seed 9e6b9c12a / 40d; unverified-restamp — bootstrap honesty, not user-tag). Pillar 2 (Ship): 🔴 --full 7/9 — #23426 (capabilities) + #23427 (005 POST flash exit 134); web/changelog ok; #22845 ✅.

Gate checklist

• ./script/release-readiness.sh --full --json → user_release_ready: yes (2026-07-26 final: 7/9 — capability-matrix → Release v1.1.0: regenerate docs/capabilities.md (capability-matrix gate; re-#21403) #23426; examples-aot-smoke → Release v1.1.0: fix examples 005-SessionsWeb AOT smoke (POST flash exit 134 free(): invalid pointer) #23427)
• Quick gates: 5/5 green (2026-07-26 @ 3fce0ade3) → user_release_ready: yes (quick)
  • bootstrap-inventory ✅ (6571/6571)
  • spine-coverage-sync ✅
  • root-readme-sync ✅
  • north-star5-fast ✅
  • vm-driver-probe ✅
• No open release-blocker issues (2 open: Release v1.1.0: regenerate docs/capabilities.md (capability-matrix gate; re-#21403) #23426, Release v1.1.0: fix examples 005-SessionsWeb AOT smoke (POST flash exit 134 free(): invalid pointer) #23427 — filed 2026-07-26; Release v1.1.0: fix examples 003-MiniWebApp AOT smoke (empty $appName — missing MiniWebApp needle) (re-#20507) #22845 closed)
• Examples AOT smoke — 🔴 Release v1.1.0: fix examples 005-SessionsWeb AOT smoke (POST flash exit 134 free(): invalid pointer) #23427 (005-SessionsWeb POST flash exit 134 free(): invalid pointer)
• Examples web smoke ✅ (2026-07-24 --full; re-confirm with next --full)
• Capability-matrix — 🔴 Release v1.1.0: regenerate docs/capabilities.md (capability-matrix gate; re-#21403) #23426 (docs/capabilities.md out of date)
• CHANGELOG v1.1.0 stub ✅ (expand themes before tag)

Out of scope (v1.1.0)

• Bootstrap honesty tag / v2 self-host release
• north-star5-verify --strict (~1h)
• Full Zend parity, MCJIT execute (#98)

---

Bootstrap release roadmap (future v2 / self-host honesty)

Not a tag candidate until north-star5-verify --strict is green on demand. Track progress only.

Blocker / gap	Gate	Status	Tracker
Honest spine PHP main() runtime	full-spine smoke without native shortcut	🚧 partial	#8559
Compile-spine stub retirement	shrink PHP_COMPILER_SELFHOST_AOT on compile spine	🚧 in progress	#1402
M3 JIT unit strict	inventory compile_driver	🚧 partial	#3038
Bootstrap include_path	spine include resolution	open	#3223
php-cfg asymmetric visibility overlay	apply-patches.sh anchor	🔴 regression	#9729
Strict M5 presenter	north-star5-verify.sh --strict (~1h)	✅ green (pre-merge only)	#1492

Must-ship before bootstrap tag: spine N/N honest runtime, stub retirement on compile path, no Zend in cold-boot loop — see #1492.

---

Milestone status (Jul 2026 — maintainer probe 2026-07-26)

Milestone	Gate	Status	Tracker
M0 minimal link	make bootstrap-selfhost-link	✅ GREEN	OK /compiler/build/selfhost
M2 spine / inventory	bootstrap-inventory.php --check	✅ GREEN	release-readiness 6571/6571
M2 spine coverage	check-selfhost-spine-coverage-sync.php	✅ GREEN	6571 files
M2 VM driver execute	make bootstrap-selfhost-vm-driver-execute-probe	✅ GREEN	via release-readiness quick
M3 HelloWorld strict	make bootstrap-selfhost-helloworld	✅ GREEN (emit_path=native)	Hello World
M3 JIT unit strict	inventory compile_driver	🚧 partial	#3038
M4 full-revision	make bootstrap-selfhost-full-revision-probe	✅ GREEN	#2880
M4 full ladder	make bootstrap-loop-probe	✅ GREEN	#1498
M5 vendor (committed)	prelinked/bootstrap-vendor/*.o manifest	✅ GREEN	3/3 object_ok
M5 spine w/o vendor/	north-star5 step 4c	✅ GREEN	#3052 closed
M5 gen-0 no Zend	BOOTSTRAP_M5_NO_ZEND=1 empty build/	✅ GREEN	#3053 closed
M5 vendor native rebuild	rm prelinked/*.o, no Zend fallback	✅ GREEN	#3054 closed
M5 presenter (daily)	make north-star5-verify-fast	✅ GREEN	via release-readiness quick
M5 presenter (pre-merge)	north-star5-verify.sh --strict	✅ GREEN	~1h — bootstrap PRs only
M5 honest runtime	full-spine PHP main() at runtime	🚧 partial	#8559
User release --full	release-readiness.sh --full	🔴 RED	7/9 — #23426 + #23427; web/changelog ✅; quick 5/5

Daily verify (fast — use during development):

make bootstrap-selfhost-vm-driver-execute-probe   # ~20ms
make north-star5-verify-fast                      # ~1–2 min
./script/ci-fast.sh                               # NORTH_STAR5_VERIFY_FAST_GATE=1 default

Pre-merge bootstrap verify (strict — sparingly):

./script/docker-exec.sh -- bash -lc './script/north-star5-verify.sh --strict'

---

Next 5 worker priorities (parallel-safe)

1. Capability matrix (Pillar 2) — #23426 (release-blocker — regenerate committed docs/capabilities.md)
2. SessionsWeb AOT (Pillar 2) — #23427 (release-blocker — 005 POST flash exit 134 free(): invalid pointer)
3. Re-probe --full — after Release v1.1.0: regenerate docs/capabilities.md (capability-matrix gate; re-#21403) #23426 + Release v1.1.0: fix examples 005-SessionsWeb AOT smoke (POST flash exit 134 free(): invalid pointer) #23427 → user_release_ready: yes
4. CHANGELOG expand — refresh v1.1.0 stub themes before tag
5. Bootstrap honesty (not tag) — gen-0 seed stale warn; #1402 / #8559

Parity backlog themes (Jul 2026)

Theme	Examples
Language (PHP 8.3–8.4)	property hooks (#6424–#6427), enum case invoke #9846, lazy proxy #7387
Stdlib gaps	ext/dom batch (#14418–#14469), is_callable #3132, ext/zip #3337
php-in-php / shrink C	#7389 linker audit, superglobals_refresh.c #5330, phpc_stream.c #5343
php-src-strict	enum operands #5906 / #5907 / #7390, hash #5780

---

Repro (roadmap health check)

docker info >/dev/null
./script/docker-exec.sh -- bash -lc './script/release-readiness.sh --json'
./script/docker-exec.sh -- bash -lc './script/release-readiness.sh --full --json'

Done when (living doc)

• M5 red gates Self-host M5: link compiler_lib_spine_smoke with prelinked vendor .o only (no vendor/ tree) #3052, Self-host M5: gen-0 bootstrap-selfhost-link without Zend bin/compile.php (compiled driver only) #3053, Self-host M5: native vendor rebuild must emit .o when PHP_COMPILER_KEEP_OBJECT_FILE=1 #3054 closed (strict presenter green)
• User + bootstrap release roadmap sections on 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 (2026-06-15)
• Milestone table updated after maintainer probe (2026-07-20)
• “Next 5” list points at open implementation-ready issues workers can claim without overlap (2026-07-26 → Release v1.1.0: regenerate docs/capabilities.md (capability-matrix gate; re-#21403) #23426 / Release v1.1.0: fix examples 005-SessionsWeb AOT smoke (POST flash exit 134 free(): invalid pointer) #23427)
• Fast M5 gate (north-star5-verify --fast) default in docs, CI, and Cursor rules
• Parity themes link to php-src paths + this-repo PHP modules (not permanent C shortcuts)

Verification (local / Docker only)

./script/docker-exec.sh -- bash -lc 'make north-star5-verify-fast'
./script/docker-exec.sh -- bash -lc 'php script/bootstrap-inventory.php --check'
./script/docker-exec.sh -- bash -lc 'make bootstrap-loop-probe'

[PurHur]

Roadmap refreshed after source audit: full suite 341 tests (0 failures), VM compliance 133/133 pass, JIT compliance 133/133 skipped (#98). Added issues #96–#107 for switch, strpos, ??, globals, extends, PHPT web sections, writable superglobals, filter_var, date/time, phpc.json, array assign.

[PurHur]

Roadmap refreshed after source audit (2026-05-18): added issues #113–#126 (host PHP 8.2 parser, ternary/break/append, path stdlib, OB, getenv, require_once, PATH_INFO, redirects, random_bytes, htmlspecialchars JIT, pow, Makefile smoke). Test baseline: 349 tests, 165 skipped, 0 failures via script/ci-local.sh.

[PurHur]

Audit 2026-05-18 (batch 3): ci-local.sh green (366 tests, 0 failures). Fixed ** via TypeReconstructor + patch. Added implementation issues #135–#160. Closed items reflected: #88 serve, #121 PATH_INFO, #125 power, #126 Makefile.

[PurHur]

Audit batch 5 (2026-05-18)

Source review highlights:

• lib/Compiler.php::compileStmt() only handles Jump, JumpIf, Switch_ — no loop statements. Created Language: while, do-while, and for loops (CFG → VM → JIT) #192 (critical blocker for any non-trivial app).
• compileParam() rejects defaults and variadics — Language: Default parameter values and optional arguments #196, Language: Variadic functions (...$args) and func_get_args() #197.
• AOT superglobals still baked via lib/JIT/SuperglobalInit.php — tracked as AOT: Per-request superglobal refresh in native binary (not compile-time bake) #201 (AOT slice of Web: Runtime-populated superglobals for JIT and AOT (per-request $_GET/$_POST) #49).
• Docker: ircmaxell/php-compiler:* images not pullable; harness must use Infrastructure: Publish Docker dev image and document container CI workflow #202 published image workflow.
• Added 22 issues (Language: while, do-while, and for loops (CFG → VM → JIT) #192–DevEx: phpc serve --aot runs precompiled CGI binary per project #213) with acceptance criteria and file pointers.

Next suggested work (P0): #192 → #53 → #49/#201 → #54 → #67/#210.

[PurHur]

Roadmap audit batch 6 (2026-05-19)

Updated: current phase (Phase 2), next 3 priorities (#192 → #53 → #99), closed-issue sync (#47, #193, #196, #200, #201, #203, #213, …), harness/Docker notes.

Created: #234 serve tests in Docker CI, #235 HTTPS/HTTP_HOST, #236 phpc lint diagnostics, #237 LLVM 9 in dev image.

Expanded: #157 param coercion, #158 mb_strlen UTF-8 semantics.

De-duped: comments on #98 / #174 / #73 — local ci-local.sh + docker-ci-local.sh are canonical; GHA is optional mirror.

Next backlog pass: close #158 if byte-length is accepted; merge #73 into #202/#237 when make test-docker is fully green.

[PurHur]

Backlog audit batch 7 (2026-05-19): synced closed #236/#237, created #243–#246, expanded #53/#67, de-duped #98/#174/#73/#202 comments.

[PurHur]

Backlog audit batch 8 (2026-05-19)

ROADMAP body updated: current phase, next 3 priorities, batch 8 state table, CI de-dupe matrix.

Created: #247 (AOT execute smoke 002-StaticWeb), #248 (ServeTest POST), #249 (make test → test-docker), #250 (ci-local JIT skip guard).

Expanded: #54 (include JIT/AOT hints), #114 (ternary hints).

De-duped: comments on #174 / #202 / #73 — local ci-local.sh + Docker canonical; #98 not #174 for JIT skips.

Next implementer focus: #192 → #53 → #99 (unchanged P0 language path).