🗺️ 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 (release-blocker, Stdlib: ReflectionFunction/Method::isGenerator() (#17505) #17511 regression 2026-07-09)
• #17522 — fix examples 009-FastCGIWeb AOT smoke PATH_INFO exit 134 (release-blocker, 2026-07-09)
• CHANGELOG draft (#9227 closed — stub on master; refresh before tag)

Gate checklist

• ./script/release-readiness.sh --full --json → user_release_ready: yes (2026-07-09: 6/9 green — Release v1.1.0: spine sync ReflectionFunctionIsGenerator + ReflectionMethodIsGenerator (#17511) #17521 spine-coverage, Release v1.1.0: fix examples 009-FastCGIWeb AOT smoke (PATH_INFO exit 134 realloc) #17522 examples-aot-smoke)
• Quick gates: 3/5 green (2026-07-09) → user_release_ready: no (quick)
  • bootstrap-inventory ✅ (4302/4302)
  • spine-coverage-sync 🔴 → Release v1.1.0: spine sync ReflectionFunctionIsGenerator + ReflectionMethodIsGenerator (#17511) #17521
  • root-readme-sync ✅
  • north-star5-fast 🔴 (cascades from spine) → Release v1.1.0: spine sync ReflectionFunctionIsGenerator + ReflectionMethodIsGenerator (#17511) #17521
  • vm-driver-probe ✅
• No open release-blocker issues (2 open: Release v1.1.0: spine sync ReflectionFunctionIsGenerator + ReflectionMethodIsGenerator (#17511) #17521, Release v1.1.0: fix examples 009-FastCGIWeb AOT smoke (PATH_INFO exit 134 realloc) #17522)
• Examples AOT smoke 🔴 009-FastCGIWeb PATH_INFO exit 134 → Release v1.1.0: fix examples 009-FastCGIWeb AOT smoke (PATH_INFO exit 134 realloc) #17522
• Examples web smoke ✅ (2026-07-09 --full probe; Release v1.1.0: fix examples 007-ThrowsWeb web smoke (POST invalid missing Invalid email) #17158 closed)
• Capability-matrix ✅ (924 builtins; Release v1.1.0: regenerate docs/capabilities.md (capability-matrix --check) #17157 closed)

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-09)

Milestone	Gate	Status	Tracker
M0 minimal link	make bootstrap-selfhost-link	✅ GREEN	#2894
M2 spine / inventory	bootstrap-inventory.php --check	✅ GREEN	4302/4302
M2 spine coverage	check-selfhost-spine-coverage-sync.php	🔴 RED	#17521 (#17511 regression)
M2 VM driver execute	make bootstrap-selfhost-vm-driver-execute-probe	✅ GREEN	#13101 closed PR #13110
M3 HelloWorld strict	make bootstrap-selfhost-helloworld	✅ GREEN (emit_path=native)	—
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	🔴 RED	#17521 spine sync
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 (6/9; #17521, #17522)	quick 3/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. Spine sync isGenerator helpers — #17521 (release-blocker + IMPORTANT — unblocks quick + north-star5-fast)
2. FastCGI AOT smoke — #17522 (release-blocker + IMPORTANT — 009-FastCGIWeb PATH_INFO exit 134)
3. Re-probe --full bundle — after Release v1.1.0: spine sync ReflectionFunctionIsGenerator + ReflectionMethodIsGenerator (#17511) #17521 + Release v1.1.0: fix examples 009-FastCGIWeb AOT smoke (PATH_INFO exit 134 realloc) #17522 → user_release_ready: yes
4. CHANGELOG expand — refresh v1.1.0 stub before tag; reopen Release roadmap: v1.1.0 #8739 meta on tag day
5. Compile-spine stub retirement — #1402 (bootstrap track; parallel)

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-09)
• “Next 5” list points at open implementation-ready issues workers can claim without overlap
• 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).