gpt-5.3 codex review: Phase 4

docs/phase-4-implementation-task-specs.md

@@ -0,0 +1,253 @@
+# Phase 4: Implementation Task Specifications
+
+## Objective
+
+Convert the canonical V4 baseline into executable, worker-ready implementation tasks that close remaining drift risk and harden enforcement.
+
+Canonical authority for all tasks:
+
+- `docs/ver4/*`
+- `.github/instructions/services.instructions.md`
+- `.github/instructions/ui.instructions.md`
+- `.github/instructions/error-handling.instructions.md`
+- `.github/skills/python-code-reviewer/skill.md`
+- `.github/skills/evidence-provenance-auditor/skill.md`
+
+---
+
+## Dependency-Ordered Task Graph
+
+| Task ID | Title | Depends On | Priority |
+| :--- | :--- | :--- | :--- |
+| P4-01 | Meta-contract regression guards | - | P0 |
+| P4-02 | Error taxonomy and translation conformance | P4-01 | P0 |
+| P4-03 | Evidence append-only write-path hardening | P4-01 | P0 |
+| P4-04 | Job/Page lifecycle consistency hardening | P4-02, P4-03 | P0 |
+| P4-05 | Eager-loading and `lazy="raise"` conformance sweep | P4-01 | P1 |
+| P4-06 | Media route/path safety enforcement sweep | P4-01 | P1 |
+| P4-07 | Duration semantics split for telemetry correctness | P4-04 | P1 |
+| P4-08 | Reviewer/instruction enforcement tests in CI path | P4-01..P4-07 | P1 |
+
+---
+
+## Task Specifications
+
+## P4-01 — Meta-contract regression guards
+
+**Goal:** Add deterministic tests preventing drift from canonical docs/instructions/skills contracts.
+
+**Scope:**
+
+- `tests/` (new focused tests)
+- optionally small helper in `tests/conftest.py` if needed
+
+**Required changes:**
+
+1. Add a test that fails if active docs/instructions/skills reference removed V4 revision paths.
+2. Add a test that asserts canonical authority references exist where required (services/ui/error-handling instructions and reviewer skills).
+3. Keep checks text-based and stable; avoid brittle full-document snapshots.
+
+**Acceptance criteria:**
+
+- Test suite fails on any reintroduction of legacy-path authority references.
+- Test suite passes with current baseline.
+
+**Validation command:** `uv run pytest tests -k "contract or instruction or skill"`
+
+---
+
+## P4-02 — Error taxonomy and translation conformance
+
+**Goal:** Ensure service/API/UI error translation matches canonical categories and boundaries.
+
+**Scope:**
+
+- `src/transcription/services/**/*.py`
+- `src/transcription/api/**/*.py`
+- `src/transcription/ui/**/*.py`
+- related tests under `tests/services`, `tests/api`, `tests/ui`
+
+**Required changes:**
+
+1. Normalize service-edge exceptions to canonical categories:
+   - `validation`, `not_found`, `conflict`, `external`, `timeout`, `internal`.
+2. Ensure causal chain preservation (`raise ... from ...`) on translation.
+3. Ensure UI/API emits user-safe envelopes/messages without stack/path/secret leakage.
+4. Add/adjust tests for category mapping and envelope shape.
+
+**Acceptance criteria:**
+
+- No ad hoc category values in user/API-facing error envelopes.
+- Translation boundaries are deterministic and test-covered.
+
+**Validation command:** `uv run pytest tests/services tests/api tests/ui -k "error or envelope or category"`
+
+---
+
+## P4-03 — Evidence append-only write-path hardening
+
+**Goal:** Guarantee each provider call appends new `ExecutionAttempt` evidence and never rewrites attempt history.
+
+**Scope:**
+
+- `src/transcription/services/sources.py`
+- `src/transcription/services/workflows.py`
+- `src/transcription/services/evidence.py`
+- `src/transcription/db/models.py` (only if required for bug fix)
+- tests under `tests/services`
+
+**Required changes:**
+
+1. Audit all attempt-write paths for accidental update/overwrite behavior.
+2. Enforce append-only semantics for retries and reprocessing.
+3. Keep `Source.raw_transcription` and preferred pointers as projection-only mutation surfaces.
+4. Add/strengthen tests proving historical attempts are unchanged across retries/promotions.
+
+**Acceptance criteria:**
+
+- Reprocessing/retry produces new attempts, never history rewrite.
+- Projection changes do not mutate prior attempt evidence.
+
+**Validation command:** `uv run pytest tests/services -k "attempt or evidence or retry or promotion"`
+
+---
+
+## P4-04 — Job/Page lifecycle consistency hardening
+
+**Goal:** Enforce coherent status transitions and cancellation semantics across `Job` and `JobSource`.
+
+**Scope:**
+
+- `src/transcription/services/jobs.py`
+- `src/transcription/services/workflows.py`
+- related tests under `tests/services`
+
+**Required changes:**
+
+1. Verify terminal `Job.status` resolution from page outcomes only:
+   - `transcribed`, `partial_success`, `failed`.
+2. Ensure cancellation transitions remaining `pending` pages to `cancelled`.
+3. Ensure lifecycle language and emitted behavior never reintroduce legacy `completed` semantics.
+4. Add/adjust reliability tests for mixed outcomes and cancel/retry edges.
+
+**Acceptance criteria:**
+
+- Job and page-level transitions remain consistent under success/failure/partial/cancel paths.
+- No legacy terminal vocabulary in behavior contracts or emitted statuses.
+
+**Validation command:** `uv run pytest tests/services/test_workflows_reliability.py tests/services -k "job or cancel or partial_success"`
+
+---
+
+## P4-05 — Eager-loading and `lazy="raise"` conformance sweep
+
+**Goal:** Eliminate hidden lazy-load access in service/UI read paths.
+
+**Scope:**
+
+- `src/transcription/services/**/*.py`
+- `src/transcription/ui/pages/**/*.py`
+- `src/transcription/ui/components/**/*.py`
+
+**Required changes:**
+
+1. Audit relationship access sites and ensure explicit eager-loads where needed.
+2. Fix any read-path assumptions that rely on implicit lazy loading.
+3. Add targeted tests for high-risk rendering/read paths.
+
+**Acceptance criteria:**
+
+- Read paths that touch relationships function with `lazy="raise"` constraints intact.
+
+**Validation command:** `uv run pytest tests/services tests/ui -k "boundary or lazy or load"`
+
+---
+
+## P4-06 — Media route/path safety enforcement sweep
+
+**Goal:** Ensure all UI/print media flows use approved record-validated or controlled resolver patterns.
+
+**Scope:**
+
+- `src/transcription/api/v4_print.py`
+- `src/transcription/ui/components/media_urls.py`
+- `src/transcription/ui/pages/**/*.py`
+- `src/transcription/ui/components/**/*.py`
+- tests in `tests/ui` and `tests/api` where applicable
+
+**Required changes:**
+
+1. Remove any direct filesystem path exposure to clients.
+2. Ensure print/export media access is record-validated.
+3. Ensure UI media URL construction uses resolver helper only.
+4. Add tests that fail on unsafe URL/path construction patterns.
+
+**Acceptance criteria:**
+
+- No `file://` usage or raw absolute-path emission in UI/API responses.
+- Media links resolve through approved paths only.
+
+**Validation command:** `uv run pytest tests/ui tests/api -k "media or print or path"`
+
+---
+
+## P4-07 — Duration semantics split for telemetry correctness
+
+**Goal:** Separate provider-call latency from end-to-end processing duration so model rollups are not misleading.
+
+**Scope:**
+
+- `src/transcription/services/workflows.py`
+- `src/transcription/db/models.py` and migration surface if schema needs extension
+- `docs/ver4/schema_v4.md` (same change if model fields evolve)
+- tests in `tests/services`
+
+**Required changes:**
+
+1. Introduce explicit timing fields or calculation paths that distinguish:
+   - provider call duration
+   - full processing duration
+2. Keep existing invariants and backward compatibility behavior explicit.
+3. Add tests covering success, timeout, and failure timing writes.
+4. Update schema docs if persistence contract changes.
+
+**Acceptance criteria:**
+
+- Telemetry consumers can compute provider performance without preprocessing/commit skew.
+- Timing semantics are test-backed and documented.
+
+**Validation command:** `uv run pytest tests/services -k "duration or timeout or workflow"`
+
+---
+
+## P4-08 — Enforcement coverage in CI path
+
+**Goal:** Ensure critical invariant checks run in the normal validation path.
+
+**Scope:**
+
+- existing test organization and runner configs only
+
+**Required changes:**
+
+1. Ensure boundary/provenance/contract tests are discoverable by default `pytest` runs.
+2. Add grouping markers only if already consistent with project test conventions.
+3. Avoid introducing new tooling; reuse existing test stack.
+
+**Acceptance criteria:**
+
+- A standard repo test run exercises meta-contract, boundary, and provenance guards.
+
+**Validation command:** `uv run pytest`
+
+---
+
+## Worker Handoff Contract (apply to every task)
+
+Each worker delivery must include:
+
+1. Files changed.
+2. Behavior change summary.
+3. Why the change satisfies the invariant/contract.
+4. Targeted test command(s) and result summary.
+5. Explicit note if `docs/ver4/schema_v4.md` was updated due to model/persistence changes.

docs/ver4/schema_v4.md

@@ -198,7 +198,7 @@ Index:
 | `router_request_id` | `str \| None` | optional |
 | `router_generation_id` | `str \| None` | optional |
 | `sdk_response_snapshot` | `dict[str, JsonValue] \| None` | JSONBCompat |
-| `normalized_metadata` | `dict[str, JsonValue] \| None` | JSONBCompat |
+| `normalized_metadata` | `dict[str, JsonValue] \| None` | JSONBCompat; may include app-namespaced `processing_timing` (`provider_call_duration_ms`, `processing_duration_ms`) |
 | `software_context` | `dict[str, JsonValue] \| None` | JSONBCompat |
 | `raw_transcription` | `str \| None` | optional |
 | `error_category` | `str \| None` | optional |