transcription/docs/phase3-codex-prompt.md

You are working in the `transcription` repository (Python 3.12+, FastAPI, NiceGUI, SQLModel/SQLAlchemy, Pydantic V2, asyncio). Follow `.github/instructions/error-handling.instructions.md` and `.github/instructions/services.instructions.md` for any code you touch, and keep `docs/ver4/*` as canonical authority for intended behavior. Do not modify unrelated code.

**Prerequisite:** This prompt assumes Phases 1-2 (`docs/phase1-codex-prompt.md`, `docs/phase2-codex-prompt.md`) are already merged.

## Goal

Implement **Phase 3 (Reliability & concurrency)** from `docs/architecture-code-review-2026-08-20.md`, addressing:

### [HIGH-03] Runtime and persisted error categories drift from canonical V4 policy
**Location:** `src/transcription/errors.py:12-24`, `src/transcription/errors.py:62-76`, `src/transcription/services/store.py:121-128`, `src/transcription/services/store.py:198-206`, `src/transcription/services/workflows.py:602-623`

**Problem:** Canonical V4 policy (`docs/ver4/error_handling_v4.md`) and `.github/instructions/error-handling.instructions.md` define six canonical error categories: `validation`, `not_found`, `conflict`, `external`, `timeout`, `internal`. But runtime code in `src/transcription/errors.py` still carries a richer internal enum (`validation_error`, `external_provider_error`, `infrastructure_transient_error`, etc.), and those raw non-canonical values get persisted directly to `ExecutionAttempt.error_category`. Worse, database/storage record-creation failures in `store.py` (lines 121-128, 198-206) are classified as `INFRA_TRANSIENT`, which the API/UI mapping layer turns into `timeout` — even though a DB write failure is not a timeout. Operators therefore receive category signals that don't match the documented taxonomy or the actual failure mode. `workflows.py:602-623` is a downstream consumer of these categories and needs review once the taxonomy changes.

**You must choose one of two remediation strategies — read `docs/ver4/error_handling_v4.md` and `.github/instructions/error-handling.instructions.md` fully before deciding, and justify your choice in your final report:**

**Option (a) — Collapse to canonical values end-to-end:**
- Reduce the runtime `errors.py` enum to exactly the six canonical categories.
- Update every raise site and every persisted-category write path (including `ExecutionAttempt.error_category`) to use only canonical values.
- Fix the specific `store.py` misclassification: database/storage record-creation failures must map to a category that reflects an infrastructure/internal failure, not `timeout`. Determine the correct canonical category (likely `internal` or `external`, per the documented semantics of each — do not guess without checking the doc's definitions).

**Option (b) — Explicit two-layer taxonomy:**
- Keep the richer internal enum but explicitly document (in `docs/ver4/error_handling_v4.md` and `.github/instructions/error-handling.instructions.md`) that internal categories are authoritative for diagnostics/evidence, while a deliberate, documented mapping table converts them to the six canonical categories at the API/UI envelope boundary.
- Ensure the mapping table is centralized (not duplicated across call sites) and is itself unit-tested.
- Still fix the `store.py` mapping: DB/storage failures must not map to `timeout`.

**Either way, required work:**
- Do not leave storage/DB failures mapped to `timeout` under any resolution.
- Update `tests/test_errors.py` (and any other test asserting category behavior, e.g. tests referencing `ExecutionAttempt.error_category` or API error envelopes) to reflect the finalized taxonomy.
- Update `docs/ver4/error_handling_v4.md` and `.github/instructions/error-handling.instructions.md` together with the code change so docs/instructions/runtime/tests move as one atomic unit — per the review's explicit warning against updating only one of these.
- Review `src/transcription/services/workflows.py:602-623` for correct behavior against the finalized taxonomy (e.g. retry/backoff decisions keyed off error category should still make sense).

### Verify operator messaging and retry semantics after taxonomy cleanup
- After the taxonomy change, walk through any UI-facing error message templates or API error envelope construction that branches on error category, and confirm the operator-visible messaging still makes sense (e.g. a DB failure should not say "request timed out").
- Confirm retry/backoff logic (in `workflows.py` or wherever retries are orchestrated) that depends on error category still selects the correct retry behavior for each category post-cleanup (e.g. `external`/`timeout` should still be retryable where appropriate; `validation`/`not_found`/`conflict` should not).
- Add or extend tests covering at least one representative case per category to confirm messaging and retry decisions are correct.

## Validation

- Run `pytest` (via the project's normal invocation, e.g. `uv run pytest`) and ensure all tests pass, including updated/added tests for the taxonomy and retry behavior.
- Run `ruff check` and `ty check` and ensure no new issues are introduced by your changes.
- Do not touch UI/service consolidation (Phase 4) or provenance/env config and ruff/ty baseline cleanup (Phase 5) — those are out of scope for this task.

Report back with: which remediation option you chose and why, the final canonical/internal category mapping (if option b), all files changed, the corrected `store.py` category for DB/storage failures, and final `pytest`/`ruff`/`ty` results.