fix(error): align templates with Error Specification ADR (#48)

yordis · web-flow · commit 53ac7ec9cdb6 · 2026-05-06T01:46:01.000-04:00
Signed-off-by: Yordis Prieto &lt;yordis.prieto@gmail.com&gt;
diff --git a/docs/README.md b/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)
diff --git a/docs/explanation/consistency-pattern.md b/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.
 
diff --git a/docs/explanation/google-rpc-error-template.md b/docs/explanation/google-rpc-error-template.md
@@ -0,0 +1,78 @@
+# 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
+
+This package is based on [ADR 0129349218: Error Specification](https://straw-hat-team.github.io/adr/adrs/0129349218/README.html). The ADR defines the broader error model: stable error identity, structured metadata, visibility-aware filtering, help links, retry guidance, and boundary processing.
+
+`trogon.error.v1alpha1` is the shared-protobuf projection of that model. It keeps the pieces that can safely live in published descriptors and maps them to Google RPC rich error details.
+
+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.
+
+This is the intentional difference from the full ADR model. The ADR still describes internal runtime errors and internal metadata filtering. Shared protos do not name that visibility because naming an internal descriptor value invites accidental publication.
+
+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
+
+- [ADR 0129349218: Error Specification](https://straw-hat-team.github.io/adr/adrs/0129349218/README.html)
+- [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)
diff --git a/docs/explanation/protobuf-extension-naming.md b/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)
 ```
 
diff --git a/docs/how-to/document-errors-in-proto.md b/docs/how-to/document-errors-in-proto.md
@@ -2,6 +2,10 @@
 
 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.
+
+This is the protobuf projection of [ADR 0129349218: Error Specification](https://straw-hat-team.github.io/adr/adrs/0129349218/README.html). The ADR explains the full boundary model; this guide only documents the descriptor fields that are safe to share.
+
 ## Example
 
 ```proto
@@ -20,13 +24,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 +41,71 @@ 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
 
+- [ADR 0129349218: Error Specification](https://straw-hat-team.github.io/adr/adrs/0129349218/README.html)
 - [../../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)
diff --git a/proto/trogon/consistency/v1alpha1/consistency.proto b/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.
diff --git a/proto/trogon/error/v1alpha1/options.proto b/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;
 }
diff --git a/proto/trogon/error/v1alpha1/visibility.proto b/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;
 }
