From d0f561e321211f4678b6202ead44f3fcf664a2b6 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Sun, 14 Jun 2026 17:23:30 +0000
Subject: [PATCH 1/8] test(catch): lock in catching exceptions by generic
 specialization

Each HttpError<X> monomorphizes into a distinct concrete class (extending
the native exception, implementing the original name as a marker
interface), so a `catch (HttpError<X> $e)` clause is just a type-hint
position that CallSiteRewriter rewrites to the specialized FQN and PHP's
native catch discriminates by concrete class. This worked as emergent
behavior with no dedicated production code; add a fixture + integration
test so a future narrowing of CallSiteRewriter or the scanner's
type-hint detection cannot regress it silently.

Covers specific-specialization discrimination (the textually-first arm is
skipped), bare-marker catch-all, and a union of two specializations, at
runtime plus a rewrite snapshot.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../GenericExceptionCatchIntegrationTest.php  | 177 ++++++++++++++++++
 .../source/Client.xphp                        |  69 +++++++
 .../source/Errors/HttpError.xphp              |  13 ++
 .../source/Models/Forbidden.xphp              |   9 +
 .../source/Models/NotFound.xphp               |   9 +
 .../verify/catch_runtime.php                  |  50 +++++
 .../Client.expected.php                       |  60 ++++++
 7 files changed, 387 insertions(+)
 create mode 100644 test/Transpiler/Monomorphize/GenericExceptionCatchIntegrationTest.php
 create mode 100644 test/fixture/compile/generic_exception_catch/source/Client.xphp
 create mode 100644 test/fixture/compile/generic_exception_catch/source/Errors/HttpError.xphp
 create mode 100644 test/fixture/compile/generic_exception_catch/source/Models/Forbidden.xphp
 create mode 100644 test/fixture/compile/generic_exception_catch/source/Models/NotFound.xphp
 create mode 100644 test/fixture/compile/generic_exception_catch/verify/catch_runtime.php
 create mode 100644 test/fixture/compile/generic_exception_catch/verify/testCatchClausesRewriteToDistinctSpecializedFqns/Client.expected.php

diff --git a/test/Transpiler/Monomorphize/GenericExceptionCatchIntegrationTest.php b/test/Transpiler/Monomorphize/GenericExceptionCatchIntegrationTest.php
new file mode 100644
index 0000000..a93e805
--- /dev/null
+++ b/test/Transpiler/Monomorphize/GenericExceptionCatchIntegrationTest.php
@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+namespace XPHP\Transpiler\Monomorphize;
+
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter\Standard as StandardPrinter;
+use PHPUnit\Framework\Attributes\RunInSeparateProcess;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use XPHP\FileSystem\FileFinder\NativeFileFinder;
+use XPHP\FileSystem\FileReader\NativeFileReader;
+use XPHP\FileSystem\FileWriter\NativeFileWriter;
+use XPHP\TestSupport\CompiledFixture;
+use XPHP\TestSupport\SnapshotHash;
+
+/**
+ * Catching an exception by its generic specialization. Because each
+ * `HttpError<X>` monomorphizes into a distinct concrete class (extending the
+ * native exception, implementing the original name as a marker interface), a
+ * `catch (HttpError<X> $e)` clause is just another type-hint position that
+ * CallSiteRewriter rewrites to the specialized FQN. PHP's native catch then
+ * discriminates by concrete class.
+ *
+ * These tests lock that behavior in: it works today as emergent behavior, with
+ * no production code dedicated to it, so a future narrowing of CallSiteRewriter
+ * or the scanner's type-hint detection could regress it silently.
+ */
+final class GenericExceptionCatchIntegrationTest extends TestCase
+{
+    private string $sourceDir;
+    private string $workDir;
+    private string $targetDir;
+    private string $cacheDir;
+
+    protected function setUp(): void
+    {
+        $this->sourceDir = realpath(__DIR__ . '/../../fixture/compile/generic_exception_catch/source')
+            ?: throw new RuntimeException('Fixture missing');
+        $this->workDir = sys_get_temp_dir() . '/xphp-generic-catch-' . uniqid('', true);
+        $this->targetDir = $this->workDir . '/dist';
+        $this->cacheDir = $this->workDir . '/.xphp-cache';
+        mkdir($this->workDir, 0o755, true);
+    }
+
+    protected function tearDown(): void
+    {
+        if (is_dir($this->workDir)) {
+            self::rrmdir($this->workDir);
+        }
+    }
+
+    #[RunInSeparateProcess]
+    public function testGenericCatchDiscriminatesBySpecializationAtRuntime(): void
+    {
+        $fixture = CompiledFixture::compile($this->sourceDir, 'generic-catch-runtime');
+        $fixture->registerAutoload('App\\GenericExceptionCatch\\');
+        try {
+            require __DIR__ . '/../../fixture/compile/generic_exception_catch/verify/catch_runtime.php';
+        } finally {
+            $fixture->cleanup();
+        }
+    }
+
+    public function testCatchClausesRewriteToDistinctSpecializedFqns(): void
+    {
+        $this->compile();
+
+        $notFoundFqn = Registry::generatedFqn(
+            'App\\GenericExceptionCatch\\Errors\\HttpError',
+            [new TypeRef('App\\GenericExceptionCatch\\Models\\NotFound')],
+        );
+        $forbiddenFqn = Registry::generatedFqn(
+            'App\\GenericExceptionCatch\\Errors\\HttpError',
+            [new TypeRef('App\\GenericExceptionCatch\\Models\\Forbidden')],
+        );
+
+        // The two specializations MUST be distinct FQNs — that distinctness is
+        // what lets the two catch arms discriminate at all. This (plus the
+        // snapshot) pins the rewrite shape, but it is position-insensitive: a
+        // regression that swapped the two arm *bodies* would slip past here
+        // because both FQNs would still appear and keep their first-seen order
+        // (SnapshotHash's documented blind spot). The runtime test
+        // (`classify('forbidden')` must skip the NotFound arm) is what actually
+        // guards the arm/body pairing.
+        self::assertNotSame($notFoundFqn, $forbiddenFqn);
+
+        $clientPath = $this->targetDir . '/Client.php';
+        self::assertFileExists($clientPath);
+        $content = file_get_contents($clientPath);
+
+        // Both specialized FQNs appear as rewritten catch targets, and the bare
+        // catch-all arm stays on the unspecialized marker name.
+        self::assertStringContainsString('catch (\\' . $notFoundFqn . ' $e)', $content);
+        self::assertStringContainsString('catch (\\' . $forbiddenFqn . ' $e)', $content);
+        self::assertStringContainsString('catch (HttpError $e)', $content);
+
+        SnapshotHash::assertMatches(
+            __DIR__ . '/../../fixture/compile/generic_exception_catch/verify/testCatchClausesRewriteToDistinctSpecializedFqns/Client.expected.php',
+            $content,
+        );
+    }
+
+    public function testAllOutputFilesAreSyntacticallyValid(): void
+    {
+        $this->compile();
+
+        $files = array_merge(
+            self::globRecursive($this->targetDir, '*.php'),
+            self::globRecursive($this->cacheDir . '/Generated', '*.php'),
+        );
+        self::assertNotEmpty($files);
+
+        foreach ($files as $file) {
+            $output = [];
+            $exit = 0;
+            exec('php -l ' . escapeshellarg($file) . ' 2>&1', $output, $exit);
+            self::assertSame(0, $exit, "Syntax error in {$file}:\n" . implode("\n", $output));
+        }
+    }
+
+    private function compile(): void
+    {
+        $compiler = $this->buildCompiler();
+        $sources = (new NativeFileFinder())
+            ->find($this->sourceDir)
+            ->filter(static fn (string $f): bool => str_ends_with($f, '.xphp'));
+        $compiler->compile($sources, $this->sourceDir, $this->targetDir, $this->cacheDir);
+    }
+
+    /**
+     * @return list<string>
+     */
+    private static function globRecursive(string $dir, string $pattern): array
+    {
+        if (!is_dir($dir)) {
+            return [];
+        }
+        $found = glob(rtrim($dir, '/') . '/' . $pattern) ?: [];
+        foreach (glob(rtrim($dir, '/') . '/*', GLOB_ONLYDIR) ?: [] as $subdir) {
+            $found = array_merge($found, self::globRecursive($subdir, $pattern));
+        }
+        return $found;
+    }
+
+    private function buildCompiler(): Compiler
+    {
+        $phpParser = (new ParserFactory())->createForHostVersion();
+        $printer = new StandardPrinter();
+        $writer = new NativeFileWriter();
+
+        return new Compiler(
+            new NativeFileReader(),
+            $writer,
+            new XphpSourceParser($phpParser),
+            new Specializer(),
+            new SpecializedClassGenerator($printer, $writer),
+            $printer,
+        );
+    }
+
+    private static function rrmdir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+        foreach (scandir($dir) as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $entry;
+            is_dir($path) ? self::rrmdir($path) : unlink($path);
+        }
+        rmdir($dir);
+    }
+}
diff --git a/test/fixture/compile/generic_exception_catch/source/Client.xphp b/test/fixture/compile/generic_exception_catch/source/Client.xphp
new file mode 100644
index 0000000..ba2aca6
--- /dev/null
+++ b/test/fixture/compile/generic_exception_catch/source/Client.xphp
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\GenericExceptionCatch;
+
+use App\GenericExceptionCatch\Errors\HttpError;
+use App\GenericExceptionCatch\Models\Forbidden;
+use App\GenericExceptionCatch\Models\NotFound;
+
+class Client
+{
+    public function raise(string $which): void
+    {
+        if ($which === 'forbidden') {
+            throw new HttpError::<Forbidden>('api key revoked');
+        }
+
+        throw new HttpError::<NotFound>('missing');
+    }
+
+    /**
+     * The generic type discriminates: a thrown `HttpError<Forbidden>` must
+     * fall through the textually-first `HttpError<NotFound>` arm and land on
+     * the `HttpError<Forbidden>` arm. Catching by generic specialization is
+     * the whole point of the fixture.
+     */
+    public function classify(string $which): string
+    {
+        try {
+            $this->raise($which);
+        } catch (HttpError<NotFound> $e) {
+            return 'not-found:' . $e->detail;
+        } catch (HttpError<Forbidden> $e) {
+            return 'forbidden:' . $e->detail;
+        }
+
+        return 'none';
+    }
+
+    /**
+     * Bare `catch (HttpError $e)` (no type args) catches any `HttpError<*>`
+     * specialization via the marker interface every specialization implements.
+     */
+    public function catchAny(string $which): string
+    {
+        try {
+            $this->raise($which);
+        } catch (HttpError $e) {
+            return $e::class;
+        }
+
+        return 'none';
+    }
+
+    /**
+     * A union of two specializations matches when the thrown error is either.
+     */
+    public function catchUnion(string $which): string
+    {
+        try {
+            $this->raise($which);
+        } catch (HttpError<NotFound> | HttpError<Forbidden> $e) {
+            return 'union:' . $e->detail;
+        }
+
+        return 'none';
+    }
+}
diff --git a/test/fixture/compile/generic_exception_catch/source/Errors/HttpError.xphp b/test/fixture/compile/generic_exception_catch/source/Errors/HttpError.xphp
new file mode 100644
index 0000000..039ee3a
--- /dev/null
+++ b/test/fixture/compile/generic_exception_catch/source/Errors/HttpError.xphp
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\GenericExceptionCatch\Errors;
+
+class HttpError<T> extends \RuntimeException
+{
+    public function __construct(public string $detail)
+    {
+        parent::__construct($detail);
+    }
+}
diff --git a/test/fixture/compile/generic_exception_catch/source/Models/Forbidden.xphp b/test/fixture/compile/generic_exception_catch/source/Models/Forbidden.xphp
new file mode 100644
index 0000000..07c5336
--- /dev/null
+++ b/test/fixture/compile/generic_exception_catch/source/Models/Forbidden.xphp
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\GenericExceptionCatch\Models;
+
+class Forbidden
+{
+}
diff --git a/test/fixture/compile/generic_exception_catch/source/Models/NotFound.xphp b/test/fixture/compile/generic_exception_catch/source/Models/NotFound.xphp
new file mode 100644
index 0000000..c3195bc
--- /dev/null
+++ b/test/fixture/compile/generic_exception_catch/source/Models/NotFound.xphp
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\GenericExceptionCatch\Models;
+
+class NotFound
+{
+}
diff --git a/test/fixture/compile/generic_exception_catch/verify/catch_runtime.php b/test/fixture/compile/generic_exception_catch/verify/catch_runtime.php
new file mode 100644
index 0000000..c04b177
--- /dev/null
+++ b/test/fixture/compile/generic_exception_catch/verify/catch_runtime.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Runtime verify for `generic_exception_catch`: a `catch` clause typed on a
+ * generic specialization (`HttpError<NotFound>` vs `HttpError<Forbidden>`)
+ * discriminates on the concrete monomorphized class, so the right arm fires.
+ *
+ * Driver contract: `$fixture` (CompiledFixture) in scope, autoload registered
+ * for `App\GenericExceptionCatch\` + the generated namespace.
+ */
+
+use App\GenericExceptionCatch\Client;
+use PHPUnit\Framework\Assert;
+use XPHP\Transpiler\Monomorphize\Registry;
+use XPHP\Transpiler\Monomorphize\TypeRef;
+
+$client = new Client();
+
+// Generic type discriminates: the Forbidden throw must skip the textually
+// FIRST `HttpError<NotFound>` arm and land on `HttpError<Forbidden>`. This is
+// the property that would silently break if catch types stopped being
+// rewritten to their distinct specialized FQNs.
+Assert::assertSame('forbidden:api key revoked', $client->classify('forbidden'));
+Assert::assertSame('not-found:missing', $client->classify('notfound'));
+
+// Bare `catch (HttpError $e)` catches any specialization via the marker
+// interface. The caught object is the concrete Forbidden specialization.
+$forbiddenFqn = Registry::generatedFqn(
+    'App\\GenericExceptionCatch\\Errors\\HttpError',
+    [new TypeRef('App\\GenericExceptionCatch\\Models\\Forbidden')],
+);
+Assert::assertSame($forbiddenFqn, $client->catchAny('forbidden'));
+
+// A union of two specializations matches either thrown error.
+Assert::assertSame('union:missing', $client->catchUnion('notfound'));
+Assert::assertSame('union:api key revoked', $client->catchUnion('forbidden'));
+
+// The specialization is a genuine Throwable subtype (so it is catchable at all)
+// AND implements the original generic name as a marker interface (so the bare
+// catch-all arm above can match it).
+Assert::assertTrue(
+    is_subclass_of($forbiddenFqn, \RuntimeException::class),
+    'specialized exception must remain a RuntimeException subtype',
+);
+Assert::assertTrue(
+    is_subclass_of($forbiddenFqn, 'App\\GenericExceptionCatch\\Errors\\HttpError'),
+    'specialized exception must implement the HttpError marker interface',
+);
diff --git a/test/fixture/compile/generic_exception_catch/verify/testCatchClausesRewriteToDistinctSpecializedFqns/Client.expected.php b/test/fixture/compile/generic_exception_catch/verify/testCatchClausesRewriteToDistinctSpecializedFqns/Client.expected.php
new file mode 100644
index 0000000..f8c75f2
--- /dev/null
+++ b/test/fixture/compile/generic_exception_catch/verify/testCatchClausesRewriteToDistinctSpecializedFqns/Client.expected.php
@@ -0,0 +1,60 @@
+<?php
+
+declare (strict_types=1);
+namespace App\GenericExceptionCatch;
+
+use App\GenericExceptionCatch\Errors\HttpError;
+use App\GenericExceptionCatch\Models\Forbidden;
+use App\GenericExceptionCatch\Models\NotFound;
+class Client
+{
+    public function raise(string $which): void
+    {
+        if ($which === 'forbidden') {
+            throw new \XPHP\Generated\App\GenericExceptionCatch\Errors\HttpError\T_06f918bacae3fd07cbcf951547a0b2cd134791ea546f4e217ed92646c23312fb('api key revoked');
+        }
+        throw new \XPHP\Generated\App\GenericExceptionCatch\Errors\HttpError\T_ecf2ea0572da7e267540a6732b45a57cd872d497de0ce6e93c5606d12dc408b8('missing');
+    }
+    /**
+     * The generic type discriminates: a thrown `HttpError<Forbidden>` must
+     * fall through the textually-first `HttpError<NotFound>` arm and land on
+     * the `HttpError<Forbidden>` arm. Catching by generic specialization is
+     * the whole point of the fixture.
+     */
+    public function classify(string $which): string
+    {
+        try {
+            $this->raise($which);
+        } catch (\XPHP\Generated\App\GenericExceptionCatch\Errors\HttpError\T_ecf2ea0572da7e267540a6732b45a57cd872d497de0ce6e93c5606d12dc408b8 $e) {
+            return 'not-found:' . $e->detail;
+        } catch (\XPHP\Generated\App\GenericExceptionCatch\Errors\HttpError\T_06f918bacae3fd07cbcf951547a0b2cd134791ea546f4e217ed92646c23312fb $e) {
+            return 'forbidden:' . $e->detail;
+        }
+        return 'none';
+    }
+    /**
+     * Bare `catch (HttpError $e)` (no type args) catches any `HttpError<*>`
+     * specialization via the marker interface every specialization implements.
+     */
+    public function catchAny(string $which): string
+    {
+        try {
+            $this->raise($which);
+        } catch (HttpError $e) {
+            return $e::class;
+        }
+        return 'none';
+    }
+    /**
+     * A union of two specializations matches when the thrown error is either.
+     */
+    public function catchUnion(string $which): string
+    {
+        try {
+            $this->raise($which);
+        } catch (\XPHP\Generated\App\GenericExceptionCatch\Errors\HttpError\T_ecf2ea0572da7e267540a6732b45a57cd872d497de0ce6e93c5606d12dc408b8|\XPHP\Generated\App\GenericExceptionCatch\Errors\HttpError\T_06f918bacae3fd07cbcf951547a0b2cd134791ea546f4e217ed92646c23312fb $e) {
+            return 'union:' . $e->detail;
+        }
+        return 'none';
+    }
+}

From 794176cfd70f43b013191c4c4a03e8ae365bf3c5 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Sun, 14 Jun 2026 23:35:42 +0200
Subject: [PATCH 2/8] docs(roadmap): roadmap cleanup

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/roadmap.md | 31 ++++++++-----------------------
 1 file changed, 8 insertions(+), 23 deletions(-)

diff --git a/docs/roadmap.md b/docs/roadmap.md
index 629a1b5..519d195 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -45,24 +45,18 @@ timeline
                 : runtime instanceof T
                 : marker interface per template
         Developer experience
-                : PSR-4 fixtures
                 : RFC-aligned call-site syntax
                 : empty turbofish for all-defaults templates
     section Next
         Editor and tooling
-                : PhpStorm syntax highlighting
-                : Language Server Protocol
-                : Composer plugin for autoload
                 : Live transpilation via stream wrapper
         Compiler ergonomics
-                : Migration hint for bare call sites
-                : PHPDoc substitution in generated bodies
                 : Source maps back to xphp lines
+    section Discovery
         Generic surface
                 : Generic type aliases
                 : Variance edges on trait-owned templates
                 : Branching narrowing precision
-    section Discovery
         Module surface
                 : internal visibility modifier
                 : composer-package boundary
@@ -182,7 +176,6 @@ upcoming one.
 
 ### Developer experience
 
-- PSR-4 fixtures.
 - RFC-aligned call-site syntax (`Name::<...>` turbofish).
 - Empty turbofish (`Name::<>`) for all-defaults templates.
 
@@ -192,27 +185,12 @@ upcoming one.
 
 ### Editor and tooling
 
-- PhpStorm syntax highlighting.
-- Language Server Protocol implementation (diagnostics, hover types,
-  goto-definition).
-- Composer plugin for autoload registration.
 - Live transpilation via stream wrapper (no build step in dev).
 
 ### Compiler ergonomics
 
-- Compile-time migration hint for bare `Name<...>(...)` call sites
-  that point users at the `::<...>` turbofish.
-- PHPDoc substitution in generated bodies so generated `.php` reads
-  naturally.
 - Source maps (stack traces back to `.xphp` lines).
 
-### Generic surface
-
-- Generic type aliases (e.g. `type Pair<A, B> = ...`).
-- Variance edges on trait-owned templates.
-- Branching narrowing precision: today conservatively de-specializes
-  when arms disagree; will track unions with runtime dispatch instead.
-
 ---
 
 ## Discovery
@@ -223,6 +201,13 @@ implementation knobs are still being settled. Treat each Discovery
 entry as a starting point for community discussion, not a guarantee
 to ship.
 
+### Generic surface
+
+- Generic type aliases (e.g. `type Pair<A, B> = ...`).
+- Variance edges on trait-owned templates.
+- Branching narrowing precision: today conservatively de-specializes
+  when arms disagree; will track unions with runtime dispatch instead.
+
 ### Module surface
 
 - **`internal` visibility modifier**: replace PHPDoc `@internal` hints

From 2f4cdb8ddde8ffc9503ab30d40584bbe0232610c Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Mon, 15 Jun 2026 23:34:55 +0200
Subject: [PATCH 3/8] test(php85): cover PHP 8.5 pipe operator on a dedicated
 8.5 runtime

The transpiler passes plain PHP through unchanged, so `|>` support hinges
purely on the parser's target version. Keep ApplicationConsole on
createForHostVersion() (supported runtime is ^8.4): the host accepts 8.4
syntax on 8.4 and 8.5 syntax on 8.5, with no need to force a newer grammar.

Lock the pipe operator with an integration test that mirrors the production
wiring and round-trips `|>` (alone and beside a generic specialization).
Tag it `@group php85` + `#[RequiresPhp('>= 8.5.0')]` so it skips on 8.4 and
runs only under an 8.5 runtime.

- Makefile: test/unit excludes php85; new test/unit/php85 runs only it.
- CI: phpunit job is now a matrix (8.4 -> full suite minus php85,
  8.5 -> only php85).
- CONTRIBUTING: document the split and the new target.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/ci-core.yml                 |  20 ++-
 CONTRIBUTING.md                               |  12 +-
 Makefile                                      |  12 +-
 src/Console/ApplicationConsole.php            |   5 +
 .../PipeOperatorIntegrationTest.php           | 159 ++++++++++++++++++
 5 files changed, 200 insertions(+), 8 deletions(-)
 create mode 100644 test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php

diff --git a/.github/workflows/ci-core.yml b/.github/workflows/ci-core.yml
index 94e6fde..5115e79 100644
--- a/.github/workflows/ci-core.yml
+++ b/.github/workflows/ci-core.yml
@@ -15,15 +15,27 @@ concurrency:
 
 jobs:
   phpunit:
-    name: PHPUnit
+    # 8.4 is the supported/default runtime and runs the full suite minus the
+    # `php85` group; a dedicated 8.5 container runs only that group, which
+    # covers syntax (e.g. the pipe operator `|>`) that the host-version
+    # parser can only tokenize on PHP 8.5.
+    name: PHPUnit (PHP ${{ matrix.php }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - php: '8.4'
+            target: test/unit
+          - php: '8.5'
+            target: test/unit/php85
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup PHP 8.4
+      - name: Setup PHP ${{ matrix.php }}
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.4'
+          php-version: ${{ matrix.php }}
           extensions: dom, json, mbstring, tokenizer
           coverage: none
           tools: composer:v2
@@ -32,7 +44,7 @@ jobs:
         uses: ramsey/composer-install@v3
 
       - name: Run PHPUnit
-        run: make test/unit
+        run: make ${{ matrix.target }}
 
   phpstan:
     name: PHPStan
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0ca9e17..8c24a55 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,10 +3,16 @@
 ## Test
 
 ```bash
-make test/unit       # PHPUnit
-make test/mutation   # Infection, MSI under a 95 % gate
+make test/unit        # PHPUnit on the default PHP 8.4 runtime
+make test/unit/php85  # only tests tagged `@group php85`; needs a PHP 8.5 runtime
+make test/mutation    # Infection, MSI under a 95 % gate
 ```
 
-CI gates every PR on both targets. `infection.json5` carries a curated set
+The supported runtime is PHP `^8.4`. Tests that exercise newer-PHP syntax
+(e.g. the 8.5 pipe operator) are tagged `@group php85`; `make test/unit`
+excludes them and they self-skip via `#[RequiresPhp]` off an 8.5 host. CI
+runs them in a dedicated PHP 8.5 job.
+
+CI gates every PR on these targets. `infection.json5` carries a curated set
 of per-mutator `ignore` rules for genuinely-equivalent / defensive
 mutations so the report only surfaces real test gaps.
\ No newline at end of file
diff --git a/Makefile b/Makefile
index e323a9a..3288b02 100644
--- a/Makefile
+++ b/Makefile
@@ -7,8 +7,18 @@
 # targets here.
 
 .PHONY: test/unit
+# Default runtime is PHP 8.4 (composer requires ^8.4). Tests exercising
+# newer-PHP syntax are tagged `@group php85` and excluded here; they run
+# on an 8.5 runtime via `make test/unit/php85`.
 test/unit:
-	php vendor/bin/phpunit
+	php vendor/bin/phpunit --exclude-group php85
+
+.PHONY: test/unit/php85
+# Runs only the PHP 8.5-specific syntax tests (e.g. the pipe operator).
+# Requires a PHP 8.5 runtime -- CI uses a dedicated 8.5 container; on 8.4
+# these self-skip via #[RequiresPhp].
+test/unit/php85:
+	php vendor/bin/phpunit --group php85
 
 .PHONY: lint/phpstan
 # Static analysis at level 7. Memory limit lifted because deep generic
diff --git a/src/Console/ApplicationConsole.php b/src/Console/ApplicationConsole.php
index a395802..bed4708 100644
--- a/src/Console/ApplicationConsole.php
+++ b/src/Console/ApplicationConsole.php
@@ -27,6 +27,11 @@ public function __construct(
     ) {
         parent::__construct('xphp');
 
+        // Parse against the host PHP version: xphp's supported runtime is
+        // ^8.4 (see composer.json), so on 8.4 the transpiler accepts 8.4
+        // syntax and on an 8.5 host it transparently accepts 8.5 syntax such
+        // as the pipe operator `|>`. Newer-syntax behaviour is locked by
+        // tests tagged `@group php85`, which run only under an 8.5 runtime.
         $phpParser = (new ParserFactory())->createForHostVersion();
         $printer = new StandardPrinter();
 
diff --git a/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php b/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php
new file mode 100644
index 0000000..af95adf
--- /dev/null
+++ b/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php
@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace XPHP\Transpiler\Monomorphize;
+
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter\Standard as StandardPrinter;
+use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\Attributes\RequiresPhp;
+use PHPUnit\Framework\TestCase;
+use XPHP\FileSystem\FileFinder\NativeFileFinder;
+use XPHP\FileSystem\FileReader\NativeFileReader;
+use XPHP\FileSystem\FileWriter\NativeFileWriter;
+
+/**
+ * Locks in pass-through support for the PHP 8.5 pipe operator (`|>`).
+ *
+ * xphp only owns generic syntax; everything else is plain PHP that must
+ * survive the parse -> rewrite -> pretty-print round-trip untouched. The
+ * production parser uses `createForHostVersion()` (xphp's runtime is ^8.4),
+ * so the `|>` token only lexes when the transpiler itself runs on PHP 8.5+.
+ *
+ * This case therefore requires an 8.5 runtime: it is tagged `@group php85`
+ * so the default 8.4 CI job excludes it, and `#[RequiresPhp]` makes it skip
+ * rather than error if ever run on an older PHP. The dedicated 8.5 CI
+ * container runs exactly this group.
+ */
+#[Group('php85')]
+#[RequiresPhp('>= 8.5.0')]
+final class PipeOperatorIntegrationTest extends TestCase
+{
+    private string $sourceDir;
+    private string $targetDir;
+    private string $cacheDir;
+
+    protected function setUp(): void
+    {
+        $workDir = sys_get_temp_dir() . '/xphp-pipe-' . uniqid('', true);
+        $this->sourceDir = $workDir . '/src';
+        $this->targetDir = $workDir . '/dist';
+        $this->cacheDir = $workDir . '/.xphp-cache';
+        mkdir($this->sourceDir, 0o755, true);
+    }
+
+    protected function tearDown(): void
+    {
+        $workDir = \dirname($this->sourceDir);
+        if (is_dir($workDir)) {
+            self::rrmdir($workDir);
+        }
+    }
+
+    public function testPipeOperatorRoundTripsThroughTranspiler(): void
+    {
+        $this->writeSource('pipe.xphp', <<<'PHP'
+        <?php
+        namespace App;
+        $slug = $title |> trim(...) |> strtolower(...);
+        PHP);
+
+        $this->compile();
+
+        $out = $this->readOutput('pipe.php');
+        self::assertStringContainsString('|>', $out);
+        self::assertStringContainsString('$slug = $title |> trim(...) |> strtolower(...);', $out);
+        $this->assertValidPhp($out);
+    }
+
+    public function testPipeOperatorCoexistsWithGenericSpecialization(): void
+    {
+        // The pipe lives right beside a turbofish call site, so this also proves
+        // xphp's generic byte-offset rewriting does not disturb the `|>` tokens.
+        $this->writeSource('box.xphp', <<<'PHP'
+        <?php
+        namespace App;
+
+        final class Box<T>
+        {
+            public function __construct(public T $value) {}
+        }
+
+        $box = new Box::<string>('  HELLO  ');
+        $slug = $box->value |> trim(...) |> strtolower(...);
+        PHP);
+
+        $this->compile();
+
+        $out = $this->readOutput('box.php');
+        // Pipe survives untouched.
+        self::assertStringContainsString('$slug = $box->value |> trim(...) |> strtolower(...);', $out);
+        // Generic was actually specialized: the turbofish call site is rewritten
+        // to a generated, monomorphized FQN and the template syntax is gone.
+        self::assertStringContainsString('XPHP\Generated\App\Box\T_', $out);
+        self::assertStringNotContainsString('Box::<', $out);
+        $this->assertValidPhp($out);
+    }
+
+    private function writeSource(string $name, string $code): void
+    {
+        file_put_contents($this->sourceDir . '/' . $name, $code);
+    }
+
+    private function readOutput(string $name): string
+    {
+        $path = $this->targetDir . '/' . $name;
+        self::assertFileExists($path);
+
+        return file_get_contents($path) ?: '';
+    }
+
+    private function assertValidPhp(string $code): void
+    {
+        // The emitted PHP must itself re-parse on this (8.5) runtime.
+        $parser = (new ParserFactory())->createForHostVersion();
+        self::assertNotNull(
+            $parser->parse($code),
+            'Transpiled output is not valid PHP',
+        );
+    }
+
+    private function compile(): void
+    {
+        // Mirror production wiring (ApplicationConsole): host-version parser.
+        // On the 8.5 runtime this group runs under, that tokenizes `|>`.
+        $phpParser = (new ParserFactory())->createForHostVersion();
+        $printer = new StandardPrinter();
+        $writer = new NativeFileWriter();
+
+        $compiler = new Compiler(
+            new NativeFileReader(),
+            $writer,
+            new XphpSourceParser($phpParser),
+            new Specializer(),
+            new SpecializedClassGenerator($printer, $writer),
+            $printer,
+        );
+
+        $sources = (new NativeFileFinder())->find($this->sourceDir)
+            ->filter(static fn (string $f): bool => str_ends_with($f, '.xphp'));
+
+        $compiler->compile($sources, $this->sourceDir, $this->targetDir, $this->cacheDir);
+    }
+
+    private static function rrmdir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+        foreach (scandir($dir) ?: [] as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $entry;
+            is_dir($path) ? self::rrmdir($path) : unlink($path);
+        }
+        rmdir($dir);
+    }
+}

From c4f1d123d48acd0a40eb3b9ff1337840a42e6a82 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Mon, 15 Jun 2026 23:38:06 +0200
Subject: [PATCH 4/8] build(docker): add php85 container for the 8.5 test group

Lets contributors without a local PHP 8.5 run the `@group php85` tests:
`docker compose run --rm php85 make test/unit/php85`. The service builds a
lean php:8.5-cli-alpine image (composer + git/unzip/make, no coverage
drivers since those tests run coverage-off). Verified green on PHP 8.5.7.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .docker/php85.Dockerfile | 12 ++++++++++++
 CONTRIBUTING.md          |  6 ++++++
 docker-compose.yml       |  9 +++++++++
 3 files changed, 27 insertions(+)
 create mode 100644 .docker/php85.Dockerfile

diff --git a/.docker/php85.Dockerfile b/.docker/php85.Dockerfile
new file mode 100644
index 0000000..766b38b
--- /dev/null
+++ b/.docker/php85.Dockerfile
@@ -0,0 +1,12 @@
+FROM php:8.5-cli-alpine
+
+# Dedicated runtime for the `@group php85` tests -- syntax (e.g. the 8.5
+# pipe operator `|>`) that the host-version parser can only tokenize on
+# PHP 8.5.  These run with coverage disabled, so no xdebug/pcov here:
+# just composer plus the tools composer + `make test/unit/php85` need.
+COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer
+
+RUN apk add --no-cache \
+    git \
+    unzip \
+    make
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8c24a55..84b9757 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,6 +13,12 @@ The supported runtime is PHP `^8.4`. Tests that exercise newer-PHP syntax
 excludes them and they self-skip via `#[RequiresPhp]` off an 8.5 host. CI
 runs them in a dedicated PHP 8.5 job.
 
+No PHP 8.5 locally? Run them in the bundled 8.5 container:
+
+```bash
+docker compose run --rm php85 make test/unit/php85
+```
+
 CI gates every PR on these targets. `infection.json5` carries a curated set
 of per-mutator `ignore` rules for genuinely-equivalent / defensive
 mutations so the report only surfaces real test gaps.
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
index ab29a5d..31851af 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -8,6 +8,15 @@ services:
     environment:
       XDEBUG_MODE: coverage,develop
 
+  # PHP 8.5 runtime for the `@group php85` tests. Run them with:
+  #   docker compose run --rm php85 make test/unit/php85
+  php85:
+    build:
+      dockerfile: .docker/php85.Dockerfile
+    working_dir: /opt/app
+    volumes:
+      - ./:/opt/app
+
   xphp:
     extends:
       service: php

From ede6fc9e7e934e756082705ef68d495f01530e34 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Mon, 15 Jun 2026 23:48:20 +0200
Subject: [PATCH 5/8] test(php85): convert pipe-operator test to the
 fixture+snapshot convention

Replace the inline-source pipe test with a tracked `pipe_operator` fixture
(Box.xphp generic + Use.xphp exercising a standalone `|>` chain and one
beside a turbofish call site), asserted via SnapshotHash like the other
compile fixtures. The whole-file snapshot locks the emitted bytes -- pipe
operator preserved verbatim, turbofish rewritten to the monomorphized FQN.

Still `@group php85` + `#[RequiresPhp('>= 8.5.0')]`: skips on 8.4, runs on
8.5. Verified green in the php85 container on PHP 8.5.7 (real comparison,
not update mode) and skipping cleanly on the 8.4 host.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../PipeOperatorIntegrationTest.php           | 113 +++++++-----------
 .../compile/pipe_operator/source/Box.xphp     |  12 ++
 .../compile/pipe_operator/source/Use.xphp     |  15 +++
 .../Use.expected.php                          |  13 ++
 4 files changed, 82 insertions(+), 71 deletions(-)
 create mode 100644 test/fixture/compile/pipe_operator/source/Box.xphp
 create mode 100644 test/fixture/compile/pipe_operator/source/Use.xphp
 create mode 100644 test/fixture/compile/pipe_operator/verify/testPipeOperatorFixtureCompiles/Use.expected.php

diff --git a/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php b/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php
index af95adf..64bf328 100644
--- a/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php
+++ b/test/Transpiler/Monomorphize/PipeOperatorIntegrationTest.php
@@ -9,12 +9,15 @@
 use PHPUnit\Framework\Attributes\Group;
 use PHPUnit\Framework\Attributes\RequiresPhp;
 use PHPUnit\Framework\TestCase;
+use RuntimeException;
 use XPHP\FileSystem\FileFinder\NativeFileFinder;
 use XPHP\FileSystem\FileReader\NativeFileReader;
 use XPHP\FileSystem\FileWriter\NativeFileWriter;
+use XPHP\TestSupport\SnapshotHash;
 
 /**
- * Locks in pass-through support for the PHP 8.5 pipe operator (`|>`).
+ * Locks in pass-through support for the PHP 8.5 pipe operator (`|>`) via the
+ * tracked `pipe_operator` fixture.
  *
  * xphp only owns generic syntax; everything else is plain PHP that must
  * survive the parse -> rewrite -> pretty-print round-trip untouched. The
@@ -24,102 +27,75 @@
  * This case therefore requires an 8.5 runtime: it is tagged `@group php85`
  * so the default 8.4 CI job excludes it, and `#[RequiresPhp]` makes it skip
  * rather than error if ever run on an older PHP. The dedicated 8.5 CI
- * container runs exactly this group.
+ * container runs exactly this group. Locally:
+ *   docker compose run --rm php85 make test/unit/php85
  */
 #[Group('php85')]
 #[RequiresPhp('>= 8.5.0')]
 final class PipeOperatorIntegrationTest extends TestCase
 {
     private string $sourceDir;
+    private string $workDir;
     private string $targetDir;
     private string $cacheDir;
 
     protected function setUp(): void
     {
-        $workDir = sys_get_temp_dir() . '/xphp-pipe-' . uniqid('', true);
-        $this->sourceDir = $workDir . '/src';
-        $this->targetDir = $workDir . '/dist';
-        $this->cacheDir = $workDir . '/.xphp-cache';
-        mkdir($this->sourceDir, 0o755, true);
+        $this->sourceDir = realpath(__DIR__ . '/../../fixture/compile/pipe_operator/source')
+            ?: throw new RuntimeException('Fixture not found');
+        $this->workDir = sys_get_temp_dir() . '/xphp-pipe-' . uniqid('', true);
+        $this->targetDir = $this->workDir . '/dist';
+        $this->cacheDir = $this->workDir . '/.xphp-cache';
+        mkdir($this->workDir, 0o755, true);
     }
 
     protected function tearDown(): void
     {
-        $workDir = \dirname($this->sourceDir);
-        if (is_dir($workDir)) {
-            self::rrmdir($workDir);
+        if (is_dir($this->workDir)) {
+            self::rrmdir($this->workDir);
         }
     }
 
-    public function testPipeOperatorRoundTripsThroughTranspiler(): void
+    public function testPipeOperatorFixtureCompiles(): void
     {
-        $this->writeSource('pipe.xphp', <<<'PHP'
-        <?php
-        namespace App;
-        $slug = $title |> trim(...) |> strtolower(...);
-        PHP);
-
-        $this->compile();
-
-        $out = $this->readOutput('pipe.php');
-        self::assertStringContainsString('|>', $out);
-        self::assertStringContainsString('$slug = $title |> trim(...) |> strtolower(...);', $out);
-        $this->assertValidPhp($out);
-    }
+        $compiler = $this->buildCompiler();
 
-    public function testPipeOperatorCoexistsWithGenericSpecialization(): void
-    {
-        // The pipe lives right beside a turbofish call site, so this also proves
-        // xphp's generic byte-offset rewriting does not disturb the `|>` tokens.
-        $this->writeSource('box.xphp', <<<'PHP'
-        <?php
-        namespace App;
-
-        final class Box<T>
-        {
-            public function __construct(public T $value) {}
-        }
+        $sources = (new NativeFileFinder())
+            ->find($this->sourceDir)
+            ->filter(static fn (string $f): bool => str_ends_with($f, '.xphp'));
 
-        $box = new Box::<string>('  HELLO  ');
-        $slug = $box->value |> trim(...) |> strtolower(...);
-        PHP);
+        $result = $compiler->compile($sources, $this->sourceDir, $this->targetDir, $this->cacheDir);
 
-        $this->compile();
+        self::assertSame(2, $result->sourceCount, 'expected Box.xphp + Use.xphp');
+        self::assertSame(1, $result->generatedCount, 'expected one specialization: Box<string>');
 
-        $out = $this->readOutput('box.php');
-        // Pipe survives untouched.
-        self::assertStringContainsString('$slug = $box->value |> trim(...) |> strtolower(...);', $out);
-        // Generic was actually specialized: the turbofish call site is rewritten
-        // to a generated, monomorphized FQN and the template syntax is gone.
-        self::assertStringContainsString('XPHP\Generated\App\Box\T_', $out);
-        self::assertStringNotContainsString('Box::<', $out);
-        $this->assertValidPhp($out);
-    }
+        $useFile = $this->targetDir . '/Use.php';
+        self::assertFileExists($useFile);
+        $useContent = file_get_contents($useFile);
 
-    private function writeSource(string $name, string $code): void
-    {
-        file_put_contents($this->sourceDir . '/' . $name, $code);
-    }
+        // Pipe survives verbatim -- both the standalone chain and the one
+        // sitting right next to the rewritten turbofish call site.
+        self::assertStringContainsString('$slug = $title |> trim(...) |> strtolower(...);', $useContent);
+        self::assertStringContainsString('$shout = $box->value |> trim(...) |> strtoupper(...);', $useContent);
 
-    private function readOutput(string $name): string
-    {
-        $path = $this->targetDir . '/' . $name;
-        self::assertFileExists($path);
+        // Generic was actually specialized: turbofish rewritten to the
+        // monomorphized FQN, template syntax gone.
+        self::assertStringContainsString('XPHP\Generated\App\PipeOperator\Box\T_', $useContent);
+        self::assertStringNotContainsString('Box::<', $useContent);
 
-        return file_get_contents($path) ?: '';
-    }
-
-    private function assertValidPhp(string $code): void
-    {
         // The emitted PHP must itself re-parse on this (8.5) runtime.
-        $parser = (new ParserFactory())->createForHostVersion();
         self::assertNotNull(
-            $parser->parse($code),
+            (new ParserFactory())->createForHostVersion()->parse($useContent),
             'Transpiled output is not valid PHP',
         );
+
+        // Whole-file snapshot (hash segments normalized) locks the exact
+        // emitted bytes, including pipe-operator formatting.
+        $snapshotDir = __DIR__ . '/../../fixture/compile/pipe_operator/verify/testPipeOperatorFixtureCompiles';
+        SnapshotHash::assertMatches($snapshotDir . '/Use.expected.php', $useContent);
     }
 
-    private function compile(): void
+    private function buildCompiler(): Compiler
     {
         // Mirror production wiring (ApplicationConsole): host-version parser.
         // On the 8.5 runtime this group runs under, that tokenizes `|>`.
@@ -127,7 +103,7 @@ private function compile(): void
         $printer = new StandardPrinter();
         $writer = new NativeFileWriter();
 
-        $compiler = new Compiler(
+        return new Compiler(
             new NativeFileReader(),
             $writer,
             new XphpSourceParser($phpParser),
@@ -135,11 +111,6 @@ private function compile(): void
             new SpecializedClassGenerator($printer, $writer),
             $printer,
         );
-
-        $sources = (new NativeFileFinder())->find($this->sourceDir)
-            ->filter(static fn (string $f): bool => str_ends_with($f, '.xphp'));
-
-        $compiler->compile($sources, $this->sourceDir, $this->targetDir, $this->cacheDir);
     }
 
     private static function rrmdir(string $dir): void
diff --git a/test/fixture/compile/pipe_operator/source/Box.xphp b/test/fixture/compile/pipe_operator/source/Box.xphp
new file mode 100644
index 0000000..7237915
--- /dev/null
+++ b/test/fixture/compile/pipe_operator/source/Box.xphp
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\PipeOperator;
+
+final class Box<T>
+{
+    public function __construct(public T $value)
+    {
+    }
+}
diff --git a/test/fixture/compile/pipe_operator/source/Use.xphp b/test/fixture/compile/pipe_operator/source/Use.xphp
new file mode 100644
index 0000000..ec46284
--- /dev/null
+++ b/test/fixture/compile/pipe_operator/source/Use.xphp
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\PipeOperator;
+
+// Pure pass-through: the PHP 8.5 pipe operator must survive transpilation
+// untouched -- xphp owns generic syntax only, everything else is plain PHP.
+$slug = $title |> trim(...) |> strtolower(...);
+
+// Pipe coexists with a generic specialization: the turbofish call site gets
+// rewritten to the monomorphized FQN while the |> tokens beside it are left
+// intact (proves the generic byte-offset rewriting doesn't disturb them).
+$box = new Box::<string>('  HELLO  ');
+$shout = $box->value |> trim(...) |> strtoupper(...);
diff --git a/test/fixture/compile/pipe_operator/verify/testPipeOperatorFixtureCompiles/Use.expected.php b/test/fixture/compile/pipe_operator/verify/testPipeOperatorFixtureCompiles/Use.expected.php
new file mode 100644
index 0000000..a4f8a21
--- /dev/null
+++ b/test/fixture/compile/pipe_operator/verify/testPipeOperatorFixtureCompiles/Use.expected.php
@@ -0,0 +1,13 @@
+<?php
+
+declare (strict_types=1);
+namespace App\PipeOperator;
+
+// Pure pass-through: the PHP 8.5 pipe operator must survive transpilation
+// untouched -- xphp owns generic syntax only, everything else is plain PHP.
+$slug = $title |> trim(...) |> strtolower(...);
+// Pipe coexists with a generic specialization: the turbofish call site gets
+// rewritten to the monomorphized FQN while the |> tokens beside it are left
+// intact (proves the generic byte-offset rewriting doesn't disturb them).
+$box = new \XPHP\Generated\App\PipeOperator\Box\T_473287f8298dba7163a897908958f7c0eae733e25d2e027992ea2edc9bed2fa8('  HELLO  ');
+$shout = $box->value |> trim(...) |> strtoupper(...);

From b2ef32678513013cf73b363722207b54b57d3345 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Tue, 16 Jun 2026 00:06:43 +0200
Subject: [PATCH 6/8] docs: fix broken README example, wrong cache path, and
 document generic catch + 8.5 pass-through

Correctness fixes (all verified by compiling/running the snippets):
- README: the flagship Collection<T> example used a variadic promoted
  property (`public T ...$items`), which PHP rejects ("Cannot declare
  variadic promoted property") -- the headline snippet never ran.
  Replace with an add()/first() shape that compiles and prints "Alice".
- how-it-works: the on-disk cache path is `<cache>/Generated/...`, not
  `XPHP/Generated/...` (XPHP\Generated\ is only the namespace). Fix the
  prose and the mermaid node; they contradicted the file's own Stage 5.
- pseudo-types: "See also" cited box_generic as using `self` (it uses
  `T`); point at the real self/static fixtures instead.

Coverage gaps:
- New docs/syntax/exceptions.md: generic exceptions and catch by
  specialization (turbofish throw, per-specialization arms, bare marker
  catch, union catch), with a tested fixture reference. Linked from the
  syntax index table and quick-reference card.
- caveats: document that newer-PHP syntax (e.g. the 8.5 pipe operator)
  needs a host runtime that can parse it, since the parser uses the host
  PHP version.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md                   |  8 ++-
 docs/caveats.md             | 32 ++++++++++++
 docs/guides/how-it-works.md |  7 +--
 docs/syntax/exceptions.md   | 98 +++++++++++++++++++++++++++++++++++++
 docs/syntax/index.md        |  8 +++
 docs/syntax/pseudo-types.md |  5 +-
 6 files changed, 151 insertions(+), 7 deletions(-)
 create mode 100644 docs/syntax/exceptions.md

diff --git a/README.md b/README.md
index f318ffe..1d4ee90 100644
--- a/README.md
+++ b/README.md
@@ -117,14 +117,18 @@ Write a generic class and use it:
 namespace App;
 
 class Collection<T> {
-    public function __construct(public T ...$items) {}
+    private array $items = [];
+
+    public function add(T $item): void { $this->items[] = $item; }
     public function first(): ?T { return $this->items[0] ?? null; }
 }
 
 // src/Use.xphp
 namespace App;
 
-$users = new Collection::<User>(new User('Alice'), new User('Bob'));
+$users = new Collection::<User>();
+$users->add(new User('Alice'));
+$users->add(new User('Bob'));
 echo $users->first()->name;
 ```
 
diff --git a/docs/caveats.md b/docs/caveats.md
index ce37261..4799252 100644
--- a/docs/caveats.md
+++ b/docs/caveats.md
@@ -493,3 +493,35 @@ class TempContainer<T> {
 }
 $x = new TempContainer::<User>();
 ```
+
+## Newer PHP syntax needs a matching host runtime
+
+### ❌ What doesn't work
+
+Running the transpiler on PHP 8.4 over a source file that uses PHP 8.5
+syntax — for example the pipe operator:
+
+```php
+$slug = $title |> trim(...) |> strtolower(...);
+```
+
+```
+Syntax error, unexpected '>'
+```
+
+### Why
+
+xphp owns only the generic syntax; everything else is plain PHP. It
+parses your source with `nikic/php-parser` configured for the **host**
+PHP version (the one running the transpiler). On PHP 8.4 the lexer
+can't tokenize 8.5-only syntax like `|>`, so the parse fails before
+specialization even begins. There's nothing generic about the line —
+it just never reaches the host parser's grammar.
+
+### ✅ Workaround
+
+Run the transpiler on a PHP version that can parse your syntax — e.g.
+PHP 8.5 for the pipe operator. Plain (non-generic) code, including
+newer-PHP syntax, passes straight through untouched. Note the emitted
+PHP still requires a runtime that supports those features to *execute*;
+the supported floor for xphp itself is PHP 8.4 (`composer.json`).
diff --git a/docs/guides/how-it-works.md b/docs/guides/how-it-works.md
index d9ad767..3452aee 100644
--- a/docs/guides/how-it-works.md
+++ b/docs/guides/how-it-works.md
@@ -22,8 +22,9 @@ defaults to `dist` and `[cache-dir]` defaults to `.xphp-cache`. The data flows t
 turn into AST, the AST populates a Registry and a TypeHierarchy, a
 fixed-point loop expands every concrete instantiation into a specialized
 class file, and finally the rewritten user code lands in the target
-directory while specialized classes land in a cache directory under
-`XPHP\Generated\<template>\T_<hash>.php`.
+directory while specialized classes land in a cache directory at
+`<cache-dir>/Generated/<template>/T_<hash>.php` (autoloaded under the
+`XPHP\Generated\` namespace).
 
 > The code's internal labels (`Phase 0`, `Phase 1a`, `Phase 1b.i`,
 > `Phase 1b.ii`, `Phase 2`, `Phase 2.5`, `Phase 3`, `Phase 4`,
@@ -45,7 +46,7 @@ flowchart TD
     Spec --> Collector
     Loop -- no --> Rewriter["CallSiteRewriter<br/>rewrite Names + emit markers"]
     Rewriter --> Emitter["SpecializedClassGenerator<br/>+ FileWriter"]
-    Emitter --> Files["target/*.php<br/>cache/XPHP/Generated/.../T_&lt;hash&gt;.php"]
+    Emitter --> Files["target/*.php<br/>cache/Generated/.../T_&lt;hash&gt;.php"]
 ```
 
 The same lifecycle as a sequence diagram, showing call order between
diff --git a/docs/syntax/exceptions.md b/docs/syntax/exceptions.md
new file mode 100644
index 0000000..d7c74e0
--- /dev/null
+++ b/docs/syntax/exceptions.md
@@ -0,0 +1,98 @@
+# Generic exceptions and catch
+
+A generic class can extend an exception type, and `catch` clauses can
+discriminate between its specializations. Because each instantiation is
+its own real class at runtime, `catch (HttpError<NotFound> $e)` catches
+*only* that specialization — the type system carries through to control
+flow.
+
+## Example
+
+```php
+<?php
+declare(strict_types=1);
+
+namespace App;
+
+class HttpError<T> extends \RuntimeException {
+    public function __construct(public string $detail) {
+        parent::__construct($detail);
+    }
+}
+
+function raise(string $which): void {
+    if ($which === 'forbidden') {
+        throw new HttpError::<Forbidden>('api key revoked');
+    }
+    throw new HttpError::<NotFound>('missing');
+}
+
+try {
+    raise($which);
+} catch (HttpError<NotFound> $e) {
+    return 'not-found:' . $e->detail;
+} catch (HttpError<Forbidden> $e) {
+    return 'forbidden:' . $e->detail;
+}
+```
+
+## What gets emitted
+
+`throw new HttpError::<Forbidden>(...)` uses [turbofish](turbofish.md)
+like any other instantiation, and each `catch` arm rewrites to the
+specialization's generated FQN — so the arms stay distinct in the
+emitted PHP:
+
+```php
+try {
+    raise($which);
+} catch (\XPHP\Generated\App\HttpError\T_<hash-of-NotFound> $e) {
+    return 'not-found:' . $e->detail;
+} catch (\XPHP\Generated\App\HttpError\T_<hash-of-Forbidden> $e) {
+    return 'forbidden:' . $e->detail;
+}
+```
+
+## Catching any specialization
+
+A bare `catch (HttpError $e)` — no type arguments — catches *every*
+`HttpError<...>` via the marker interface that every specialization
+implements. It is left untouched in the emit:
+
+```php
+} catch (HttpError $e) {
+    return $e::class; // the concrete specialized class name
+}
+```
+
+## Union catch
+
+A catch arm may union specializations; it lowers to a native PHP union
+of the generated FQNs:
+
+```php
+} catch (HttpError<NotFound> | HttpError<Forbidden> $e) {
+    return 'union:' . $e->detail;
+}
+```
+
+## Rules
+
+- The `catch` clause uses bare angle brackets (`HttpError<NotFound>`),
+  like every other type-hint position — not the `::<>`
+  [turbofish](turbofish.md), which is reserved for call sites
+  (`throw new HttpError::<NotFound>(...)`).
+- Arms are ordered as written; a thrown `HttpError<Forbidden>` falls
+  through a preceding `HttpError<NotFound>` arm because they are
+  genuinely different runtime classes.
+- Bare `catch (HttpError $e)` matches any specialization via the marker
+  interface; type-argumented arms match exactly one.
+- Specializations are only generated for type arguments that actually
+  appear in the program (`throw`, `new`, type hints). Catching a
+  specialization that is never instantiated catches nothing.
+
+## See also
+
+- Test fixture: `test/fixture/compile/generic_exception_catch/`
+- Related: [classes and interfaces](classes-and-interfaces.md),
+  [turbofish](turbofish.md)
diff --git a/docs/syntax/index.md b/docs/syntax/index.md
index c4d9166..ab2c1d8 100644
--- a/docs/syntax/index.md
+++ b/docs/syntax/index.md
@@ -21,6 +21,7 @@ first.
 | [Pseudo-types](pseudo-types.md) | `self<T>` / `static<T>` / `parent<T>` and the `new self::<T>(...)` form |
 | [Turbofish](turbofish.md) | All four call-site shapes plus variable and empty turbofish |
 | [Array sugar](array-sugar.md) | `T[]` shorthand |
+| [Exceptions](exceptions.md) | Generic exceptions, `catch (HttpError<NotFound> $e)`, bare and union catch |
 
 ## Quick reference card
 
@@ -72,6 +73,13 @@ class Container<T> {
     public function with(T $n): self<T> { return new self::<T>($n); }
 }
 return new self::<T>($x);                 // constructor turbofish
+
+// Generic exceptions + catch by specialization
+class HttpError<T> extends \RuntimeException {}
+throw new HttpError::<NotFound>('missing');
+try { /* ... */ }
+catch (HttpError<NotFound> $e) {}         // one specialization
+catch (HttpError $e) {}                    // any specialization (marker)
 ```
 
 For the runtime side -- how marker interfaces work, how specialized
diff --git a/docs/syntax/pseudo-types.md b/docs/syntax/pseudo-types.md
index bbe14d9..3a9ee16 100644
--- a/docs/syntax/pseudo-types.md
+++ b/docs/syntax/pseudo-types.md
@@ -97,7 +97,8 @@ pseudo-type, and the receiver short-circuits.
 
 ## See also
 
-- Test fixture: `test/fixture/compile/box_generic/` (uses `self` in
-  return positions)
+- Test fixtures: `test/fixture/compile/generic_method_new_self_turbofish/`,
+  `generic_method_self_with_type_args/`, and
+  `generic_method_new_static_turbofish/` (exercise `self` / `static`)
 - Related: [classes and interfaces](classes-and-interfaces.md),
   [turbofish](turbofish.md)

From 6aa8d72f7b616040d2227733c94645e050e313f5 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Wed, 17 Jun 2026 18:07:31 +0000
Subject: [PATCH 7/8] fix(monomorphize): fully-qualify bare imported names in
 specialized classes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A specialized generic is lifted into a fresh XPHP\Generated\... namespace, but
bare class/interface names that relied on the source file's `use` imports
(extends Countable, implements IteratorAggregate, new ArrayIterator,
catch (SomeException), typed properties/params/returns) were copied verbatim.
In the relocated namespace they resolved to a non-existent
XPHP\Generated\...\<Name> and threw "Interface not found" at autoload time —
silent at compile time, fatal on first load. Only type-param and generic-args
names were ever fully-qualified; plain class references were neither.

Resolve at parse time, swap on the clone:
- XphpSourceParser::resolveAndAttach now tags bare class-name Names in
  class-name positions (extends/implements/new/instanceof/catch/static-access/
  param·return·property·const type hints) with their resolved FQN in a new
  ATTR_RESOLVED_FQN attribute, reusing the existing NamespaceContext. The node
  is not mutated, so emitted user files stay byte-identical. A shouldQualify
  guard skips already-FQ names, generic-marker names, enclosing type-params and
  scalars/self/parent/static; function and const Names are never visited, so
  PHP's global fallback is preserved.
- Specializer fully-qualifies a tagged Name only on the relocated clone, so the
  generated class references every non-generic symbol by FQN and loads cleanly.

Regression coverage: builtin_interface_via_use fixture exercising every position
(built-in extends/implements via use, same-namespace extends, new, catch,
instanceof, class-const fetch, nullable/union/closure-return type hints, an
enum-typed constant) with a runtime verify asserting the specialized class
autoloads and satisfies \Countable/\IteratorAggregate/\Traversable, plus a
no-churn guard proving a non-generic class still emits bare imported names.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/Transpiler/Monomorphize/Specializer.php   |  13 ++
 .../Monomorphize/XphpSourceParser.php         | 120 ++++++++++
 .../BuiltinInterfaceViaUseIntegrationTest.php | 209 ++++++++++++++++++
 .../source/AbstractBag.xphp                   |  20 ++
 .../source/ArrayBag.xphp                      |  75 +++++++
 .../builtin_interface_via_use/source/Bag.xphp |  13 ++
 .../source/Color.xphp                         |  11 +
 .../source/Errors/EmptyBagError.xphp          |   9 +
 .../source/Models/User.xphp                   |  12 +
 .../source/PlainBag.xphp                      |  35 +++
 .../builtin_interface_via_use/source/Use.xphp |  10 +
 .../verify/runtime.php                        |  75 +++++++
 .../ArrayBag_User.expected.php                |  58 +++++
 .../Bag_User.expected.php                     |   9 +
 14 files changed, 669 insertions(+)
 create mode 100644 test/Transpiler/Monomorphize/BuiltinInterfaceViaUseIntegrationTest.php
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/AbstractBag.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/ArrayBag.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/Bag.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/Color.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/Errors/EmptyBagError.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/Models/User.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/PlainBag.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/source/Use.xphp
 create mode 100644 test/fixture/compile/builtin_interface_via_use/verify/runtime.php
 create mode 100644 test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/ArrayBag_User.expected.php
 create mode 100644 test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/Bag_User.expected.php

diff --git a/src/Transpiler/Monomorphize/Specializer.php b/src/Transpiler/Monomorphize/Specializer.php
index b64e926..1fe295f 100644
--- a/src/Transpiler/Monomorphize/Specializer.php
+++ b/src/Transpiler/Monomorphize/Specializer.php
@@ -160,6 +160,19 @@ public function leaveNode(Node $node): ?Node
                             $args,
                         );
                         $node->setAttribute(XphpSourceParser::ATTR_GENERIC_ARGS, $substituted);
+
+                        return null;
+                    }
+
+                    // Bare, non-generic class/interface name carried over from the
+                    // template (extends Countable, new ArrayIterator, ...). The parser
+                    // tagged it with the FQN resolved against the source file's
+                    // namespace + use map; fully-qualify it now so it survives
+                    // relocation into the XPHP\Generated\... namespace. Only runs on
+                    // the cloned specialized AST -- user files never reach here.
+                    $resolvedFqn = $node->getAttribute(XphpSourceParser::ATTR_RESOLVED_FQN);
+                    if (is_string($resolvedFqn)) {
+                        return new FullyQualified($resolvedFqn, $node->getAttributes());
                     }
                 }
 
diff --git a/src/Transpiler/Monomorphize/XphpSourceParser.php b/src/Transpiler/Monomorphize/XphpSourceParser.php
index 9444bdd..a1d9157 100644
--- a/src/Transpiler/Monomorphize/XphpSourceParser.php
+++ b/src/Transpiler/Monomorphize/XphpSourceParser.php
@@ -64,6 +64,14 @@ final class XphpSourceParser
     public const ATTR_GENERIC_ARGS = 'xphp:genericArgs';
     public const ATTR_TEMPLATE_FQN = 'xphp:templateFqn';
 
+    // Resolved FQN for a bare, non-generic class/interface Name in a class-name
+    // position (extends/implements/new/catch/instanceof/static-access/type-hint).
+    // Recorded at parse time WITHOUT mutating the node, so user-file output stays
+    // byte-identical; the Specializer reads it to fully-qualify the name only on
+    // a relocated specialized clone (where the source's `use` imports no longer
+    // apply and a bare name would otherwise resolve into XPHP\Generated\...).
+    public const ATTR_RESOLVED_FQN = 'xphp:resolvedFqn';
+
     // Method-scoped generics (one type-param set per method, distinct from any class-level set).
     public const ATTR_METHOD_GENERIC_PARAMS = 'xphp:methodGenericParams';
     public const ATTR_METHOD_GENERIC_ARGS = 'xphp:methodGenericArgs';
@@ -1572,9 +1580,121 @@ public function enterNode(Node $node): null
                     }
                 }
 
+                // Tag bare class/interface Name references in class-name positions
+                // with their resolved FQN. Reached from the *parent* node's slots
+                // (never via a blanket Name visit) so function-call and constant
+                // Names are left bare -- PHP's global fallback covers them, and
+                // fully-qualifying them would break it. Runs after the Namespace_/
+                // Use_ branches (so $ctx is populated) and after the ClassLike/
+                // method type-param push (so isEnclosingTypeParam sees this scope).
+                if ($node instanceof Node\Stmt\Class_) {
+                    $this->markType($node->extends);
+                    foreach ($node->implements as $impl) {
+                        $this->markName($impl);
+                    }
+                } elseif ($node instanceof Node\Stmt\Interface_) {
+                    foreach ($node->extends as $ext) {
+                        $this->markName($ext);
+                    }
+                // Enums are intentionally absent: they can't be generic, so they
+                // are never cloned into the XPHP\Generated\... namespace, and a
+                // resolved-FQN attribute on an enum's `implements` would never be
+                // consumed by the Specializer swap.
+                } elseif ($node instanceof Node\Expr\New_
+                    || $node instanceof Node\Expr\Instanceof_
+                    || $node instanceof Node\Expr\StaticCall
+                    || $node instanceof Node\Expr\ClassConstFetch
+                    || $node instanceof Node\Expr\StaticPropertyFetch
+                ) {
+                    if ($node->class instanceof Name) {
+                        $this->markName($node->class);
+                    }
+                } elseif ($node instanceof Node\Stmt\Catch_) {
+                    foreach ($node->types as $type) {
+                        $this->markName($type);
+                    }
+                } elseif ($node instanceof Node\Param) {
+                    $this->markType($node->type);
+                } elseif ($node instanceof Node\Stmt\Property) {
+                    $this->markType($node->type);
+                } elseif ($node instanceof Node\Stmt\ClassConst) {
+                    $this->markType($node->type);
+                } elseif ($node instanceof Node\Stmt\ClassMethod
+                    || $node instanceof Node\Stmt\Function_
+                    || $node instanceof Node\Expr\Closure
+                    || $node instanceof Node\Expr\ArrowFunction
+                ) {
+                    $this->markType($node->returnType);
+                }
+
                 return null;
             }
 
+            /**
+             * Tag every class-name Name leaf inside a type-hint slot (recursing
+             * through nullable/union/intersection wrappers). Scalar `Identifier`
+             * leaves and non-Name expressions are left untouched.
+             */
+            private function markType(?Node $type): void
+            {
+                if ($type instanceof Name) {
+                    $this->markName($type);
+                } elseif ($type instanceof Node\NullableType) {
+                    $this->markType($type->type);
+                } elseif ($type instanceof Node\UnionType || $type instanceof Node\IntersectionType) {
+                    foreach ($type->types as $inner) {
+                        $this->markType($inner);
+                    }
+                }
+            }
+
+            private function markName(Name $node): void
+            {
+                if (!$this->shouldQualify($node)) {
+                    return;
+                }
+                $node->setAttribute(
+                    XphpSourceParser::ATTR_RESOLVED_FQN,
+                    $this->ctx->resolveAgainstContext($node->toString()),
+                );
+            }
+
+            /**
+             * A bare class/interface Name is fully-qualifiable only when it is not
+             * already absolute, carries no generic args (those are rewritten by the
+             * generic machinery, which keys on `!isFullyQualified()`), is not an
+             * enclosing type-param, and is not a scalar / self / parent / static
+             * keyword (all of which live in SCALAR_TYPES).
+             */
+            private function shouldQualify(Name $node): bool
+            {
+                // @infection-ignore-all — defensive only: a FullyQualified name that slipped
+                // through would still be skipped by the Specializer swap (which guards on
+                // `!isFullyQualified()`), so tagging or not tagging it is unobservable. The
+                // check just avoids stamping a useless attribute.
+                if ($node instanceof Node\Name\FullyQualified) {
+                    return false;
+                }
+                if ($node->getAttribute(XphpSourceParser::ATTR_GENERIC_ARGS) !== null) {
+                    return false;
+                }
+                $name = $node->toString();
+                // @infection-ignore-all — defensive only: an enclosing type-param is a single
+                // segment that the Specializer substitutes (returning early via typeRefToNode)
+                // before the resolved-FQN swap can ever read the attribute, so tagging it is
+                // likewise unobservable.
+                if ($this->isEnclosingTypeParam($name)) {
+                    return false;
+                }
+                $parts = $node->getParts();
+                // @infection-ignore-all — scalar keywords are single-segment; the count guard only
+                // skips a needless strtolower on namespaced names and never changes the outcome.
+                if (count($parts) === 1 && in_array(strtolower($parts[0]), XphpSourceParser::SCALAR_TYPES, true)) {
+                    return false;
+                }
+                return true;
+            }
+
             private function resolveNameOnly(string $name): string
             {
                 if (str_starts_with($name, '\\')) {
diff --git a/test/Transpiler/Monomorphize/BuiltinInterfaceViaUseIntegrationTest.php b/test/Transpiler/Monomorphize/BuiltinInterfaceViaUseIntegrationTest.php
new file mode 100644
index 0000000..854ff4a
--- /dev/null
+++ b/test/Transpiler/Monomorphize/BuiltinInterfaceViaUseIntegrationTest.php
@@ -0,0 +1,209 @@
+<?php
+
+declare(strict_types=1);
+
+namespace XPHP\Transpiler\Monomorphize;
+
+use PhpParser\ParserFactory;
+use PhpParser\PrettyPrinter\Standard as StandardPrinter;
+use PHPUnit\Framework\Attributes\RunInSeparateProcess;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use XPHP\FileSystem\FileFinder\NativeFileFinder;
+use XPHP\FileSystem\FileReader\NativeFileReader;
+use XPHP\FileSystem\FileWriter\NativeFileWriter;
+use XPHP\TestSupport\CompiledFixture;
+use XPHP\TestSupport\SnapshotHash;
+
+/**
+ * Regression coverage for ticket 0001: a generic that `extends`/`implements` a
+ * built-in interface — or instantiates / catches an imported class — via a bare
+ * `use` import used to keep those bare names when relocated into the
+ * `XPHP\Generated\...` namespace, where they resolved to a non-existent
+ * `XPHP\Generated\...\<Name>` and threw at autoload time.
+ *
+ * The fix fully-qualifies such names ONLY on the relocated specialized clone, so
+ * (a) the generated classes load, and (b) the emitted user files stay byte-for-byte
+ * unchanged (bare names + their `use` lines preserved).
+ */
+final class BuiltinInterfaceViaUseIntegrationTest extends TestCase
+{
+    private string $sourceDir;
+    private string $workDir;
+    private string $targetDir;
+    private string $cacheDir;
+
+    protected function setUp(): void
+    {
+        $this->sourceDir = realpath(__DIR__ . '/../../fixture/compile/builtin_interface_via_use/source')
+            ?: throw new RuntimeException('Fixture missing');
+        $this->workDir = sys_get_temp_dir() . '/xphp-builtin-via-use-' . uniqid('', true);
+        $this->targetDir = $this->workDir . '/dist';
+        $this->cacheDir = $this->workDir . '/.xphp-cache';
+        mkdir($this->workDir, 0o755, true);
+    }
+
+    protected function tearDown(): void
+    {
+        if (is_dir($this->workDir)) {
+            self::rrmdir($this->workDir);
+        }
+    }
+
+    public function testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports(): void
+    {
+        $this->compile();
+
+        $bagFqn = Registry::generatedFqn(
+            'App\\BuiltinViaUse\\Bag',
+            [new TypeRef('App\\BuiltinViaUse\\Models\\User')],
+        );
+        $arrayBagFqn = Registry::generatedFqn(
+            'App\\BuiltinViaUse\\ArrayBag',
+            [new TypeRef('App\\BuiltinViaUse\\Models\\User')],
+        );
+
+        $bagFile = $this->fqnToPath($bagFqn);
+        $arrayBagFile = $this->fqnToPath($arrayBagFqn);
+        self::assertFileExists($bagFile, 'specialized interface must be emitted');
+        self::assertFileExists($arrayBagFile, 'specialized class must be emitted');
+
+        $bagContent = file_get_contents($bagFile);
+        $arrayBagContent = file_get_contents($arrayBagFile);
+
+        // The bug: these names were copied bare into the generated namespace.
+        self::assertStringContainsString('extends \\Countable, \\IteratorAggregate', $bagContent);
+        self::assertStringContainsString('extends \\App\\BuiltinViaUse\\AbstractBag', $arrayBagContent);
+        self::assertStringContainsString(', \\Countable, ', $arrayBagContent);
+        self::assertStringContainsString('?\\Traversable', $arrayBagContent);
+        self::assertStringContainsString('\\Countable|\\Traversable|null', $arrayBagContent);
+        self::assertStringContainsString('accepts(\\App\\BuiltinViaUse\\Errors\\EmptyBagError $probe)', $arrayBagContent);
+        self::assertStringContainsString('new \\ArrayIterator(', $arrayBagContent);
+        self::assertStringContainsString('\\ArrayIterator::STD_PROP_LIST', $arrayBagContent);
+        self::assertStringContainsString('instanceof \\Traversable', $arrayBagContent);
+        self::assertStringContainsString('function (): \\Traversable {', $arrayBagContent);
+        self::assertStringContainsString('const \\App\\BuiltinViaUse\\Color DEFAULT_COLOR = \\App\\BuiltinViaUse\\Color::Red', $arrayBagContent);
+        self::assertStringContainsString('catch (\\App\\BuiltinViaUse\\Errors\\EmptyBagError', $arrayBagContent);
+        self::assertStringContainsString('new \\App\\BuiltinViaUse\\Errors\\EmptyBagError(', $arrayBagContent);
+        // The bare function call must NOT have been qualified.
+        self::assertStringContainsString('\\count($this->items)', $arrayBagContent);
+
+        $snapshotDir = __DIR__ . '/../../fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports';
+        SnapshotHash::assertMatches($snapshotDir . '/Bag_User.expected.php', $bagContent);
+        SnapshotHash::assertMatches($snapshotDir . '/ArrayBag_User.expected.php', $arrayBagContent);
+    }
+
+    public function testEmittedUserFileKeepsBareImportedNames(): void
+    {
+        // Hybrid-scope guarantee: only relocated clones are fully-qualified. The
+        // non-generic PlainBag is never specialized, so its emitted output must
+        // stay byte-identical to source — bare imported names + their `use` lines.
+        $this->compile();
+
+        $userFile = $this->targetDir . '/PlainBag.php';
+        self::assertFileExists($userFile);
+        $content = file_get_contents($userFile);
+
+        self::assertStringContainsString('use ArrayIterator;', $content);
+        self::assertStringContainsString('implements Countable', $content);
+        self::assertStringContainsString('return new ArrayIterator(', $content);
+        self::assertStringContainsString('catch (EmptyBagError ', $content);
+        self::assertStringContainsString(': Traversable', $content);
+        // No leaked fully-qualified rewrite in the user file.
+        self::assertStringNotContainsString('implements \\Countable', $content);
+        self::assertStringNotContainsString('new \\ArrayIterator(', $content);
+        self::assertStringNotContainsString('catch (\\App\\BuiltinViaUse\\Errors\\EmptyBagError', $content);
+    }
+
+    public function testAllOutputFilesAreSyntacticallyValid(): void
+    {
+        $this->compile();
+
+        $files = array_merge(
+            self::globRecursive($this->targetDir, '*.php'),
+            self::globRecursive($this->cacheDir . '/Generated', '*.php'),
+        );
+        self::assertNotEmpty($files);
+
+        foreach ($files as $file) {
+            $output = [];
+            $exit = 0;
+            exec('php -l ' . escapeshellarg($file) . ' 2>&1', $output, $exit);
+            self::assertSame(0, $exit, "Syntax error in {$file}:\n" . implode("\n", $output));
+        }
+    }
+
+    #[RunInSeparateProcess]
+    public function testSpecializedClassLoadsAndResolvesBuiltinsAtRuntime(): void
+    {
+        $fixture = CompiledFixture::compile($this->sourceDir, 'builtin-via-use-runtime');
+        $fixture->registerAutoload('App\\BuiltinViaUse\\');
+        try {
+            require __DIR__ . '/../../fixture/compile/builtin_interface_via_use/verify/runtime.php';
+        } finally {
+            $fixture->cleanup();
+        }
+    }
+
+    private function compile(): void
+    {
+        $compiler = $this->buildCompiler();
+        $sources = (new NativeFileFinder())
+            ->find($this->sourceDir)
+            ->filter(static fn (string $f): bool => str_ends_with($f, '.xphp'));
+        $compiler->compile($sources, $this->sourceDir, $this->targetDir, $this->cacheDir);
+    }
+
+    private function fqnToPath(string $fqn): string
+    {
+        $prefix = Registry::GENERATED_NAMESPACE_PREFIX . '\\';
+        $rel = str_starts_with($fqn, $prefix) ? substr($fqn, strlen($prefix)) : $fqn;
+        return $this->cacheDir . '/Generated/' . str_replace('\\', '/', $rel) . '.php';
+    }
+
+    /**
+     * @return list<string>
+     */
+    private static function globRecursive(string $dir, string $pattern): array
+    {
+        if (!is_dir($dir)) {
+            return [];
+        }
+        $found = glob(rtrim($dir, '/') . '/' . $pattern) ?: [];
+        foreach (glob(rtrim($dir, '/') . '/*', GLOB_ONLYDIR) ?: [] as $subdir) {
+            $found = array_merge($found, self::globRecursive($subdir, $pattern));
+        }
+        return $found;
+    }
+
+    private function buildCompiler(): Compiler
+    {
+        $phpParser = (new ParserFactory())->createForHostVersion();
+        $printer = new StandardPrinter();
+        $writer = new NativeFileWriter();
+
+        return new Compiler(
+            new NativeFileReader(),
+            $writer,
+            new XphpSourceParser($phpParser),
+            new Specializer(),
+            new SpecializedClassGenerator($printer, $writer),
+            $printer,
+        );
+    }
+
+    private static function rrmdir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+        foreach (scandir($dir) as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $entry;
+            is_dir($path) ? self::rrmdir($path) : unlink($path);
+        }
+        rmdir($dir);
+    }
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/AbstractBag.xphp b/test/fixture/compile/builtin_interface_via_use/source/AbstractBag.xphp
new file mode 100644
index 0000000..d640f94
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/AbstractBag.xphp
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse;
+
+/**
+ * A same-namespace base class referenced by a BARE name in `extends`. Even
+ * without a `use` import these break under relocation: the bare `AbstractBag`
+ * resolves against the current namespace, so once the specialized subclass is
+ * lifted into `XPHP\Generated\...` it would point at a non-existent
+ * `XPHP\Generated\...\AbstractBag`. The fix qualifies it to the real FQN.
+ */
+abstract class AbstractBag
+{
+    public function isEmpty(array $items): bool
+    {
+        return $items === [];
+    }
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/ArrayBag.xphp b/test/fixture/compile/builtin_interface_via_use/source/ArrayBag.xphp
new file mode 100644
index 0000000..0683e26
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/ArrayBag.xphp
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse;
+
+use ArrayIterator;
+use Countable;
+use Traversable;
+use App\BuiltinViaUse\Errors\EmptyBagError;
+
+class ArrayBag<T> extends AbstractBag implements Bag<T>, Countable
+{
+    // Typed (enum) class constant: the type `Color` is a same-namespace bare name
+    // that must be qualified in the relocated class — the `ClassConst` position.
+    public const Color DEFAULT_COLOR = Color::Red;
+
+    private array $items = [];
+
+    // Nullable + union type-hints referencing `use`-imported built-ins: exercise
+    // the NullableType and UnionType arms of the resolver in a relocated class.
+    private ?Traversable $snapshot = null;
+    private Countable|Traversable|null $meta = null;
+
+    public function add(T $item): void
+    {
+        $this->items[] = $item;
+    }
+
+    public function count(): int
+    {
+        // Bare function call: must stay bare (PHP global fallback) even after relocation.
+        return \count($this->items);
+    }
+
+    public function getIterator(): Traversable
+    {
+        // Return-type hint + `new` of a `use`-imported built-in class.
+        return new ArrayIterator($this->items);
+    }
+
+    // Param typed with an imported class; `instanceof` + class-constant fetch on
+    // imported classes inside a relocated body.
+    public function accepts(EmptyBagError $probe): bool
+    {
+        $iter = new ArrayIterator($this->items);
+        $flags = ArrayIterator::STD_PROP_LIST;
+
+        return $flags >= 0
+            && $iter instanceof Traversable
+            && $probe instanceof EmptyBagError;
+    }
+
+    // Closure with an imported return-type hint, nested in a relocated method.
+    public function makeFactory(): callable
+    {
+        return function (): Traversable {
+            return new ArrayIterator($this->items);
+        };
+    }
+
+    public function first(): T
+    {
+        try {
+            if ($this->items === []) {
+                // `new` of a `use`-imported exception class.
+                throw new EmptyBagError('bag is empty');
+            }
+            return $this->items[0];
+        } catch (EmptyBagError $e) {
+            // `catch` of a `use`-imported exception class.
+            throw new \RuntimeException($e->getMessage(), 0, $e);
+        }
+    }
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/Bag.xphp b/test/fixture/compile/builtin_interface_via_use/source/Bag.xphp
new file mode 100644
index 0000000..5c91a63
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/Bag.xphp
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse;
+
+use Countable;
+use IteratorAggregate;
+
+interface Bag<T> extends Countable, IteratorAggregate
+{
+    public function add(T $item): void;
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/Color.xphp b/test/fixture/compile/builtin_interface_via_use/source/Color.xphp
new file mode 100644
index 0000000..1f0b75d
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/Color.xphp
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse;
+
+enum Color
+{
+    case Red;
+    case Blue;
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/Errors/EmptyBagError.xphp b/test/fixture/compile/builtin_interface_via_use/source/Errors/EmptyBagError.xphp
new file mode 100644
index 0000000..ce65e17
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/Errors/EmptyBagError.xphp
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse\Errors;
+
+final class EmptyBagError extends \RuntimeException
+{
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/Models/User.xphp b/test/fixture/compile/builtin_interface_via_use/source/Models/User.xphp
new file mode 100644
index 0000000..d48e590
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/Models/User.xphp
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse\Models;
+
+final class User
+{
+    public function __construct(public readonly string $name)
+    {
+    }
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/PlainBag.xphp b/test/fixture/compile/builtin_interface_via_use/source/PlainBag.xphp
new file mode 100644
index 0000000..aa87499
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/PlainBag.xphp
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse;
+
+use ArrayIterator;
+use Countable;
+use Traversable;
+use App\BuiltinViaUse\Errors\EmptyBagError;
+
+/**
+ * A NON-generic class that uses the same `use`-imported built-ins. It is never
+ * specialized/relocated, so its emitted output must stay byte-identical to the
+ * source (bare names + `use` lines) — this guards the Hybrid-scope promise that
+ * the fix only touches relocated clones, never the user's own files.
+ */
+final class PlainBag implements Countable
+{
+    private array $items = [];
+
+    public function count(): int
+    {
+        return \count($this->items);
+    }
+
+    public function iterate(): Traversable
+    {
+        try {
+            return new ArrayIterator($this->items);
+        } catch (EmptyBagError $e) {
+            throw new \RuntimeException($e->getMessage(), 0, $e);
+        }
+    }
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/source/Use.xphp b/test/fixture/compile/builtin_interface_via_use/source/Use.xphp
new file mode 100644
index 0000000..fc9a752
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/source/Use.xphp
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\BuiltinViaUse;
+
+use App\BuiltinViaUse\Models\User;
+
+$bag = new ArrayBag::<User>();
+$bag->add(new User('alice'));
diff --git a/test/fixture/compile/builtin_interface_via_use/verify/runtime.php b/test/fixture/compile/builtin_interface_via_use/verify/runtime.php
new file mode 100644
index 0000000..1348f74
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/verify/runtime.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Runtime verify for `builtin_interface_via_use`.
+ *
+ * The specialized `ArrayBag<User>` is relocated into the `XPHP\Generated\...`
+ * namespace. Before the fix, its `implements`/`extends` chain and body kept the
+ * bare `use`-imported names (`Countable`, `IteratorAggregate`, `ArrayIterator`,
+ * `EmptyBagError`), which resolved into the generated namespace and threw
+ * "Interface ... not found" the moment the class autoloaded. This file proves
+ * the class now loads and the built-ins resolve to the real global symbols.
+ *
+ * Driver contract: `$fixture` (CompiledFixture) in scope, autoload registered
+ * for `App\BuiltinViaUse\` + the generated namespace.
+ */
+
+use App\BuiltinViaUse\Models\User;
+use PHPUnit\Framework\Assert;
+use XPHP\Transpiler\Monomorphize\Registry;
+use XPHP\Transpiler\Monomorphize\TypeRef;
+
+$bagFqn = Registry::generatedFqn(
+    'App\\BuiltinViaUse\\ArrayBag',
+    [new TypeRef('App\\BuiltinViaUse\\Models\\User')],
+);
+
+// Autoloads without a "not found" error — this is the regression under test.
+$bag = new $bagFqn();
+
+// `extends Countable, IteratorAggregate` (imported, bare) resolved to the real built-ins.
+Assert::assertInstanceOf(\Countable::class, $bag);
+Assert::assertInstanceOf(\IteratorAggregate::class, $bag);
+
+$bag->add(new User('alice'));
+$bag->add(new User('bob'));
+
+// Countable::count() via the bare `\count(...)` call (must have stayed bare).
+Assert::assertCount(2, $bag);
+
+// `getIterator(): Traversable { return new ArrayIterator(...); }` — return-type
+// hint + `new` of an imported built-in, both relocation-proof now.
+$iter = $bag->getIterator();
+Assert::assertInstanceOf(\Traversable::class, $iter);
+Assert::assertInstanceOf(\ArrayIterator::class, $iter);
+Assert::assertCount(2, $iter);
+
+// `first()` happy path returns the concrete substituted element type.
+Assert::assertInstanceOf(User::class, $bag->first());
+Assert::assertSame('alice', $bag->first()->name);
+
+// `extends AbstractBag` (bare, same-namespace) resolved to the real base class.
+Assert::assertInstanceOf(\App\BuiltinViaUse\AbstractBag::class, $bag);
+Assert::assertTrue((new $bagFqn())->isEmpty([]));
+
+// Param-typed / instanceof / class-const-fetch positions all load and run.
+Assert::assertTrue($bag->accepts(new \App\BuiltinViaUse\Errors\EmptyBagError('probe')));
+
+// Closure with an imported return type, nested in a relocated method.
+$factory = $bag->makeFactory();
+Assert::assertInstanceOf(\Traversable::class, $factory());
+
+// Typed (enum) class constant whose type + value reference a same-namespace class.
+Assert::assertSame(\App\BuiltinViaUse\Color::Red, $bag::DEFAULT_COLOR);
+
+// `catch (EmptyBagError $e)` + `new EmptyBagError(...)` path on the empty bag.
+$empty = new $bagFqn();
+try {
+    $empty->first();
+    Assert::fail('expected RuntimeException from the empty-bag path');
+} catch (\RuntimeException $e) {
+    Assert::assertSame('bag is empty', $e->getMessage());
+    Assert::assertInstanceOf(\App\BuiltinViaUse\Errors\EmptyBagError::class, $e->getPrevious());
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/ArrayBag_User.expected.php b/test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/ArrayBag_User.expected.php
new file mode 100644
index 0000000..2d14d94
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/ArrayBag_User.expected.php
@@ -0,0 +1,58 @@
+<?php
+
+declare (strict_types=1);
+namespace XPHP\Generated\App\BuiltinViaUse\ArrayBag;
+
+class T_729a900208fdde1d2fd72168cd42098ff2c2d6155f1713a6e10b4aafa854674e extends \App\BuiltinViaUse\AbstractBag implements \XPHP\Generated\App\BuiltinViaUse\Bag\T_729a900208fdde1d2fd72168cd42098ff2c2d6155f1713a6e10b4aafa854674e, \Countable, \App\BuiltinViaUse\ArrayBag
+{
+    // Typed (enum) class constant: the type `Color` is a same-namespace bare name
+    // that must be qualified in the relocated class — the `ClassConst` position.
+    public const \App\BuiltinViaUse\Color DEFAULT_COLOR = \App\BuiltinViaUse\Color::Red;
+    private array $items = [];
+    // Nullable + union type-hints referencing `use`-imported built-ins: exercise
+    // the NullableType and UnionType arms of the resolver in a relocated class.
+    private ?\Traversable $snapshot = null;
+    private \Countable|\Traversable|null $meta = null;
+    public function add(\App\BuiltinViaUse\Models\User $item): void
+    {
+        $this->items[] = $item;
+    }
+    public function count(): int
+    {
+        // Bare function call: must stay bare (PHP global fallback) even after relocation.
+        return \count($this->items);
+    }
+    public function getIterator(): \Traversable
+    {
+        // Return-type hint + `new` of a `use`-imported built-in class.
+        return new \ArrayIterator($this->items);
+    }
+    // Param typed with an imported class; `instanceof` + class-constant fetch on
+    // imported classes inside a relocated body.
+    public function accepts(\App\BuiltinViaUse\Errors\EmptyBagError $probe): bool
+    {
+        $iter = new \ArrayIterator($this->items);
+        $flags = \ArrayIterator::STD_PROP_LIST;
+        return $flags >= 0 && $iter instanceof \Traversable && $probe instanceof \App\BuiltinViaUse\Errors\EmptyBagError;
+    }
+    // Closure with an imported return-type hint, nested in a relocated method.
+    public function makeFactory(): callable
+    {
+        return function (): \Traversable {
+            return new \ArrayIterator($this->items);
+        };
+    }
+    public function first(): \App\BuiltinViaUse\Models\User
+    {
+        try {
+            if ($this->items === []) {
+                // `new` of a `use`-imported exception class.
+                throw new \App\BuiltinViaUse\Errors\EmptyBagError('bag is empty');
+            }
+            return $this->items[0];
+        } catch (\App\BuiltinViaUse\Errors\EmptyBagError $e) {
+            // `catch` of a `use`-imported exception class.
+            throw new \RuntimeException($e->getMessage(), 0, $e);
+        }
+    }
+}
diff --git a/test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/Bag_User.expected.php b/test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/Bag_User.expected.php
new file mode 100644
index 0000000..2929f47
--- /dev/null
+++ b/test/fixture/compile/builtin_interface_via_use/verify/testSpecializedClassFullyQualifiesBuiltinNamesFromUseImports/Bag_User.expected.php
@@ -0,0 +1,9 @@
+<?php
+
+declare (strict_types=1);
+namespace XPHP\Generated\App\BuiltinViaUse\Bag;
+
+interface T_729a900208fdde1d2fd72168cd42098ff2c2d6155f1713a6e10b4aafa854674e extends \Countable, \IteratorAggregate, \App\BuiltinViaUse\Bag
+{
+    public function add(\App\BuiltinViaUse\Models\User $item): void;
+}

From 9d5a86af8fdc5695c2170e244a06340a8ed4f811 Mon Sep 17 00:00:00 2001
From: Matheus Martins <mathrm@gmail.com>
Date: Wed, 17 Jun 2026 18:34:18 +0000
Subject: [PATCH 8/8] fix(cli): locate Composer autoloader when installed as a
 dependency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bin/xphp bootstrapped Composer with a single hardcoded
`require dirname(__DIR__) . '/vendor/autoload.php'`. That path only exists in a
standalone checkout. When xphp-lang/xphp is installed as a Composer dependency
the package has no vendor/ of its own — the autoloader lives in the consuming
project's vendor/autoload.php, three levels up from bin/ — so `vendor/bin/xphp`
died at startup with "Failed opening required ...". It only worked in the
package's own repo, masking the bug.

Replace the require with the standard multi-candidate bootstrap: probe the
Composer bin-proxy global ($GLOBALS['_composer_autoload_path']), the
dependency path (dirname(__DIR__, 3) . '/autoload.php'), then the standalone
path (dirname(__DIR__) . '/vendor/autoload.php'), requiring the first that
exists; otherwise print a clear message to STDERR and exit(1). The is_string
guard keeps it safe under strict_types, and the standalone candidate is kept
last because it is also the PHAR's only working autoloader path.

Regression coverage: test/Console/BinAutoloadBootstrapTest.php drives the binary
via proc_open with separate stdout/stderr pipes — standalone checkout, a
simulated consumer layout (fake vendor/xphp-lang/xphp/bin/xphp with no nested
vendor/), and the no-autoloader error path asserting exit 1 + the diagnostic on
STDERR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 bin/xphp                                  |  26 ++++-
 test/Console/BinAutoloadBootstrapTest.php | 127 ++++++++++++++++++++++
 2 files changed, 152 insertions(+), 1 deletion(-)
 create mode 100644 test/Console/BinAutoloadBootstrapTest.php

diff --git a/bin/xphp b/bin/xphp
index cdf9b11..a1c75ee 100755
--- a/bin/xphp
+++ b/bin/xphp
@@ -3,7 +3,31 @@
 
 declare(strict_types=1);
 
-require dirname(__DIR__) . '/vendor/autoload.php';
+(static function (): void {
+    $candidates = [
+        // Set by Composer's generated bin proxy (vendor/bin/xphp).
+        $GLOBALS['_composer_autoload_path'] ?? null,
+        // Installed as a dependency: vendor/xphp-lang/xphp/bin -> <project>/vendor/autoload.php
+        dirname(__DIR__, 3) . '/autoload.php',
+        // Standalone checkout AND the PHAR (phar://alias.phar/vendor/autoload.php) rely on
+        // this one -- keep it present and last.
+        dirname(__DIR__) . '/vendor/autoload.php',
+    ];
+
+    foreach ($candidates as $file) {
+        if (is_string($file) && is_file($file)) {
+            require $file;
+
+            return;
+        }
+    }
+
+    fwrite(
+        STDERR,
+        'xphp: could not locate Composer\'s autoloader. Run `composer install`.' . PHP_EOL,
+    );
+    exit(1);
+})();
 
 use Symfony\Component\Console\Input\ArgvInput;
 use Symfony\Component\Console\Output\ConsoleOutput;
diff --git a/test/Console/BinAutoloadBootstrapTest.php b/test/Console/BinAutoloadBootstrapTest.php
new file mode 100644
index 0000000..c935031
--- /dev/null
+++ b/test/Console/BinAutoloadBootstrapTest.php
@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+namespace XPHP\Console;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Guards the autoloader bootstrap in `bin/xphp`. The CLI must locate Composer's
+ * autoloader whether xphp is a standalone checkout (its own `vendor/`) or
+ * installed as a dependency (the consuming project's `vendor/`, three levels up
+ * from `bin/`), and must fail with a clear, non-fatal message when no autoloader
+ * exists. Regression coverage for the hardcoded `dirname(__DIR__) . '/vendor/...'`
+ * that broke every downstream consumer.
+ */
+final class BinAutoloadBootstrapTest extends TestCase
+{
+    private string $projectRoot;
+    private string $workDir;
+
+    protected function setUp(): void
+    {
+        $this->projectRoot = dirname(__DIR__, 2);
+        $this->workDir = sys_get_temp_dir() . '/xphp-bin-bootstrap-' . uniqid('', true);
+        mkdir($this->workDir, 0o755, true);
+    }
+
+    protected function tearDown(): void
+    {
+        if (is_dir($this->workDir)) {
+            self::rrmdir($this->workDir);
+        }
+    }
+
+    public function testRunsInStandaloneCheckout(): void
+    {
+        // The real checkout has its own vendor/ — candidate #3 of the bootstrap.
+        $result = $this->runBin($this->projectRoot . '/bin/xphp', ['--version']);
+
+        self::assertSame(0, $result['exit'], $result['stderr']);
+        self::assertStringContainsString('xphp', $result['stdout']);
+    }
+
+    public function testRunsWhenInstalledAsDependency(): void
+    {
+        // Reproduce the consumer layout: vendor/xphp-lang/xphp/bin/xphp with the
+        // real autoloader three levels up at vendor/autoload.php, and crucially NO
+        // vendor/ inside the package (the path the old hardcoded require assumed).
+        $pkgBinDir = $this->workDir . '/vendor/xphp-lang/xphp/bin';
+        mkdir($pkgBinDir, 0o755, true);
+        self::assertTrue(copy($this->projectRoot . '/bin/xphp', $pkgBinDir . '/xphp'));
+
+        // A stub that just pulls in the real autoloader, so XPHP + symfony/console
+        // classes resolve without a network `composer install`.
+        file_put_contents(
+            $this->workDir . '/vendor/autoload.php',
+            '<?php require ' . var_export($this->projectRoot . '/vendor/autoload.php', true) . ';' . PHP_EOL,
+        );
+
+        $result = $this->runBin($pkgBinDir . '/xphp', ['--version']);
+
+        self::assertSame(0, $result['exit'], $result['stderr']);
+        self::assertStringContainsString('xphp', $result['stdout']);
+    }
+
+    public function testFailsGracefullyWhenNoAutoloaderFound(): void
+    {
+        // Same package layout but with no reachable autoload.php anywhere.
+        $pkgBinDir = $this->workDir . '/vendor/xphp-lang/xphp/bin';
+        mkdir($pkgBinDir, 0o755, true);
+        self::assertTrue(copy($this->projectRoot . '/bin/xphp', $pkgBinDir . '/xphp'));
+
+        $result = $this->runBin($pkgBinDir . '/xphp', ['--version']);
+
+        self::assertSame(1, $result['exit']);
+        // The diagnostic must go to STDERR (separate pipe), not STDOUT.
+        self::assertStringContainsString('could not locate', $result['stderr']);
+        self::assertStringContainsString('composer install', $result['stderr']);
+    }
+
+    /**
+     * Run `PHP_BINARY <binPath> <args...>` with separate STDOUT/STDERR pipes.
+     *
+     * @param list<string> $args
+     * @return array{exit:int, stdout:string, stderr:string}
+     */
+    private function runBin(string $binPath, array $args): array
+    {
+        $descriptors = [
+            0 => ['pipe', 'r'],
+            1 => ['pipe', 'w'],
+            2 => ['pipe', 'w'],
+        ];
+
+        $proc = proc_open(
+            array_merge([PHP_BINARY, $binPath], $args),
+            $descriptors,
+            $pipes,
+        );
+        self::assertIsResource($proc);
+
+        fclose($pipes[0]);
+        $stdout = stream_get_contents($pipes[1]) ?: '';
+        $stderr = stream_get_contents($pipes[2]) ?: '';
+        fclose($pipes[1]);
+        fclose($pipes[2]);
+        $exit = proc_close($proc);
+
+        return ['exit' => $exit, 'stdout' => $stdout, 'stderr' => $stderr];
+    }
+
+    private static function rrmdir(string $dir): void
+    {
+        if (!is_dir($dir)) {
+            return;
+        }
+        foreach (scandir($dir) ?: [] as $entry) {
+            if ($entry === '.' || $entry === '..') {
+                continue;
+            }
+            $path = $dir . '/' . $entry;
+            is_dir($path) ? self::rrmdir($path) : unlink($path);
+        }
+        rmdir($dir);
+    }
+}