V4.5 Complete - Enhanced trancription context, added option to restranscribe source under different models.

docs/ver4/architecture_v4.md

@@ -137,11 +137,12 @@ Responsibilities:
 
 1. User uploads one or more images for a `Document`.
 2. System stores files, hashes them, creates ordered `Source` rows, and creates a `Job`.
-3. Worker claims the job, marks it `processing`, and executes page calls concurrently.
+3. Worker claims the job, marks it `processing`, resolves metadata-directed orientation, and sends either the
+   immutable original or an exact normalized derivative to the provider.
 4. Each provider call appends an `ExecutionAttempt` with its request manifest, transport evidence, SDK snapshot,
    normalized metadata, timing, and outcome.
-5. The linked `JobSource` is updated as a compatibility projection, and a successful attempt updates the
-   `Source.raw_transcription` latest-success projection.
+5. The linked `JobSource` is updated as a compatibility projection. The first successful attempt establishes
+   `Source.preferred_execution_attempt_id` and `Source.raw_transcription`; later successes remain candidates.
 6. Aggregate status becomes `completed`, `partial_success`, or `failed`.
 
 ### 2. Document-Person Relationship Management
@@ -170,13 +171,18 @@ Responsibilities:
 ## V4 Domain Rules
 
 - `JobSource.raw_transcription` preserves page output for its Job execution.
-- `Source.raw_transcription` is the latest-success machine-output projection for a page.
+- `Source.raw_transcription` is the selected preferred-machine-output projection for a page.
+- `Source.preferred_execution_attempt_id` identifies its exact immutable provenance; candidate promotion updates
+  both fields atomically.
 - Human corrections occur only in `Source.revised_text`.
 - Prompt and parameter provenance is frozen on `Job` at submission time.
 - The SDK-serialized OpenRouter response snapshot is stored on `JobSource` for each successful page execution.
 - Every V4.2 provider call appends a distinct `ExecutionAttempt`; retries never rewrite earlier attempts.
 - Exact response bytes identify the OpenRouter HTTP boundary and are not labeled as native upstream-provider JSON.
 - Generic `ProcessingArtifact` records use versioned schemas, digests, and one inline or external content location.
+- Orientation-normalized model inputs and deterministic quality warnings are versioned `ProcessingArtifact` evidence
+  attached to the consuming `ExecutionAttempt`.
+- A `retranscription` Job contains one locked existing Source and freezes one configured allowlisted model.
 - `DocumentPerson` links are unique for `(document_id, person_id)` and require one `role_id`.
 - Relationship mutations are deterministic, set-based, and atomic with Document writes.
 - `DocumentType.id` and `PersonRole.id` are canonical relationship identities; unique labels may evolve.

docs/ver4/requirements_v4.md

@@ -15,7 +15,7 @@ This document defines the baseline requirements for the document transcription s
 | REQ-6 | Functional | Support an extensible role taxonomy for document-person relationships. | inspection |
 | REQ-7 | Policy Constraint | Enforce deterministic relationship-role writes with uniqueness on `(document_id, person_id)` and explicit conflict responses for duplicate Person links. | test |
 | REQ-8 | Functional | Use set-based synchronization for document-person mutations so updates add and remove only the intended links. | test |
-| REQ-9 | Functional | Maintain immutable machine output on `Source.raw_transcription` while permitting inline human edits on `Source.revised_text`. | test |
+| REQ-9 | Functional | Maintain selected machine output and exact attempt provenance on `Source` while permitting independent human edits on `Source.revised_text`. | test |
 | REQ-10 | Functional | Support a UUID-identified `DocumentType` taxonomy with unique user-facing labels and active/inactive lifecycle control. | test |
 | REQ-11 | Data Constraint | Store `Document` type as a controlled reference to `DocumentType`. | test |
 | REQ-12 | Interface | Render multi-page transcriptions sequentially by `page_number` with document, people, and document-type metadata. | demonstration |
@@ -31,6 +31,9 @@ This document defines the baseline requirements for the document transcription s
 | REQ-22 | Interface | Provide safe browser-native Facsimile and Text-only print views from persisted Document Detail. | demonstration |
 | REQ-23 | Security | Escape stored print text and serve Source images through record-validated application routes without disclosing local paths. | test |
 | REQ-24 | Functional | Print current human-preferred Source text, semantic Author metadata, deterministic Source order, and oldest-to-newest Job metadata. | test |
+| REQ-25 | Quality | Physically apply recognized raster orientation metadata to provider-input derivatives without changing original Source bytes. | test |
+| REQ-26 | Quality | Persist deterministic, non-mutating output warnings without automatic paid retries. | test |
+| REQ-27 | Functional | Create one-Source retranscription Jobs from a configured model allowlist and preserve later successes as candidates until explicit promotion. | test |
 
 ## Clarifying Constraints
 

docs/ver4/schema_v4.md

@@ -71,6 +71,7 @@ UUID id PK
 UUID document_id FK
 VARCHAR status
 INTEGER retry_count
+VARCHAR purpose
 TEXT provider
 TEXT model
 TEXT prompt_name
@@ -93,6 +94,7 @@ TEXT file_path
 TEXT file_hash
 BIGINT file_size_bytes
 TEXT raw_transcription
+UUID preferred_execution_attempt_id FK
 TEXT revised_text
 TIMESTAMPTZ date_uploaded
 TIMESTAMPTZ date_revised
@@ -177,7 +179,9 @@ EXECUTION_ATTEMPT ||--o{ PROCESSING_ARTIFACT : produces
 - `EXECUTION_ATTEMPT(job_id, source_id, attempt_number)` is unique; retries increment the persisted attempt number.
 - Historical `JOB_SOURCE` rows without an `EXECUTION_ATTEMPT` remain SDK snapshots and are explicitly labeled as
   lacking transport evidence.
-- `SOURCE.raw_transcription` caches the latest successful machine output for that page.
+- `SOURCE.raw_transcription` caches the explicitly selected preferred machine output for that page.
+- `SOURCE.preferred_execution_attempt_id` records exact successful-attempt provenance. Legacy projections may remain
+  null until a new successful result is selected.
 
 ### Generic Processing Artifacts
 
@@ -185,6 +189,8 @@ EXECUTION_ATTEMPT ||--o{ PROCESSING_ARTIFACT : produces
 - Exactly one of `inline_payload` and `external_reference` is populated.
 - Externally stored artifacts use application-managed relative references and are verified by SHA-256 and byte size.
 - Coordinate metadata declares units, origin, dimensions, and transformations when geometry is present.
+- Orientation-normalized binary model inputs and JSON quality-warning results use distinct versioned artifact types
+  and are attached to the exact consuming `EXECUTION_ATTEMPT`.
 
 ### Image Storage and Integrity
 
@@ -195,7 +201,7 @@ EXECUTION_ATTEMPT ||--o{ PROCESSING_ARTIFACT : produces
 ### Page Ordering and Revisions
 
 - `SOURCE.page_number` dictates page ordering within a document.
-- `SOURCE.raw_transcription` remains immutable machine output.
+- `SOURCE.raw_transcription` changes only through first-success selection or explicit candidate promotion.
 - `SOURCE.revised_text` stores human edits and is the preferred display value when present.
 
 ### Semantic Registry Governance