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