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

docs/ui/README.md

@@ -57,5 +57,4 @@ Each page contract contains:
 
 ## Current Baseline
 
-These contracts describe the completed V4 through V4.4 behavior.
-V4.5 planned behavior remains defined by its frozen scope and implementation plan until implementation updates the applicable page contracts.
+These contracts describe the completed V4 through V4.5 behavior.

docs/ui/pages/jobs.md

@@ -36,6 +36,8 @@ Jobs manages transcription processing runs. A Job belongs to one Document, links
 - Files can be removed individually or cleared before submission.
 - Helper text explains numeric filename prefixes for page ordering.
 - Submission creates the Job, Source records, and JobSource links, notifies the worker, and opens Job Detail.
+- When opened with `source_id`, creation becomes a retranscription flow: Source and Document are locked, Provider is
+  read-only, Model is restricted to `PROVIDER_MODELS`, no upload is accepted, and one existing Source is linked.
 
 ## Detail and Lifecycle Behavior
 
@@ -61,7 +63,7 @@ Jobs manages transcription processing runs. A Job belongs to one Document, links
 - The page explains that resubmission queues failed linked Sources while preserving immutable prior attempt evidence.
 - The service blocks submission while processing is active or when no failed Sources exist.
 - `JobSource` remains the latest compatibility projection, while every provider call appends an `ExecutionAttempt`.
-- The latest successful `Source.raw_transcription` projection remains available while a retry is pending or fails.
+- The selected `Source.raw_transcription` projection remains available while a retry is pending or fails.
 - Success reports the number of resubmitted Sources and returns to Job Detail.
 
 ## Delete Behavior

docs/ui/pages/sources.md

@@ -30,14 +30,20 @@ The list accepts optional `document_id` and `job_id` query parameters. Document
 
 - The heading shows page number, upload name, and Source ID.
 - **Back to Sources** returns to the global list.
+- **Retranscribe Source** opens Create Processing Job with this Source and its Document locked.
 - **Delete Source** opens the guarded delete route.
 - Previous and Next navigate only among Sources belonging to the same Document in page order; unavailable boundary actions are disabled.
 - The media viewer resolves the stored Source path through the configured upload root.
-- Transcription Text is read-only and prefers the latest JobSource transcription, then the Source projection.
+- Transcription Text is read-only and displays the preferred machine projection, with a legacy latest-JobSource
+  fallback only when no Source projection exists.
 - Editable Revision is seeded from an existing revision or the machine transcription.
 - Source Metadata shows upload name, stored filename, page number, Document Name, Document ID, and stored path. Source ID appears in the page-header subtitle.
 - SourceJob Metadata shows latest status, Job ID, execution time, provider, model, prompt, and failure detail.
 - Revision Logistics shows revised state, last-revised time, and upload time.
+- Candidate Machine Transcriptions remains compact until a candidate is expanded, then compares it with the preferred
+  machine result and requires confirmation before **Use this transcription**.
+- Candidate promotion does not alter a human revision. Empty states distinguish no machine result from no candidates.
+- An orientation-normalized artifact appears in evidence only when recognized metadata required a physical rotation.
 
 ## Provider Evidence
 
@@ -47,6 +53,7 @@ The list accepts optional `document_id` and `job_id` query parameters. Document
 - Historical `raw_api_response` values are labeled as OpenRouter SDK response snapshots.
 - Missing evidence has an explicit empty state.
 - Historical executions explicitly state that exact transport evidence was not captured.
+- Quality warning artifacts remain attached to their machine attempt and are not recomputed during page rendering.
 - **Export Evidence** downloads a versioned package containing source identity, attempts, artifacts, relationships,
   schema versions, and integrity digests without source binaries, credentials, or machine-local source paths.
 
@@ -71,6 +78,7 @@ The list accepts optional `document_id` and `job_id` query parameters. Document
 - List columns and alignments match this contract and omit Stored Filename.
 - Previous/next navigation never crosses Document boundaries.
 - Detail keeps machine output read-only and human revision separately editable.
+- Retranscription, candidate comparison, warnings, and explicit promotion preserve every prior attempt.
 - Empty, failed, and missing-evidence states remain explicit.
 - JSON evidence is readable without being mislabeled as native transport evidence.
 - Delete cannot remove a Source with processing-history links.

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