gpt-5.3-codex review phase 1 (revised)

docs/ver4/schema_v4.md

@@ -87,7 +87,6 @@ erDiagram
 - `queued`
 - `processing`
 - `transcribed`
-- `completed` (legacy-compatible)
 - `partial_success`
 - `failed`
 
@@ -112,6 +111,31 @@ erDiagram
 4. `Job` terminal status is derived from `JobSource` outcomes.
 5. Registry semantic keys, when present, are immutable once created.
 
+## Schema Design Rationale
+
+### Why `ExecutionAttempt` exists alongside `JobSource`
+
+- `JobSource` is the mutable queue/projection row for workflow control and current-facing page outcome state.
+- `ExecutionAttempt` is the durable, append-only evidence timeline for each provider call.
+- Keeping both avoids overloading one table with competing concerns (queue state vs immutable audit history).
+
+### Why `Source.raw_transcription` remains on `Source`
+
+- `Source` needs a stable, current projection for UI and print behavior.
+- Projection reads are fast and direct, while deep historical inspection remains available through attempts.
+- Explicit candidate promotion updates the projection pointer without rewriting history.
+
+### Why semantic registries use UUID identity plus optional semantic keys
+
+- UUIDs are durable relationship identifiers for public/domain links.
+- Optional immutable semantic keys support protected built-ins without exposing internal meaning as external API identity.
+- Labels can evolve without breaking relationships.
+
+### Why status enums are narrow
+
+- Restricting `JobStatus` and `JobSourceStatus` keeps lifecycle transitions explicit and testable.
+- Queue/state transitions and terminal derivation logic remain deterministic across worker and UI flows.
+
 ## Media Storage Semantics
 
 1. `Source.storage_path` references canonical stored bytes used by processing.
@@ -123,6 +147,12 @@ erDiagram
 - Relationship access from service/UI layers must use explicit eager loading patterns compatible with `lazy="raise"`.
 - Candidate-attempt views should select latest/selected attempts explicitly; do not rely on implicit lazy traversal.
 
+## Evolution and Migration Policy
+
+- Additive schema evolution is preferred for evidence-bearing records.
+- Deprecated semantics should be removed only when model enums, service logic, tests, and docs are updated together.
+- Historical V4.x schema discussions are archived under tag `docs-v4x-archive`; this file is the active contract.
+
 ## Cross-Reference
 
 - [System Architecture](architecture_v4.md)