Fix generated GPBMetadata for php

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 <!-- There is always Unreleased section on the top. Subsections (Add, Changed, Fix, Removed) should be Add as needed. -->
 ## Unreleased
+### Fixed
+- Pinned the PHP `php_metadata_namespace` to the standard protoc convention `GPBMetadata\Feather\Contracts\Core\V1` (instead of managed mode's `Feather\Contracts\Core\V1\GPBMetadata` default), so downstream contracts generated without managed mode can load the metadata class.
+
+### Changed
+- Added a `GPBMetadata\` PSR-4 autoload entry in `composer.json` for the relocated PHP metadata class.
 
 ## 1.2.0 - 2026-07-31
 ### Changed

README.md

@@ -149,6 +149,15 @@ Common flags: `no-lint`, `no-clean` to skip the respective steps.
    buf push             # publishes buf.build/feathertools/contracts
    ```
 
+### Managed mode
+
+Buf can decide the generated namespaces two ways, controlled in [`buf.gen.yaml`](buf.gen.yaml):
+
+- **Managed mode ON** (used here) — namespaces are **derived from the Protobuf package** and injected at generation time, so the `.proto` stays free of language-specific options. This is Buf's idiomatic default and the right choice when the package (`feather.contracts.core.v1`) already maps cleanly onto the desired namespaces (`Feather.Contracts.Core.V1`, `Feather\Contracts\Core\V1`).
+- **Managed mode OFF** — namespaces come from `option` lines written **inside the `.proto`** (or plain package-derived protoc defaults). Choose this only when you need a namespace scheme the package can't produce (e.g. a `Context.Contracts.System` layout that intentionally differs from the package path).
+
+This repository uses **managed mode ON** with a single override: `php_metadata_namespace` is pinned to the standard protoc convention `GPBMetadata\<Package>` (rather than managed mode's `<php_namespace>\GPBMetadata` default). This keeps the PHP metadata class name compatible with downstream contracts that import `core.proto` and are generated **without** managed mode. **Any project reusing these contracts should follow the same idea**: prefer managed mode on, and only add overrides when a name must interoperate with an external convention.
+
 ### Proto conventions
 
 - File name: `lower_snake_case`; messages: `UpperCamelCase`; fields: `lower_snake_case`; enum values: `UPPER_SNAKE_CASE`.

buf.gen.yaml

@@ -2,6 +2,15 @@ version: v2
 clean: true
 managed:
   enabled: true # derive csharp_namespace / php_namespace from the package
+  override:
+    # Emit the PHP metadata class in the standard protoc convention
+    # (GPBMetadata\<Package>) instead of managed mode's default
+    # (<php_namespace>\GPBMetadata). Downstream contracts generated without
+    # managed mode import core.proto and reference
+    # \GPBMetadata\Feather\Contracts\Core\V1\Core::initOnce(), so the emitted
+    # class name must match that convention.
+    - file_option: php_metadata_namespace
+      value: GPBMetadata\Feather\Contracts\Core\V1
 plugins:
   # C# messages + gRPC
   - remote: buf.build/protocolbuffers/csharp

composer.json

@@ -16,7 +16,8 @@
     },
     "autoload": {
         "psr-4": {
-            "Feather\\Contracts\\Core\\V1\\": "gen/php/Feather/Contracts/Core/V1/"
+            "Feather\\Contracts\\Core\\V1\\": "gen/php/Feather/Contracts/Core/V1/",
+            "GPBMetadata\\": "gen/php/GPBMetadata/"
         }
     },
     "archive": {

gen/csharp/Core.cs

@@ -37,7 +37,7 @@ static CoreReflection() {
             "B2NvbnRlbnQYASABKAxSB2NvbnRlbnRCsQEKHWNvbS5mZWF0aGVyLmNvbnRy",
             "YWN0cy5jb3JlLnYxQglDb3JlUHJvdG9QAaICA0ZDQ6oCGUZlYXRoZXIuQ29u",
             "dHJhY3RzLkNvcmUuVjHKAhlGZWF0aGVyXENvbnRyYWN0c1xDb3JlXFYx4gIl",
-            "RmVhdGhlclxDb250cmFjdHNcQ29yZVxWMVxHUEJNZXRhZGF0YeoCHEZlYXRo",
+            "R1BCTWV0YWRhdGFcRmVhdGhlclxDb250cmFjdHNcQ29yZVxWMeoCHEZlYXRo",
             "ZXI6OkNvbnRyYWN0czo6Q29yZTo6VjFiBnByb3RvMw=="));
       descriptor = pbr::FileDescriptor.FromGeneratedCode(descriptorData,
           new pbr::FileDescriptor[] { },