feat(php-rpc): embed the Composer PHP runtime in the executable

Plugins and scripts need the real `Composer\` classes and the packages
Composer depends on, which so far came from a checkout found through
SHIRABE_COMPOSER_PHP_DIR or a path next to the workspace. Neither exists
for a distributed binary.

The build script now archives those PHP sources into a phar the way
Compiler.php does and the executable carries it. The worker maps it with
Phar::loadPhar and reads a content-addressed sentinel back to tell a
bundle it can use from one it cannot; where its PHP cannot open the phar,
the bundle is unpacked once into the cache directory and autoloaded from
there. SHIRABE_COMPOSER_PHP_DIR still overrides both for development.

PHP locates a phar's manifest by the first __HALT_COMPILER(); token in
the file, so the executable must hold no other copy of it: phar.rs builds
the token at run time, and a linter keeps further literals out of the
sources that reach the binary.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2 files changed, 48 insertions, 5 deletions

diff --git a/docs/dev/composer-runtime-bundle.md b/docs/dev/composer-runtime-bundle.md
new file mode 100644
index 00000000..f152897f
--- /dev/null
+++ b/docs/dev/composer-runtime-bundle.md
@@ -0,0 +1,40 @@
+# Composer runtime bundle
+
+Composer plugins and scripts expect the real PHP classes in `Composer\` itself
+and packages that Composer depends on to be available. Shirabe embeds the
+runtime PHP sources into the binary at compile time.
+
+## Building and embedding the bundle
+
+Shirabe archives all PHP sources and resources of Composer and its dependencies,
+and embeds the archived phar file into the binary. Shirabe also calculates a
+hash value from all included files and puts a file that contains the hash,
+`shirabe/bundle-id`. It is used for verifying the bundle. See
+`crates/shirabe-php-rpc/build.rs` for details.
+
+### Phar signature
+
+A phar signature is an optional signature to verify the archive's integrity, and
+must be appended to the end of the file. Shirabe's runtime bundle has no
+signature because the bundle is not always at the end of the executable file.
+To disable phar verification, the PHP worker is started with `-d phar.require_hash=0`.
+The worker restores it to `1` right after opening the bundle, so that the rest
+of the process still verifies the phars it opens. A verification result is
+cached per file, and the bundle is never re-verified.
+
+### `__HALT_COMPILER();` tokens
+
+A phar file consists of 3 or 4 sections: a stub, a manifest, the actual contents
+and an optional signature. The stub and the manifest are separated by
+`__HALT_COMPILER();` tokens, which means that Shirabe's executable binary
+must not contain the tokens except for phar's one.
+
+## Accessing files at runtime
+
+Shirabe tries to open the embedded bundle, and sets the executable as the base
+path of autoloading. If loading phar fails for some reason, e.g., no phar ext,
+Shirabe unpacks the archive to `<Shirabe's cache dir>/runtime/<bundle id>` once,
+and uses that directory for the base path instead.
+
+NOTE: the environment variable `SHIRABE_COMPOSER_PHP_DIR` can override the
+location for development.
diff --git a/docs/dev/php-rpc.md b/docs/dev/php-rpc.md
index 8418db88..b1c992d7 100644
--- a/docs/dev/php-rpc.md
+++ b/docs/dev/php-rpc.md
@@ -7,12 +7,15 @@ runtime.
 The `shirabe-php-rpc` crate spawns the system PHP as a child process and talks to it over a Unix
 domain socket. There is exactly one child process per Shirabe process, shared by every caller.
 
-## Locating PHP
+## Locating and spawning PHP
 
-The existing `PhpExecutableFinder` class resolves the PHP binary. The child is started with
-`-d serialize_precision=-1` so the wire codec's float formatting is pinned to the default PHP
-behavior, and with `-d xdebug.mode=off` unless `COMPOSER_ALLOW_XDEBUG` asks for Xdebug to stay
-(see `xdebug.md`).
+The existing `PhpExecutableFinder` class resolves the PHP binary.
+
+The child is started with the following arguments:
+
+* `-d serialize_precision=-1` for stable float formatting of `serialize()`/`unserialize()`
+* `-d phar.require_hash=0` (see [docs/dev/composer-runtime-bundle.md](./composer-runtime-bundle.md))
+* `-d xdebug.mode=off` (see [docs/dev/xdebug.md](./xdebug.md))
 
 ## Transport