transcription/docs/ui/pages/jobs.md

Jobs Page Contract

Purpose

Jobs manages transcription processing runs. A Job belongs to one Document, links one or more Source pages, records processing provenance, and exposes lifecycle actions without making lifecycle fields directly editable.

Routes

Route	Purpose
/jobs	Searchable processing Job list.
/jobs/new	Create and queue a Job.
/jobs/{job_id}	View status, execution logistics, and related records.
/jobs/{job_id}/cancel	Confirm cancellation.
/jobs/{job_id}/resubmit	Confirm resubmission of failed Sources.
/jobs/{job_id}/delete	Confirm or block deletion.

List Behavior

• The title is Transcription Pipeline Jobs.
• Create job opens Job creation and Refresh reloads the table.
• Columns are Job ID, Status, Document Name, # Sources, Retries, and Updated.
• Updated is the primary date/sort field.
• Search covers Job ID, document name, and status.
• Status is displayed as a semantic status chip.
• Selecting a row opens Job Detail.
• Global Job-list row navigation includes list context so Job Detail provides Back to Jobs.
• No records displays No job records found in repository.

Create Behavior

• A Target Document and at least one source file are required.
• document_id may preselect a Target Document.
• If no Documents exist, the page explains the prerequisite and links to Document creation with a return path.
• Provider and Model are selectable when creating a new Job.
• Upload accepts JPEG, PNG, TIFF, and PDF files and supports multiple/folder selection.
• The visible upload queue is sorted alphabetically by original filename.
• 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

• The heading shows Job ID and a status badge.
• Job Detail includes a contextual back action: Back to Jobs by default and Back to Document when opened from a Document-filtered Job list.
• Execution Logistics shows provider, model, prompt, retry count, and last update.
• Document Links show a clickable Document Name (with Job context), Sources count, and a single View Sources action using job filtering.
• Queued and processing Jobs show an auto-refresh notice and reload every four seconds.
• Polling stops when the Job becomes terminal or a refresh fails.
• Queued and processing Jobs expose Cancel.
• Jobs other than transcribed expose Resubmit under the current UI rule. The service blocks resubmission while processing is active or when no failed Sources exist.
• All Jobs expose Delete Job, subject to explicit evidence-deletion guardrails.
• Invalid and missing IDs produce explicit states.

Cancel Behavior

• The confirmation explains that processing stops and remaining pending Sources become cancelled.
• The service decides whether the current state permits cancellation.
• Success updates the Job, notifies the worker, and returns to Job Detail.

Resubmit Behavior

• The page shows current status and failed Source count.
• 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 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

• Deletion is blocked while status is processing.
• Allowed deletion explicitly warns that related JobSource projections, immutable execution attempts, captured transport responses, and attempt-owned artifacts are permanently removed.
• Source records and source files remain available for separate deletion.
• Success returns to the Jobs list.

Acceptance Checklist

• Job creation cannot proceed without a valid Document and at least one Source.
• Upload ordering and removal controls match the displayed queue.
• Detail shows current status and provenance summary with correct related links.
• Active Jobs refresh without overlapping permanent polling after terminal state.
• Cancel, resubmit, and delete honor service guardrails and show actionable failures.
• Lifecycle fields cannot be edited directly.

Implementation Anchors

• src/transcription/ui/pages/jobs_page.py
• src/transcription/ui/components/table/jobs.py
• src/transcription/services/jobs.py
• src/transcription/services/store.py
• src/transcription/services/workflows.py
• tests/ui/test_jobs_page.py
• tests/services/test_job_service.py
• tests/services/test_store.py