Language: JIT include/require compile-time lowering (#54 follow-up)

[PurHur]

Category

language

Problem

#54 closed with AOT literal-path bundling (lib/AOT/LiteralIncludeDiscovery.php, lib/AOT/SourceBundler.php). VM and AOT compile static includes. JIT execute path remains fragile: bin/jit.php on multi-file / __DIR__ graphs can segfault or fall back to runtime TYPE_INCLUDE where IncludeHelper is not wired for the entry script (#1770, #207).

examples/003-MiniWebApp/ needs phpc serve --jit with the same include graph as VM/AOT.

php-src reference

• php/php-src Zend/zend_compile.c — zend_compile_include_or_eval, zend_compile_require
• php/php-src Zend/zend_execute.c — zend_include_or_eval, zend_execute_scripts
• php/php-src Zend/zend_builtin_functions.c — compile_file hook for include/require_once dedup (Language: require_once and include_once deduplication #120)

Repro (failure today)

Two-file JIT (create helper then include):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh
  echo "<?php function answer(): int { return 42; }" > /tmp/helper.php
  php bin/jit.php -r "include \"/tmp/helper.php\"; echo answer();"'

Expected (Zend JIT equivalent / VM): 42
Actual (May 2026): segmentation fault in bin/jit.php MCJIT execute path, or LogicException on unresolved TYPE_INCLUDE.

MiniWebApp gate (when OOP green):

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'

Scope (this repo)

Area	Files
Shared discovery	lib/AOT/LiteralIncludeDiscovery.php, lib/Web/LiteralIncludeDiscovery.php
JIT lowering	lib/JIT/IncludeHelper.php, lib/JIT.php TYPE_INCLUDE
Compiler	lib/Compiler.php — inline literal includes at compile time
Entry	bin/jit.php, bin/serve.php — pass project root / deploy path
Tests	test/compliance/cases/include_two_file_jit.phpt, #587 gate
Docs	docs/capabilities-syntax.md row #475 — set JIT column yes

Dynamic include $variable remains out of scope (document in capabilities).

Done when

• Two-file repro prints 42 under bin/jit.php without segfault
• __DIR__ . '/file.php' concat paths work (pairs Language: VM/JIT runtime __DIR__/__FILE__ on include stack (#85) #707)
• require_once dedup matches VM (Language: require_once and include_once deduplication #120)
• MINIWEBAPP_JIT_PROJECT_GATE / Testing: JIT smoke for phpc build --project on 003-MiniWebApp #587 opt-in green on harness
• No runtime throw new LogicException('include/require must be resolved before AOT compile') for static paths in JIT

Implementation slices

1. Single literal require 'helper.php' JIT PHPT
2. __DIR__ paths + IncludeHelper::compileLiteral
3. phpc serve --jit entry discovery (Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207)

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter include_two_file'
make test-harness  # optional; prefer targeted filter

Use ./script/docker-exec.sh — bind-mount docker run -v "$(pwd):/compiler" is often empty on Runforge.

Dependencies

• Language: include/require in JIT and AOT (multi-file applications) #54 ✅ AOT bundling (reference)
• Language: VM/JIT runtime __DIR__/__FILE__ on include stack (#85) #707 ✅ __DIR__
• Language: require_once and include_once deduplication #120 require_once table
• Blocks: Web: JIT/AOT mode for bin/serve.php (compile per script on first request) #207, JIT: Project include lowering for 003-MiniWebApp (phpc serve --jit blocked on #475) #1770, Reference app: examples/003-MiniWebApp (router, templates, forms) #67 multi-file JIT serve

Links

• Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 — self-host multi-TU compile
• 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 ROADMAP Phase 1 language

[PurHur]

Harness-safe verification (replace raw docker run -v)

The issue body still shows docker run -rm -v "$(pwd):/compiler" … — do not use on Runforge (empty bind-mount). Use:

Targeted compliance

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter include_two_file'

Full gate

make test-harness
# or:
./script/docker-ci-local.sh

Manual JIT probe (003 front controller)

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'

Expected progression: no TYPE_INCLUDE throw → may still fail on #58/#145 until OOP JIT lands.

CI policy

Local/Docker only — #394 ✅ (GHA disabled). LLVM toolchain: #174 (orthogonal version bump).

Related doc cleanup: #2245 (remove remaining raw docker snippets).

[PurHur]

Backlog architect note (2026-05-26) — harness-safe verification

The acceptance criteria below still show raw docker run -v "$(pwd):/compiler". On Runforge/harness hosts that bind-mount is often empty — use the repo wrappers instead:

# Targeted JIT include probe
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'

# Filtered CI
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && ./script/ci-local.sh --filter include_two_file'

# Full gate
make test-harness

CI policy: merge gates = ./script/ci-local.sh / make test-harness (#436 ✅). #174 (LLVM 14+) is toolchain-only — not a substitute. GHA optional (#394 ✅).

Unblock chain (unchanged): #54 ✅ AOT bundler → this issue (JIT) → #1770 / #587 project JIT → #207 / #2274 serve --jit e2e.

[PurHur]

Backlog architect note (May 2026): Prefer harness-safe verification per ROADMAP #78 — replace acceptance docker run -v "$(pwd):/compiler" blocks with:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'
make test-harness

Blocks #207 / #1770 / #2274; land after #54 AOT bundler reuse in lib/JIT.php. Parent chain: #58/#145 for OOP runtime after include lowering compiles.

[PurHur]

Backlog architect note (May 2026): Harness verification should use ./script/docker-exec.sh or make test-harness, not raw docker run -v "$(pwd):/compiler" (empty bind-mount on Runforge — #272).

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter include_two_file'

Unblock chain: this issue → #1770 (003 project JIT) → #587 / #1869 → #2274 serve-jit e2e → #1900 ci-local gate. ROADMAP #78 tracks de-dupe vs AOT bundling (#54 ✅).

[PurHur]

Verification note (May 2026): Prefer harness-safe commands over raw bind-mount Docker:

```bash
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'
make test-harness
```

Acceptance criteria in the issue body still valid on hosts with working `-v` mounts; on Runforge use `docker-exec.sh` / `docker-ci-local.sh` (#272 ✅). Blocks #207 serve--jit and #1770 project includes — ROADMAP #78 priority 2.

[PurHur]

Backlog expansion (2026-05-26) — implementation + harness verification

Reference implementation (AOT today)

Read these first — JIT v1 should reuse discovery, not reinvent bundling:

Component	Path	Role
Discovery	lib/AOT/LiteralIncludeDiscovery.php	Static path expressions from entry
Bundle	lib/AOT/SourceBundler.php	Merged translation unit for link
Entry	bin/compile.php	Calls discovery before emit
Once table	lib/JIT.php (search require_once / #120)	Dedup included files at module scope

Suggested JIT lowering sequence

1. At TYPE_INCLUDE compile site, resolve path with __DIR__ (Language: Magic constants __DIR__, __FILE__, __LINE__ for multi-file apps #85 ✅) + literal concat only.
2. Run same discovery as AOT; emit nested LLVM functions or inlined blocks per bundled file (start with single included file).
3. Leave dynamic include $var as compile-time error (document in docs/capabilities.md).
4. Add test/compliance/cases/include_two_file_jit.phpt mirroring existing VM two-file fixture.

Unblock chain (do not parallelize blindly)

#475 (this) → #1770 (003 project JIT) → #587 (ci smoke) → #1869 / #730 (gate promotion)
            → #207 (serve --jit) + #2274 (001 flat serve-jit) + #2408 (007 serve-jit)

Verification — harness-safe only

Do not use docker run -v "$(pwd):/compiler" on Runforge (empty mount — #272 ✅).

make docker-build-22   # once
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter include_two_file'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/jit.php examples/003-MiniWebApp/public/index.php'

Full gate (one container at a time):

make test-harness
# or: ./script/docker-ci-local.sh

No GitHub Actions required (#394 ✅).

Dependencies (ordered)

• Language: include/require in JIT and AOT (multi-file applications) #54 ✅ — AOT literal bundling (reference)
• Web: Nested include inherits parent variable scope (template partials) #471 / Stdlib: extract() and compact() JIT/AOT parity (#275 follow-up) #476 — VM include frame semantics
• Language: Class methods and property access in JIT #58 / Language: Visibility, constructors, and destructors #145 — OOP may still fail after include lowering on 003

[PurHur]

claim: worker-lane-b — starting this run

[PurHur]

Progress (worker-lane-b): LLVM IR compile-time include lowering verifies for all compliance fixtures + absolute-path two-file repro. PR incoming with IncludeJitCompileTest and IncludeHelper resume blockStorage fix.

Verified locally (Docker):

• vendor/bin/phpunit test/unit/IncludeJitCompileTest.php — green
• vendor/bin/phpunit test/unit/IncludeLiteralTest.php — VM/AOT green; JIT execute tests skip (MCJIT probe fails in harness — segfault at jitEmitInPlace even for echo 42, not include-specific)

Still open for #475: MCJIT execute path (bin/jit.php, MINIWEBAPP_JIT_PROJECT_GATE) — blocked on harness MCJIT runtime; compile+verify path is ready.

php-src ref: Zend/zend_compile.c (zend_compile_include_or_eval), Zend/zend_execute.c (zend_include_or_eval).