gpt-5.3-codex review phase 1 (revised)

docs/ver4/error_handling_v4.md

@@ -19,6 +19,25 @@ This policy defines active V4 error taxonomy, translation boundaries, and retry
 - **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.
 
+## Decision Context
+
+### Why taxonomy is category-based (not exception-class-based)
+
+- Categories encode operator-facing recovery semantics (fix input, retry later, investigate internal failure) independent of low-level exception type.
+- This keeps retry and messaging behavior consistent even when provider/client libraries change.
+
+### Why page-level failure is isolated
+
+- Multi-page archival documents often contain a mix of readable and degraded pages.
+- Isolating failures to page scope preserves successful results and avoids all-or-nothing loss when one page fails.
+- Aggregate job status then communicates overall outcome (`transcribed`, `partial_success`, `failed`) without hiding page detail.
+
+### Why retries append evidence instead of mutating rows
+
+- Retry operations are new observations, not corrections of history.
+- Appending attempts preserves forensic traceability, timing history, and provider variability analysis.
+- Projection updates remain explicit user/workflow decisions, separate from immutable evidence.
+
 ## Job and Page Failure Semantics
 
 ### Page-Level (`JobSource`)
@@ -45,6 +64,12 @@ This policy defines active V4 error taxonomy, translation boundaries, and retry
 2. Avoid leaking stack traces or local paths into user-facing message envelopes.
 3. Preserve causal exception chains for internal diagnostics.
 
+## Operator Recovery Guidance
+
+- **validation/conflict:** correct input or state and retry manually.
+- **external/timeout:** allow bounded retries and keep prior attempt evidence visible.
+- **internal:** stop automatic retries, surface a safe message, and inspect diagnostics with correlation context.
+
 ## UI Messaging Contract
 
 - User-visible errors must be actionable, bounded, and category-consistent.