JIT: Project include lowering for 003-MiniWebApp (phpc serve --jit blocked on #475)

[PurHur]

Problem

#475 tracks JIT lowering for static include/require paths. #587 / #1759 add MiniWebAppJitProjectTest for project-level JIT, but the test remains skipped or home-only until:

1. JIT resolves TYPE_INCLUDE for literal paths (Language: JIT include/require compile-time lowering (#54 follow-up) #475)
2. OOP + private methods compile under JIT (Language: Class methods and property access in JIT #58, Language: Visibility, constructors, and destructors #145)

VM ✅ and AOT multi-TU ✅ for 003-MiniWebApp; JIT project mode is the only north-star mode still partial in the run matrix.

#207 (phpc serve --jit) cannot serve 003 until project includes JIT.

Goal

MiniWebAppJitProjectTest runs green (not skipped) for at least home + hello PATH_INFO under:

MINIWEBAPP_JIT_PROJECT_GATE=1 ./script/ci-local.sh --filter MiniWebAppJitProject

Optional follow-on: #1759 contact POST + #730 promotion to ci-fast.sh.

Implementation hints

Layer	Files	Notes
Include op	lib/JIT.php TYPE_INCLUDE	Delegate to same literal resolver as AOT LiteralIncludeDiscovery (#54)
Multi-file	lib/Runtime.php, project entry	Compile public/index.php graph like bin/jit.php multi-input
OOP	#58, #145	Router::dispatch, private render methods
Test	test/unit/MiniWebAppJitProjectTest.php	@group llvm; reuse MiniWebAppCgiEnv helpers from AOT tests (#1529)
Serve	#207 (later)	Consumer once project JIT green

Unblock order

#475 literal include JIT → #58/#145 OOP JIT → #587 test home → #1759 PATH_INFO/POST → #730 ci-fast

Acceptance criteria

• php bin/jit.php examples/003-MiniWebApp/public/index.php with CGI env for home route prints HTML (non-empty)
• MiniWebAppJitProjectTest not skipped when LLVM 9 ready and gates on
• examples/README.md JIT column for 003 moves from partial → ✅ (via Examples: Sync examples/README.md run matrix after #764 close #1531)

Verification (local / Docker only)

MINIWEBAPP_JIT_PROJECT_GATE=1 ./script/ci-local.sh --filter MiniWebAppJitProject
docker run --rm -v "$(pwd):/compiler" -w /compiler php-compiler:22.04-dev \
  env MINIWEBAPP_JIT_PROJECT_GATE=1 ./script/ci-local.sh --filter MiniWebAppJitProject

No GitHub Actions.

Dependencies

• Language: JIT include/require compile-time lowering (#54 follow-up) #475 — include/require JIT lowering (primary)
• Language: Class methods and property access in JIT #58, Language: Visibility, constructors, and destructors #145 — class methods / visibility
• Testing: JIT smoke for phpc build --project on 003-MiniWebApp #587, Testing: MiniWebAppJitProjectTest — PATH_INFO hello + contact POST (#587 phase 2) #1759, Testing: promote MiniWebAppJitProjectTest to ci-fast when #587 green #730 — test ladder
• Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207 — serve --jit (downstream)

Links

• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 1 Language + Phase 4 Polish
• Reference app: examples/003-MiniWebApp/
• AOT parity: AOT: MiniWebApp native binary CLI execute emits empty stdout (post-link) #764 ✅

[PurHur]

Unblock matrix (batch 101)

Blocker	Symptom in MiniWebAppJitProjectTest	Tracker
TYPE_INCLUDE in JIT	LogicException from lib/JIT.php	#475 (canonical)
ClassMethod not jittable	skip / throw on Router::dispatch	#58, #145
Template require chain	second TU not bundled	#475 + LiteralIncludeDiscovery reuse
Per-request superglobals	stale $_GET between JIT CLI runs	#49, #642
Project JIT CLI	no phpc build --project --jit	#1801 (optional; test uses bin/jit.php first)

Suggested first green slice

1. JIT-compile public/index.php with only route=home (no contact POST) — mirror MiniWebAppVmCliTest
2. stdout needle: MiniWebApp or layout title from templates/home.php
3. Wire MINIWEBAPP_JIT_PROJECT_GATE=1 in ci-local.sh (CI: Default MINIWEBAPP_JIT_PROJECT_GATE=1 in ci-local after #587 green #1869); promote to ci-fast via Testing: promote MiniWebAppJitProjectTest to ci-fast when #587 green #730 only after slice is not skipped

Key files

• test/unit/MiniWebAppJitProjectTest.php (create / extend per Testing: JIT smoke for phpc build --project on 003-MiniWebApp #587)
• examples/003-MiniWebApp/public/index.php, src/Router.php, phpc.json
• lib/JIT.php (TYPE_INCLUDE branch)
• lib/AOT/LiteralIncludeDiscovery.php (reference for static paths)

Verify

./script/ci-local.sh --filter MiniWebAppJitProjectTest
./script/docker-ci-local.sh --filter MiniWebAppJitProjectTest

Sibling: #587 (test definition), #475 (include lowering). NS1 VM/AOT already green (#764 ✅).

[PurHur]

Implementation-ready spec (May 2026 parity audit)

Category

language / runtime (JIT project graph)

Current state

Mode	003-MiniWebApp home route	Blocker
VM	✅ serve smoke	—
AOT multi-TU	✅ #764	—
JIT project	❌ skipped / LLVM or include gaps	#475, OOP JIT partial

Literal include JIT (#475) and public OOP (#58 / #145) have landed on master for many paths; this issue tracks project-level JIT compiling the full MiniWebApp graph.

Repro (failure today)

MINIWEBAPP_JIT_PROJECT_GATE=1 ./script/docker-exec.sh bash -lc \
  'source script/php-env.sh && vendor/bin/phpunit --filter MiniWebAppJitProjectTest'

Or direct:

./script/docker-exec.sh bash -lc '
  export SCRIPT_NAME=/index.php PATH_INFO=/hello QUERY_STRING= REQUEST_METHOD=GET
  php bin/jit.php examples/003-MiniWebApp/public/index.php
'

Expected when done: non-empty HTML containing route output (same body needles as VM serve smoke).

php-src reference

N/A (integration). Semantics follow Zend for:

• include/require — Zend/zend_execute.c ZEND_INCLUDE_OR_EVAL
• Method dispatch — Zend/zend_execute.c ZEND_INIT_METHOD_CALL

Scope (this repo)

Piece	Path
Include JIT	lib/JIT.php TYPE_INCLUDE + lib/JIT/IncludeHelper.php
Project entry	lib/Runtime.php, bin/jit.php multi-file graph
OOP JIT	#58, #145, #55 (non-void returns)
Test	test/unit/MiniWebAppJitProjectTest.php (@group llvm)
CI gate	MINIWEBAPP_JIT_PROJECT_GATE → #587, #730

Done when

• MiniWebAppJitProjectTest passes (not skipped) with MINIWEBAPP_JIT_PROJECT_GATE=1.
• ./script/ci-local.sh --filter MiniWebAppJitProject green on harness Docker image.
• Home + hello PATH_INFO routes match VM serve output (grep needles from script/examples-web-smoke.sh).
• docs/capabilities-syntax.md MiniWebApp JIT row flipped from partial → yes.

Unblock order

#475 include JIT → #55 non-void JIT returns → MiniWebAppJitProjectTest home → #1759 POST → #730 ci-fast

[PurHur]

claim: worker-lane-a-automation — starting this run

[PurHur]

WIP (lane A)

Done this run: CLI entry scripts (bin/vm.php, bin/jit.php, …) now resolve relative script paths against the invocation cwd before chdir to the repo root. This unblocks MiniWebAppVmCliTest and the documented repro when run from examples/003-MiniWebApp/public/ (was: Could not open file index.php).

Still blocked for full gate:

• script/jit-runtime-probe.php / MiniWebAppJitProjectTest skip in Docker: MCJIT execute segfaults on trivial echo 2+2 (CI: Run JIT compliance tests in CI (fix LLVM skip in PHPUnit) #98) — separate from path resolution.
• When JIT probe is green, MiniWebApp JIT compile hits substr() length must be an integer during LLVM lowering (stdlib/JIT typing) — needs follow-up.

PR incoming with verification commands.