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

.github/instructions/error-handling.instructions.md

@@ -23,13 +23,38 @@ Use category-driven semantics aligned to canonical V4 policy:
 - `internal`
 
 Do not invent ad hoc categories in user/API-facing envelopes unless canonical docs are updated.
-Service-layer exceptions must normalize to this category set before crossing service boundaries.
+
+Runtime/internal categories may be more specific for diagnostics and persistence, but they must map
+deterministically to the canonical envelope categories through the centralized mapper in
+`transcription.errors.canonical_error_category`.
+
+Current internal 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`
+
+Required internal -> canonical mapping:
+
+- `validation_error`, `user_input_error` -> `validation`
+- `not_found_error` -> `not_found`
+- `conflict_error` -> `conflict`
+- `external_provider_error` -> `external`
+- `external_timeout_error`, `infrastructure_transient_error` -> `timeout`
+- `processing_error`, `infrastructure_persistent_error`, `internal_unexpected_error` -> `internal`
 
 ## Translation Boundaries
 
 - **Provider/adapters:** raise provider/domain exceptions; do not emit UI text.
-- **Services:** map raw exceptions into domain categories and preserve causal chain (`raise ... from ...`).
-- **UI/API:** emit user-safe, actionable messages based on category + operation context.
+- **Services:** map raw exceptions into internal categories and preserve causal chain (`raise ... from ...`).
+- **UI/API:** map internal category -> canonical envelope category and emit user-safe, actionable messages.
 
 ## Retry Rules