claude-sonnet-5 review Phase 3 (by gpt-5.3-codex)

docs/ver4/error_handling_v4.md

@@ -13,11 +13,46 @@ This policy defines active V4 error taxonomy, translation boundaries, and retry
 | `timeout` | Provider call exceeded configured bound | worker/provider client timeout | Retry path and bounded messaging |
 | `internal` | Unexpected local failure | unhandled service/runtime faults | Safe generic message + diagnostics capture |
 
+## Runtime Taxonomy and Canonical Mapping
+
+Runtime code uses a richer internal taxonomy for diagnostics and persisted evidence, then maps that
+taxonomy to the six canonical categories at the API/UI envelope boundary.
+
+### Internal runtime categories
+
+- `validation_error`
+- `user_input_error`
+- `not_found_error`
+- `conflict_error`
+- `external_provider_error`
+- `external_timeout_error`
+- `processing_error`
+- `infrastructure_transient_error`
+- `infrastructure_persistent_error`
+- `internal_unexpected_error`
+
+### Internal -> Canonical mapping
+
+| Internal category | Canonical envelope category |
+| :--- | :--- |
+| `validation_error` | `validation` |
+| `user_input_error` | `validation` |
+| `not_found_error` | `not_found` |
+| `conflict_error` | `conflict` |
+| `external_provider_error` | `external` |
+| `external_timeout_error` | `timeout` |
+| `infrastructure_transient_error` | `timeout` |
+| `processing_error` | `internal` |
+| `infrastructure_persistent_error` | `internal` |
+| `internal_unexpected_error` | `internal` |
+
+`ExecutionAttempt.error_category` stores the internal category value so diagnostics remain specific.
+
 ## Translation Boundaries
 
 - **Provider layer:** raise provider-scoped exceptions with provider context; do not emit UI text.
-- **Service layer:** map raw exceptions into domain-aware categories and preserve causal chain.
-- **UI/API layer:** convert category to user-safe message with contextual action guidance.
+- **Service layer:** map raw exceptions into internal categories and preserve causal chain.
+- **UI/API layer:** convert internal categories to canonical categories using the centralized mapping.
 
 ## Decision Context