Revised and simplified V4 Plan and core documents.

docs/ver4/error_handling_v4.md

@@ -1,62 +1,68 @@
 # Error Handling Policy (Version 4)
 
-This document defines canonical error-handling behavior for V4 document-person relationship expansion.
-
-V4 keeps V3 transcription error behavior and adds policy/conflict handling for role extensibility, suggestion lifecycle transitions, and exclusivity enforcement.
+This document defines the canonical error-handling policy for the document transcription system.
 
 ## Error Handling Objectives
 
-- Provide clear, actionable conflict and validation feedback for relationship write operations.
-- Prevent partial, silent, or destructive relationship mutations when policy checks fail.
-- Preserve suggestion review auditability with deterministic accept/reject outcomes.
-- Keep consistent API/UI/service error envelopes across relationship workflows.
+- Make failures visible in clear, actionable language at both the document and page levels.
+- Support isolated failure handling in multi-page jobs so one failing page does not invalidate successful pages.
+- Preserve diagnostic detail for validation failures, provider failures, and policy conflicts.
+- Ensure consistent error envelope structure across API, UI, service, and worker boundaries.
 
 ## Scope and Authority
 
-Governs relationship-related error behavior in:
+This policy governs error behavior across:
 
-- NiceGUI document/person relationship views,
-- FastAPI relationship and suggestion endpoints,
-- domain services for relationship sync and suggestion review,
-- persistence constraints for role, state, and exclusivity invariants.
+- NiceGUI pages
+- FastAPI routes
+- Service-layer orchestration
+- `asyncio` worker tasks
+- Database interactions
+- Provider adapters
 
-## Relationship Error Taxonomy
+## Error Taxonomy
 
 | Category | Definition | Retriable |
 | --- | --- | --- |
-| `validation_error` | Payload shape/type invalid, unknown role/state, malformed IDs | no |
-| `not_found_error` | Target `Document`, `Person`, role, or suggestion record does not exist | no |
-| `conflict_error` | Write violates uniqueness or exclusivity policy | no |
-| `suggestion_state_error` | Invalid suggestion transition (for example accept after reject) | no |
-| `policy_violation_error` | Action blocked by configured role matrix or governance rule | no |
-| `infrastructure_transient_error` | Temporary DB or network instability during relationship operation | yes |
-| `infrastructure_persistent_error` | Persistent DB/configuration failure | no |
-| `internal_unexpected_error` | Unhandled exception/logic defect | no |
+| `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 exclusivity 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 |
 
-## Deterministic Conflict Behavior
+## Async Batch and Page-Level Error Behavior
 
-When relationship writes fail policy checks:
+In multi-page `asyncio` processing:
 
-1. Reject the full write operation (no partial apply).
-2. Return structured conflict details including conflicting role pair and target identifiers.
-3. Preserve existing canonical relationships unchanged.
+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.
 
-When suggestion transitions fail:
+## Relationship and Classification Conflict Behavior
 
-1. Reject invalid state transition.
-2. Return current state and allowed next actions.
-3. Preserve suggestion record integrity.
+When relationship or document-type writes fail policy checks:
+
+1. Reject the full write operation.
+2. Return structured conflict detail including target identifiers and the violated rule.
+3. Preserve existing persisted relationships unchanged.
 
 ## API Error Response Contract
 
-Relationship endpoints return a structured envelope:
+API error responses return a structured envelope:
 
 ^^^json
 {
   "error_id": "err_uuid_12345",
   "category": "conflict_error",
   "message": "Role assignment violates exclusivity policy.",
-  "suggestion": "Remove recipient role before assigning author for this person on this document.",
+  "suggestion": "Remove recipient before assigning author for this person on this document.",
   "details": {
     "document_id": "...",
     "person_id": "...",
@@ -64,41 +70,41 @@ Relationship endpoints return a structured envelope:
     "conflicting_role": "recipient",
     "policy_rule": "author+recipient exclusive"
   },
-  "timestamp": "2026-08-09T15:00:00Z"
+  "timestamp": "2026-08-10T15:00:00Z"
 }
 ^^^
 
 HTTP status mappings:
 
-- `validation_error` -> `400`
+- `validation_error`, `user_input_error` -> `400`
 - `not_found_error` -> `404`
-- `conflict_error`, `suggestion_state_error`, `policy_violation_error` -> `409`
+- `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 conflict summary with actionable next step.
-- Keep user edits in context (do not discard form state when feasible).
-- Differentiate between validation issues, policy conflicts, and infrastructure failures.
-- For bulk role sync operations, show per-item conflict context when multiple failures occur.
+- 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 relationship write failures with correlation IDs.
-- Log suggestion acceptance/rejection outcomes with actor and timestamp where available.
-- Log policy matrix violations with deterministic machine-readable context.
+- 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.
 
-## Relationship-Specific Retry Guidance
+## Retry Guidance
 
-- Do not auto-retry policy or conflict failures.
-- Permit user-driven retry only after input changes.
-- Retry infrastructure transient failures with bounded policy in service layer if operation is idempotent.
+- 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
 
-- [V4 Scope Boundary](scope_boundary_v4.md)
-- [V4 Requirements](requirements_v4.md)
-- [V4 Schema](schema_v4.md)
-- [V4 Architecture](architecture_v4.md)
-- [V3 Error Handling](../error_handling_v3.md)
+- [System Overview](index_v4.md)
+- [System Requirements](requirements_v4.md)
+- [Data Model](schema_v4.md)
+- [System Architecture](architecture_v4.md)