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>

3 files changed, 60 insertions, 10 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
diff --git a/docs/dev/plugin-class-classification.md b/docs/dev/plugin-class-classification.md
index c77eca52..7046ea48 100644
--- a/docs/dev/plugin-class-classification.md
+++ b/docs/dev/plugin-class-classification.md
@@ -42,6 +42,12 @@ exactly one category.
 | `php-native` | PHP | the real, unmodified PHP source | none — Rust may or may not have its own port for internal use, and that port is free to diverge in shape |
 | `unsupported` | n/a | nothing; any reference raises an explicit error | none, until explicitly promoted |
 
+A Rust-owned class the child has no artifact for — every `unsupported` one, and
+every `rust-proxy`/`rust-snapshot` one whose stub is not written yet — is
+shadowed there by a generated *guard* class instead of the real Composer source:
+same FQCN, hierarchy and constants, every constructor and method an explicit
+error. See `docs/dev/plugin-stub-generation.md`.
+
 #### rust-proxy
 
 The living services: `Composer`, `Config`, `RepositoryManager`,
diff --git a/docs/dev/plugin-stub-generation.md b/docs/dev/plugin-stub-generation.md
index 68dde156..e2b6d848 100644
--- a/docs/dev/plugin-stub-generation.md
+++ b/docs/dev/plugin-stub-generation.md
@@ -1,4 +1,4 @@
-# Plugin proxy stub generation
+# Plugin proxy stub and guard generation
 
 ## Purpose
 
@@ -12,13 +12,21 @@ Composer sources keeps every stub signature mechanically faithful to the real
 class and turns "the stub is missing something the real class has" into a
 generation failure instead of silent breakage.
 
+The same tool emits the **guard classes** under
+`crates/shirabe-php-rpc/php/guards/`, one for every Rust-owned class no stub and
+no `php/runtime/` class shadows. Without them the worker's autoloader falls
+through to the real Composer implementation, and code running there works on a
+second instance the Rust side never sees — silent breakage in place of the
+explicit error an unimplemented plugin API is supposed to raise. `build.rs`
+embeds the guards, building the list from the directory itself.
+
 ## Running
 
 ```
 cd scripts/plugin-stub-generator
 composer install            # once; vendor/ is git-ignored
-./generate-stubs            # rewrites crates/shirabe-php-rpc/php/stubs/
-./generate-stubs --check    # verifies committed stubs are fresh; exit 1 otherwise
+./generate-stubs            # rewrites the stubs/ and guards/ directories
+./generate-stubs --check    # verifies committed files are fresh; exit 1 otherwise
 ```
 
 Inputs:
@@ -36,10 +44,19 @@ Inputs:
   interfaces from vendor packages (e.g. `Psr\Log\LoggerInterface`) resolve too.
 * the classifier report (`scripts/plugin-class-classifier/report.json`, override
   with `--report=`). Run `scripts/plugin-class-classifier/classify` first; the
-  report is git-ignored. Every target must be classified `rust-proxy` or
-  `contract`, and a report with classification violations is rejected.
+  report is git-ignored. Every stub target must be classified `rust-proxy` or
+  `contract`, and a report with classification violations is rejected. The guard
+  set is read from the report alone: every `rust-proxy`, `rust-snapshot` and
+  `unsupported` class that is not a stub target, a `php/runtime/` class or an
+  exemption.
+* `guard-exemptions.list` — the Rust-owned FQCNs that stay resolvable to the real
+  Composer class, each with the worker-side mechanism that makes a native
+  instance correct (the materialized-value codec for `Composer\Package\Link`,
+  the dual-mode `Composer\EventDispatcher\Event` for
+  `Composer\Plugin\PreCommandRunEvent`). An entry that needs no guard anyway
+  fails the run.
 
-The freshness check runs in `cargo test` as
+The freshness check for both sets runs in `cargo test` as
 `crates/shirabe-php-rpc/tests/generated_stubs.rs`; it returns early when PHP,
 the generator's vendor directory or the classifier report is unavailable.
 
@@ -93,6 +110,27 @@ the generator's vendor directory or the classifier report is unavailable.
   order, restricted to names the emitted stub references; signatures declared
   elsewhere (interface files) are re-spelled through that import table.
 
+## What a guard looks like
+
+A guard reproduces the real class's declaration — `abstract`/`final`, `extends`,
+`implements`, the constants and public static properties verbatim — so that
+references satisfied by the declaration alone keep working: `instanceof`,
+`catch`, `X::class`, `Link::TYPE_REQUIRE`. Everything executable raises
+`ShirabeUnsupportedClass::fail()`, which names the class and the member:
+
+* the constructor (the class's own, or the one it would inherit; a class whose
+  hierarchy declares none gets a no-argument one, so the implicit constructor
+  cannot be reached either),
+* every public and protected method the guard would otherwise inherit from real
+  code: its own, its traits', and those of ancestors up to the first one that is
+  itself guarded or shadowed by a stub. Private methods are reachable only from
+  the code the guard replaces, and a destructor that throws would fire during
+  unwinding, so neither is emitted.
+
+Abstract methods of an abstract guard stay abstract. A method an ancestor
+declares `final` cannot be redeclared, so it keeps running the real
+implementation; the guard's header names each one.
+
 ## Coverage assertions
 
 Generation fails — instead of emitting something quietly wrong — on:
@@ -107,7 +145,7 @@ Generation fails — instead of emitting something quietly wrong — on:
 * a target whose FQCN is also provided by `php/runtime/`.
 
 `generate-stubs` (in both modes) additionally fails when a `.php` file exists
-under the stubs directory that no target produces, or when `STUB_FILES` /
+under the stubs or guards directory that no target produces, or when `STUB_FILES` /
 `RUNTIME_FILES` in `crates/shirabe-php-rpc/src/lib.rs` does not embed every
 generated stub / runtime file. It also cross-checks the handoff property table
 for `Composer\Console\Application` (declared in `generate-stubs` itself) against