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.