chore(error): anchor templates on Google RPC

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

docs/README.md

@@ -1,5 +1,6 @@
 # Documentation
 
 - [Document Errors in Proto](how-to/document-errors-in-proto.md)
+- [Google RPC Error Templates](explanation/google-rpc-error-template.md)
 - [Protobuf Extension Naming](explanation/protobuf-extension-naming.md)
 - [Consistency Pattern](explanation/consistency-pattern.md)

docs/explanation/consistency-pattern.md

@@ -121,12 +121,12 @@ When projection fails to meet consistency requirements, return appropriate gRPC
 **Projection Timeout** (timeout exceeded):
 - Status Code: `UNAVAILABLE` (503)
 - Use `google.rpc.ErrorInfo` for structured error details
-- Suggested metadata: min_version, current_version, attempts, elapsed_ms
+- Suggested metadata: `minVersion`, `currentVersion`, `attempts`, `elapsedMs`
 
 **Snapshot Expired** (ExactVersion only, version moved past):
 - Status Code: `FAILED_PRECONDITION` (400)
 - Use `google.rpc.ErrorInfo` for structured error details
-- Suggested metadata: requested_version, current_version
+- Suggested metadata: `requestedVersion`, `currentVersion`
 
 Consider using `google.rpc.Status` with `google.rpc.ErrorInfo` for rich error responses that clients can programmatically handle.
 

docs/explanation/google-rpc-error-template.md

@@ -0,0 +1,71 @@
+# Google RPC Error Templates
+
+Trogon error options describe the Google RPC rich error details a runtime should emit. They are descriptor metadata, not a replacement for gRPC, Connect, or HTTP error envelopes.
+
+## Why This Exists
+
+Without a shared proto annotation, every runtime has to construct `google.rpc.Status`, `google.rpc.ErrorInfo`, and related details by hand. That makes stable fields such as `domain`, `reason`, and metadata keys easy to drift across languages.
+
+The `trogon.error.v1alpha1` package keeps that contract close to the typed error payload message. Code generators and runtime adapters can read the same descriptor metadata and produce consistent Google RPC details.
+
+## Mapping
+
+| Trogon template field | Google RPC target |
+|-----------------------|-------------------|
+| `code` | `google.rpc.Status.code` |
+| `message` | `google.rpc.Status.message` |
+| `domain` | `google.rpc.ErrorInfo.domain` |
+| `reason` | `google.rpc.ErrorInfo.reason` |
+| `metadata` | `google.rpc.ErrorInfo.metadata` |
+| `help_links` | `google.rpc.Help.links` |
+
+Payload fields annotated with `trogon.error.v1alpha1.field` supply emission-specific `ErrorInfo.metadata` values. Template metadata supplies fixed metadata values that apply to every emission. Metadata keys should use lowerCamelCase; payload fields use their protobuf JSON names.
+
+## Boundaries
+
+Trogon error templates do not declare which RPC can return an error. That belongs in a method-level outcome option.
+
+Trogon error templates also do not model successful outcomes. `trogon.error.v1alpha1.Code` intentionally mirrors only Google RPC error codes and omits `OK`.
+
+Shared error protos should expose only public or private metadata. Internal-only metadata belongs in runtime enrichment, observability pipelines, or internal-only overlays because descriptor annotations are visible to anyone who receives the proto.
+
+The runtime owns protocol adaptation. A gRPC runtime can emit `google.rpc.Status` with typed details. A Connect runtime can expose the same semantics through Connect errors and strongly typed details.
+
+## Example
+
+A template like this:
+
+```proto
+message UserNotFoundError {
+  option (trogon.error.v1alpha1.message).template = {
+    domain: "identity.trogonstack.dev"
+    reason: "USER_NOT_FOUND"
+    message: "The requested user was not found."
+    code: NOT_FOUND
+    visibility: VISIBILITY_PUBLIC
+  };
+
+  string user_id = 1 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC];
+}
+```
+
+describes this Google RPC detail identity:
+
+```json
+{
+  "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+  "domain": "identity.trogonstack.dev",
+  "reason": "USER_NOT_FOUND",
+  "metadata": {
+    "userId": "usr_123"
+  }
+}
+```
+
+The surrounding transport error still comes from the runtime protocol. Trogon only defines the stable error detail contract.
+
+## References
+
+- [Document Errors in Proto](../how-to/document-errors-in-proto.md)
+- [Google RPC Status](https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status)
+- [Google RPC ErrorInfo](https://cloud.google.com/spanner/docs/reference/rpc/google.rpc#errorinfo)

docs/explanation/protobuf-extension-naming.md

@@ -108,7 +108,7 @@ trogon/stream/v1alpha1/options.proto
 
 trogon/error/v1alpha1/options.proto
 ├─ MessageOptions        { template }               → message (870012)
-│  └─ Template (nested)  { domain, reason, message, code }
+│  └─ Template (nested)  { domain, reason, message, code, help_links, metadata }
 └─ FieldOptions          { visibility }             → field (870013)
 ```
 

docs/how-to/document-errors-in-proto.md

@@ -2,6 +2,8 @@
 
 This guide shows the intended protobuf shape for typed error payload messages that use `trogon.error.v1alpha1`.
 
+Trogon error annotations are descriptor-time templates for the Google RPC rich error model. They describe the `google.rpc.Status` and `google.rpc.ErrorInfo` details a runtime should emit when the typed error occurs.
+
 ## Example
 
 ```proto
@@ -20,13 +22,12 @@ message ResourceAvailabilityError {
       {url: "https://docs.acme.com/compute", description: "Compute Docs"}
     ]
     metadata: [
-      {key: "component", value: "compute", visibility: VISIBILITY_PUBLIC},
-      {key: "team", value: "platform-compute", visibility: VISIBILITY_INTERNAL}
+      {key: "component", value: "compute", visibility: VISIBILITY_PUBLIC}
     ]
   };
 
-  string zone = 1;
-  string vm_type = 2;
+  string zone = 1 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC];
+  string vm_type = 2 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC];
   string service = 3 [(trogon.error.v1alpha1.field) = {
     visibility: VISIBILITY_PUBLIC,
     default_value: "compute-api"
@@ -38,18 +39,70 @@ message ResourceAvailabilityError {
 }
 ```
 
+## Runtime Mapping
+
+When a runtime emits this error, it should build the protocol-native error envelope from the template:
+
+| Trogon option | Google RPC field |
+|---------------|------------------|
+| `code` | `google.rpc.Status.code` |
+| `message` | `google.rpc.Status.message` |
+| `domain` | `google.rpc.ErrorInfo.domain` |
+| `reason` | `google.rpc.ErrorInfo.reason` |
+| `metadata` | `google.rpc.ErrorInfo.metadata` |
+| Payload fields | `google.rpc.ErrorInfo.metadata` using proto JSON names |
+| `help_links` | `google.rpc.Help.links` |
+
+For the example above, a runtime could emit this JSON representation of a `google.rpc.Status`:
+
+```json
+{
+  "code": 8,
+  "message": "Requested resources are unavailable.",
+  "details": [
+    {
+      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+      "reason": "RESOURCE_AVAILABILITY",
+      "domain": "compute.googleapis.com",
+      "metadata": {
+        "component": "compute",
+        "region": "us-east-1",
+        "service": "compute-api",
+        "vmType": "n2-standard-16",
+        "zone": "us-east1-b"
+      }
+    },
+    {
+      "@type": "type.googleapis.com/google.rpc.Help",
+      "links": [
+        {
+          "description": "Compute Docs",
+          "url": "https://docs.acme.com/compute"
+        }
+      ]
+    }
+  ]
+}
+```
+
 ## Notes
 
 - `template` is a message field, so it carries proto3 presence by default.
-- The template captures the parts of the error contract that never vary at runtime: `domain`, `reason`, `code`, default `message`, error-level `visibility`, `help_links`, and fixed `metadata` entries.
-- `metadata` declares contract-level constants (component, team, subsystem) that attach to every emission without occupying a wire field. Keys must be unique within the template and must not collide with field names on the payload message.
+- The template captures the parts of the Google RPC error contract that never vary at runtime: `domain`, `reason`, `code`, default `message`, error-level `visibility`, `help_links`, and fixed `metadata` entries.
+- `domain` and `reason` describe the `google.rpc.ErrorInfo` identity for this error. `reason` must be stable within the `domain`.
+- `metadata` declares contract-level constants (component, product, support category) that attach to every emission without occupying a wire field. Keys should use lowerCamelCase, must be unique within the template, and must not collide with field names on the payload message.
 - Payload fields hold the dynamic context for a single emission. Each field can carry `FieldOptions`:
-  - `visibility` controls who sees the field at runtime (defaults to `INTERNAL`).
+  - `visibility` controls who sees the field at runtime. `VISIBILITY_UNSPECIFIED` is invalid for emitted metadata.
   - `value_policy.default_value` substitutes a value when the runtime field is empty.
   - `value_policy.value` pins the field to a contract-fixed value; the runtime payload is ignored on emit.
+- Payload fields use their protobuf JSON names as `ErrorInfo.metadata` keys. For example, `vm_type` emits `vmType`.
+- Shared protos should use only `VISIBILITY_PUBLIC` and `VISIBILITY_PRIVATE`. Internal-only metadata belongs in runtime enrichment or internal overlays, not shared descriptors.
+- `visibility` is a Trogon filtering policy. It is not part of `google.rpc.ErrorInfo`.
 
 ## References
 
 - [../../proto/trogon/error/v1alpha1/code.proto](../../proto/trogon/error/v1alpha1/code.proto)
 - [../../proto/trogon/error/v1alpha1/options.proto](../../proto/trogon/error/v1alpha1/options.proto)
 - [../../proto/trogon/error/v1alpha1/visibility.proto](../../proto/trogon/error/v1alpha1/visibility.proto)
+- [Google RPC Status](https://cloud.google.com/tasks/docs/reference/rpc/google.rpc#status)
+- [Google RPC ErrorInfo](https://cloud.google.com/spanner/docs/reference/rpc/google.rpc#errorinfo)

proto/trogon/consistency/v1alpha1/consistency.proto

@@ -102,7 +102,7 @@ message Consistency {
   // - Maximum: 5s (values above should be clamped and logged)
   //
   // If projection doesn't reach required version within timeout, query should return
-  // unavailable error with appropriate error metadata (e.g., projection_timeout).
+  // unavailable error with appropriate error metadata (e.g., projectionTimeout).
   optional google.protobuf.Duration timeout_duration = 3;
 
   // Delay between retry attempts.

proto/trogon/error/v1alpha1/options.proto

@@ -9,38 +9,44 @@ import "trogon/error/v1alpha1/visibility.proto";
 option (elixirpb.file).module_prefix = "TrogonProto.Error.V1Alpha1";
 
 // MessageOptions defines message-level options for error payload messages.
+//
+// These annotations describe the Google RPC rich error details a runtime
+// should emit for this payload. They are not a transport envelope; runtimes
+// adapt the template into google.rpc.Status, google.rpc.ErrorInfo, google.rpc.Help,
+// or equivalent protocol-native details.
 message MessageOptions {
   // Template defines the static error template for a message that can be
-  // adapted into a runtime error representation.
+  // adapted into a runtime Google RPC error representation.
   //
   // These fields are intentionally language-neutral so both Elixir and Go
   // runtimes can derive their native error template APIs from the same proto
   // annotation.
   message Template {
-    // domain identifies the logical owner of the error contract.
+    // domain maps to google.rpc.ErrorInfo.domain.
     // Example: "compute.googleapis.com"
     string domain = 1;
 
-    // reason identifies the stable machine-readable error reason.
+    // reason maps to google.rpc.ErrorInfo.reason.
     // Example: "RESOURCE_AVAILABILITY"
     string reason = 2;
 
-    // message is the default human-readable message template.
+    // message maps to google.rpc.Status.message.
     string message = 3;
 
-    // code is the canonical error code for the template.
+    // code maps to google.rpc.Status.code.
     Code code = 4;
 
     // visibility controls who can see this error at runtime.
-    // When unset, defaults to INTERNAL for safety.
+    // UNSPECIFIED is invalid for emitted error details.
     Visibility visibility = 5;
 
-    // help_links provides documentation or support links for this error.
+    // help_links maps to google.rpc.Help links.
     repeated HelpLink help_links = 6;
 
     // metadata declares fixed key/value pairs attached to every emission
-    // of this error. Unlike struct fields with FieldOptions.value, these
-    // entries have no wire representation on the payload message — they
+    // of this error. Runtimes copy these entries into
+    // google.rpc.ErrorInfo.metadata. Unlike struct fields with FieldOptions.value,
+    // these entries have no wire representation on the payload message — they
     // are part of the error contract itself.
     //
     // Keys must be unique within a template and must not collide with
@@ -61,8 +67,8 @@ message MessageOptions {
 
   // MetadataEntry declares a fixed metadata pair on a Template.
   message MetadataEntry {
-    // key is the metadata key. Lowercase snake_case, matching the
-    // convention used for FieldOptions-derived metadata keys.
+    // key is the metadata key. Use lowerCamelCase to match
+    // google.rpc.ErrorInfo.metadata guidance.
     string key = 1;
 
     // value is the literal value attached at every emission. Template
@@ -72,7 +78,7 @@ message MessageOptions {
     string value = 2;
 
     // visibility controls who can see this metadata at runtime.
-    // When unset, defaults to INTERNAL for safety.
+    // UNSPECIFIED is invalid for emitted error details.
     Visibility visibility = 3;
   }
 
@@ -83,10 +89,13 @@ message MessageOptions {
 }
 
 // FieldOptions defines field-level options for error payload message fields.
+//
+// Runtimes copy payload fields into google.rpc.ErrorInfo.metadata unless a
+// value policy supplies a default or fixed value.
 message FieldOptions {
   // visibility controls who can see this metadata field at runtime.
   //
-  // When unset, defaults to INTERNAL for safety.
+  // UNSPECIFIED is invalid for emitted error details.
   Visibility visibility = 1;
 
   oneof value_policy {
@@ -119,13 +128,12 @@ extend google.protobuf.MessageOptions {
   //       visibility: VISIBILITY_PUBLIC,
   //       help_links: [{url: "https://docs.acme.com/compute", description: "Compute Docs"}],
   //       metadata: [
-  //         {key: "component", value: "compute", visibility: VISIBILITY_PUBLIC},
-  //         {key: "team",      value: "platform-compute", visibility: VISIBILITY_INTERNAL}
+  //         {key: "component", value: "compute", visibility: VISIBILITY_PUBLIC}
   //       ]
   //     };
   //
-  //     string zone = 1;
-  //     string vm_type = 2;
+  //     string zone = 1 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC];
+  //     string vm_type = 2 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC];
   //     string service = 3 [(trogon.error.v1alpha1.field) = {
   //       visibility: VISIBILITY_PUBLIC,
   //       default_value: "compute-api"
@@ -153,11 +161,11 @@ extend google.protobuf.FieldOptions {
   //       domain: "identity.acme.com",
   //       reason: "USER_NOT_FOUND",
   //       message: "The requested user was not found.",
-  //       code: NOT_FOUND
+  //       code: NOT_FOUND,
+  //       visibility: VISIBILITY_PUBLIC
   //     };
   //
   //     string user_id = 1 [(trogon.error.v1alpha1.field).visibility = VISIBILITY_PUBLIC];
-  //     string internal_trace = 2; // defaults to INTERNAL
   //   }
   optional FieldOptions field = 870013;
 }

proto/trogon/error/v1alpha1/visibility.proto

@@ -7,22 +7,20 @@ option (elixirpb.file).module_prefix = "TrogonProto.Error.V1Alpha1";
 
 // Visibility controls who can see a given error metadata field.
 //
-// This aligns with the three-tier model in the Trogon Error runtime
-// (Trogon.Error.MetadataValue.visibility/0).
+// Visibility is an exposure contract for shared descriptors. It is not a
+// secrecy boundary for data encoded in proto annotations: anyone with the
+// descriptor can read those keys and values. Internal-only metadata belongs in
+// runtime enrichment, observability pipelines, or internal-only overlays.
 //
-// Default (unspecified) is treated as INTERNAL for safety.
+// Code generators should reject UNSPECIFIED for emitted error details.
 enum Visibility {
   VISIBILITY_UNSPECIFIED = 0;
 
-  // INTERNAL fields are only visible to internal systems and developers.
-  // Use for stack traces, debug identifiers, internal correlation IDs.
-  VISIBILITY_INTERNAL = 1;
-
   // PRIVATE fields are visible to authenticated users but not the general public.
   // Use for account-specific context that the caller owns.
-  VISIBILITY_PRIVATE = 2;
+  VISIBILITY_PRIVATE = 1;
 
   // PUBLIC fields are visible to all users including end consumers.
   // Use for identifiers the caller already knows or non-sensitive context.
-  VISIBILITY_PUBLIC = 3;
+  VISIBILITY_PUBLIC = 2;
 }