gpt-5.3-codex review phase 1 - Flatten the documentation

docs/ver4/error_handling_v4.md

@@ -1,115 +1,58 @@
 # Error Handling Policy (Version 4)
 
-This document defines the Version 4 taxonomy, contracts, and framework behavior used to satisfy the cross-version [Error Handling invariant](../invariant/error_handling.md).
+This policy defines active V4 error taxonomy, translation boundaries, and retry semantics.
 
-## Invariant Alignment
+## Error Categories
 
-Version 4 implements the invariant through:
+| Category | Meaning | Typical Origin | User Treatment |
+| :--- | :--- | :--- | :--- |
+| `validation` | Input payload/selection is invalid | UI form parsing, service validators | Inline correction guidance |
+| `not_found` | Target record is missing | ID lookup in service layer | Non-blocking warning or redirect |
+| `conflict` | State prevents requested action | lifecycle transitions, duplicate semantic keys | Explain required precondition |
+| `external` | Provider/network dependency failure | OpenRouter/provider adapter | Retry path and evidence retained |
+| `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 |
 
-- The shared error taxonomy below.
-- Structured error envelopes with correlation IDs.
-- Page-level failure isolation and explicit aggregate job status.
-- Atomic relationship and classification writes.
-- Consistent translation across API, UI, service, worker, persistence, and provider boundaries.
-- Bounded retry guidance based on category and idempotency.
+## Translation Boundaries
 
-## Scope and Authority
+- **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.
 
-This policy governs error behavior across:
+## Job and Page Failure Semantics
 
-- NiceGUI pages
-- FastAPI routes
-- Service-layer orchestration
-- `asyncio` worker tasks
-- Database interactions
-- Provider adapters
+### Page-Level (`JobSource`)
 
-## Error Taxonomy
+- `pending` -> `transcribed` when attempt succeeds.
+- `pending` -> `failed` when attempt fails terminally.
+- `pending` -> `cancelled` on job cancellation before processing.
 
-| Category | Definition | Retriable |
-| --- | --- | --- |
-| `validation_error` | Payload, parameter, or schema validation failure | no |
-| `user_input_error` | Unacceptable file, invalid selection, or malformed request from the operator | no |
-| `not_found_error` | Requested `Document`, `Source`, `Person`, `Job`, role, or type does not exist | no |
-| `conflict_error` | Operation violates uniqueness or relationship-write policy | no |
-| `external_provider_error` | Provider API failure, rate limit, or execution problem | yes |
-| `infrastructure_transient_error` | Temporary DB, file-system, or network instability | yes |
-| `infrastructure_persistent_error` | Persistent configuration, credential, or database availability failure | no |
-| `internal_unexpected_error` | Uncaught exception or logic defect | no |
+### Job-Level (`Job`)
 
-## Async Batch and Page-Level Error Behavior
+- `transcribed` when all pages transcribe successfully.
+- `partial_success` when mixed success/failure outcomes exist.
+- `failed` when no page transcribes successfully.
 
-In multi-page `asyncio` processing:
+## Retry and Retranscription Rules
 
-1. Exceptions from individual page calls are trapped within the page task wrapper.
-2. Failed page detail is written to `JobSource.error_detail` and the page state becomes `failed`.
-3. Aggregate job status is derived from page outcomes:
-   - all pages succeed -> `completed`
-   - some succeed and some fail -> `partial_success`
-   - all fail -> `failed`
-4. Successful pages remain valid even when sister pages fail.
+1. Failed/cancelled pages may be re-queued through retranscription workflows.
+2. Retry attempts must append new `ExecutionAttempt` rows; prior evidence remains immutable.
+3. Selecting a better candidate must update projection pointers, not mutate historical attempt rows.
 
-## Relationship and Classification Conflict Behavior
+## Logging and Diagnostics Rules
 
-When relationship or document-type writes fail policy checks:
+1. Persist sufficient attempt error metadata (`error_category`, `error_message`, transport evidence) for post-hoc analysis.
+2. Avoid leaking stack traces or local paths into user-facing message envelopes.
+3. Preserve causal exception chains for internal diagnostics.
 
-1. Reject the full write operation.
-2. Return structured conflict detail including target identifiers and the violated rule.
-3. Preserve existing persisted relationships unchanged.
+## UI Messaging Contract
 
-## API Error Response Contract
+- User-visible errors must be actionable, bounded, and category-consistent.
+- Multi-page jobs must show partial outcomes instead of collapsing into a single opaque failure.
+- Recovery actions (`retry`, `retranscribe`, `edit input`) must be offered where available.
 
-API error responses return a structured envelope:
+## Cross-Reference
 
-^^^json
-{
-  "error_id": "err_uuid_12345",
-  "category": "conflict_error",
-  "message": "Relationship write conflicts with existing links.",
-  "suggestion": "Adjust the requested relationship links and retry.",
-  "details": {
-    "document_id": "...",
-    "person_id": "...",
-    "attempted_role": "recipient",
-    "operation": "add_link",
-    "conflict_reason": "duplicate document-person-role link"
-  },
-  "timestamp": "2026-08-10T15:00:00Z"
-}
-^^^
-
-HTTP status mappings:
-
-- `validation_error`, `user_input_error` -> `400`
-- `not_found_error` -> `404`
-- `conflict_error` -> `409`
-- `external_provider_error` -> `502` or `503`
-- `infrastructure_transient_error` -> `503`
-- `infrastructure_persistent_error`, `internal_unexpected_error` -> `500`
-
-## UI Error Presentation Rules
-
-- Display concise failure summaries with the next action the operator can take.
-- Keep form state in context when feasible.
-- Distinguish validation issues, conflict issues, provider failures, and infrastructure failures.
-- For bulk relationship updates, identify the specific role or person that caused a conflict.
-
-## Logging and Audit Expectations
-
-- Log worker failures with correlation IDs and provider context.
-- Log relationship and classification conflicts with machine-readable detail.
-- Log persisted provider errors and page-level execution failures.
-
-## Retry Guidance
-
-- Do not auto-retry validation or conflict failures.
-- Permit user-driven retry after the input or selection changes.
-- Allow bounded retry for transient provider or infrastructure failures when the operation is idempotent.
-
-## Related Local References
-
-- [Error Handling Invariant](../invariant/error_handling.md)
-- [System Overview](index_v4.md)
+- [Error Handling invariant](../invariant/error_handling.md)
 - [System Requirements](requirements_v4.md)
 - [Data Model](schema_v4.md)
-- [System Architecture](architecture_v4.md)