transcription/docs/ui/pages/sources.md

Sources Page Contract

Purpose

Sources manages individual archived page/file records. It provides source-media viewing, current processing context, provider evidence inspection, previous/next page navigation, and human revision without allowing machine output to be edited.

Routes

Route	Purpose
/sources	Global or filtered Source list.
/sources/{source_id}	View media, transcription, revision, metadata, and evidence.
/sources/{source_id}/delete	Confirm or block deletion.

The list accepts optional document_id and job_id query parameters. Document context takes precedence if both parse successfully.

List Behavior

• The title is Source Asset Records, Sources for Document, or Sources for Job according to context.
• Global context provides Create Job.
• Filtered context provides Back to Document or Back to Job.
• Rows are ordered by page number and then upload name.
• Columns are Document Name, Page Number, Upload Title, Status, and Error Detail.
• Document Name, Upload Title, and Error Detail are left-aligned; Status is centered.
• Stored Filename is intentionally absent from the list.
• Selecting a row opens Source Detail.
• No records displays No source asset records found in repository.

Detail Behavior

• The heading shows page number, upload name, and Source ID.
• Back to Sources returns to the global list.
• 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.
• 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.

Provider Evidence

• Provider Evidence is associated with the latest JobSource execution.
• AI Metadata and the current raw_api_response value are displayed as expandable formatted JSON.
• Missing evidence has an explicit empty state.
• Under the current V4 implementation, raw_api_response is an OpenRouter SDK response snapshot, not an exact HTTP or native upstream-provider response.

Revision Behavior

• Machine transcription is never edited directly.
• A revision must contain non-whitespace text.
• Save persists revised text and updates the saved timestamp without leaving the page.
• Reset restores the in-memory revision from page load or the most recent successful save. When no revision exists, it restores the machine transcription; it does not re-read the database.
• A failed latest execution displays guidance that a human revision can preserve corrected text.

Delete Behavior

• Deletion is allowed only when the Source has no JobSource links.
• A linked Source shows cleanup guidance and navigation to Jobs.
• An unlinked Source requires explicit permanent deletion.
• Success returns to the Sources list.

Acceptance Checklist

• Global, Document-filtered, and Job-filtered lists show the correct context and return action.
• 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.
• 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.

Implementation Anchors

• src/transcription/ui/pages/sources_page.py
• src/transcription/ui/components/table/sources.py
• src/transcription/services/sources.py
• tests/ui/test_sources_page.py
• tests/services/test_transcription_service.py
• tests/services/test_v2_crud.py

Planned Changes

• V4.2 will rename and separate evidence layers, add exact OpenRouter transport capture, and preserve append-only attempts. See the V4.2 scope.
• Source page reordering is deferred to the draft V4.3 scope.