🗺️ 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 (Jun 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)

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, preg_match JIT, spl_autoload, php-in-php helpers, nested JIT compile isolation, 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 (reopened 2026-06-22 — JIT helper drift after Regenerate docs/bootstrap-inventory.md for v1.1.0 (#10368) #10450)
• #10542 — spine: add NestedJitCompileScope.php (Fix AOT smoke: nested JIT helper compile isolation (#10343) #10498 regression)
• #9225 — examples 000–009 AOT smoke ✅
• #9226 — examples web smoke ✅
• #10369 — docs/capabilities sync ✅ (Sync v1.1.0 docs: README, development-status, examples smoke matrix (#10369) #10406)
• CHANGELOG draft (#9227 closed — stub on master; refresh before tag)

Gate checklist

• ./script/release-readiness.sh --full --json → user_release_ready: yes (blocked: Release v1.1.0: regenerate stale docs/bootstrap-inventory.md #10368, Release v1.1.0: add NestedJitCompileScope to self-host spine #10542, Release-readiness: bootstrap-inventory gate flake in full bundle #10531 flake)
• Quick gates: 3/5 green (2026-06-22 maintainer probe)
  • spine-coverage-sync (committed doc) ✅
  • vm-driver-probe ✅
  • root-readme-sync ✅
  • bootstrap-inventory — Release v1.1.0: regenerate stale docs/bootstrap-inventory.md #10368
  • north-star5-fast — Release v1.1.0: add NestedJitCompileScope to self-host spine #10542
• No open release-blocker issues (2 open: Release v1.1.0: regenerate stale docs/bootstrap-inventory.md #10368, Release v1.1.0: add NestedJitCompileScope to self-host spine #10542)
• Examples AOT smoke ✅ (Release v1.1.0: examples 000–009 AOT smoke green #9225); web smoke ✅ (Release v1.1.0: examples web smoke green #9226)

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 (Jun 2026 — maintainer probe 2026-06-22)

Milestone	Gate	Status	Tracker
M0 minimal link	make bootstrap-selfhost-link	✅ GREEN	#2894
M2 spine / inventory	bootstrap-inventory.php --check	🔴 stale doc	#10368 (reopened)
M2 spine coverage	check-selfhost-spine-coverage-sync.php	🔴 1 missing	#10542 (NestedJitCompileScope.php)
M2 VM driver execute	make bootstrap-selfhost-vm-driver-execute-probe	✅ GREEN	#2201
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	#10542
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
Spine coverage sync	check-selfhost-spine-coverage-sync.php	🟡 committed doc OK; live regen finds gap	#10542

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. Inventory doc regen — #10368 (release-blocker — quick gate red; regen + commit)
2. Spine: NestedJitCompileScope — #10542 (release-blocker — north-star5-fast red after Fix AOT smoke: nested JIT helper compile isolation (#10343) #10498)
3. Compile-spine stub retirement — #1402 / docs/bootstrap-m5-fast-path.md
4. Honest spine PHP main() runtime — #8559
5. Full bundle inventory flake — #10531 (secondary — after P0 green)

Parity backlog themes (Jun 2026)

Theme	Examples
Language (PHP 8.3–8.4)	property hooks (#6424–#6427), enum case invoke #9846, lazy proxy #7387
Stdlib gaps	is_callable #3132, createLazyProxy #7387, 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 'php script/bootstrap-inventory.php --check'
./script/docker-exec.sh -- bash -lc 'make bootstrap-selfhost-vm-driver-execute-probe'
./script/docker-exec.sh -- bash -lc 'make north-star5-verify-fast'
./script/docker-exec.sh -- bash -lc 'make bootstrap-loop-probe'

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-06-22)
• “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).