feat(plugin): guard Rust-owned classes the worker has no proxy for

The worker's autoloader fell through to the real Composer source for every
Rust-owned FQCN without a proxy stub, so plugin code doing `new Filesystem()`
or subclassing `LibraryInstaller` silently ran on a second instance the Rust
side never sees. An unimplemented part of the plugin API has to fail with an
explicit error naming it, not quietly work on a disconnected copy.

The stub generator now emits a guard class for each of those FQCNs: the real
declaration, hierarchy and constants, with every constructor and method
raising an explicit error. References satisfied by the declaration alone
(`instanceof`, `X::class`, `Link::TYPE_REQUIRE`) keep working. Two FQCNs stay
resolvable to the real class, each listed with the worker-side mechanism that
makes a natively constructed instance correct.

The error had nowhere to go: `Installer::run` dropped the `Result` of both
`dispatch_script` calls, so an exception from a listener ended in exit 0.
Both propagate now, the way the exception does upstream.

Three real-plugin E2E comparisons stop at a guard and are ignored, each
naming the class it needs.

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

1 files changed, 9 insertions, 3 deletions

diff --git a/docs/dev/php-rpc.md b/docs/dev/php-rpc.md
index b1c992d7..f91b8e54 100644
--- a/docs/dev/php-rpc.md
+++ b/docs/dev/php-rpc.md
@@ -185,7 +185,7 @@ allocates the Rust entity behind a `new SomeProxiedClass(...)` written by plugin
 answers with `[rhandle, epoch]`. Classes whose entity Rust cannot build are an explicit error
 naming the class.
 
-## Proxy stubs and runtime classes
+## Proxy stubs, runtime classes and guards
 
 `php/stubs/` holds the proxy stub classes (`Composer\Script\Event`, `Composer\PartialComposer`,
 `Composer\Composer`, the `Composer\IO\{BaseIO,ConsoleIO,BufferIO,NullIO}` hierarchy, the
@@ -215,8 +215,14 @@ by `scripts/plugin-stub-generator/generate-stubs` and must not be edited by hand
   here) is a faithful in-process port of the real base class and crosses the wire as a P-table
   entity (`__shirabeRustHandleDescriptor()` returns null in native mode).
 
-Both sets are written into the same autoload directory at worker spawn and resolved with
-highest priority, so these FQCNs can never be shadowed by the real implementation;
+`php/guards/` holds the guard classes: one per Composer class whose entity lives on the Rust side
+and that neither a stub nor a runtime class shadows. A guard keeps the FQCN, the hierarchy and the
+constants of the real class, and raises an explicit error from its constructor and every method,
+so code running here can never work on a second instance the Rust side never sees. They are
+generated by the same tool as the stubs.
+
+The three sets are written into two autoload directories at worker spawn (guards behind stubs) and
+resolved with highest priority, so these FQCNs can never be shadowed by the real implementation;
 `__shirabe_require` restores that priority after loading code that prepends its own autoloader.
 Stubs are interned per rhandle (`WeakReference`-based registry) so identity (`===`) holds, and
 their destructors send `ReleaseRustHandle`. Reviving a stub for an existing entity bypasses its