System Requirements (Version 4)

These requirements define the active V4 contract and align to current implementation.

Functional Requirements

REQ-4-001 Document Registry: The system must create and update Document records with title, type, language, comments, date metadata, and optional location.
REQ-4-002 Source Registry: The system must create and update Source records linked to exactly one Document.
REQ-4-003 People Registry: The system must create and update Person records and support many-to-many links to Document with role and confidence.
REQ-4-004 Registry Semantics: Document types and person roles must support optional immutable semantic keys and hard-delete only when unreferenced.

REQ-4-010 Job Creation: The system must create Job records from uploaded sources and from retranscription of existing sources.
REQ-4-011 Prompt Snapshotting: Job creation must persist effective prompt and runtime settings as immutable per-job snapshots.
REQ-4-012 Queue Membership: Each (job, source) pair must be represented by one JobSource row.
REQ-4-013 Job Status Lifecycle: Job.status must use one of queued, processing, transcribed, completed, partial_success, failed.
REQ-4-014 JobSource Status Lifecycle: JobSource.status must use one of pending, transcribed, failed, cancelled.
REQ-4-015 Terminal Job Resolution: Job terminal status must derive from page outcomes as transcribed, partial_success, or failed.
REQ-4-016 Cancellation Semantics: Job cancellation must set remaining pending page entries to cancelled.

REQ-4-020 Attempt Evidence: Each provider call must emit one append-only ExecutionAttempt record.
REQ-4-021 Attempt Payload: ExecutionAttempt must retain request manifest/hash, outcome, timing, model/provider fields, and error details when present.
REQ-4-022 Transport Evidence: Provider response evidence must be attached to the attempt when a response is available.
REQ-4-023 Source Projection Rule: Source.raw_transcription is a projection chosen from attempt outcomes and can be repointed by explicit promotion.
REQ-4-024 Candidate Visibility: UI must expose candidate attempts with metadata needed for comparative review and selection.

REQ-4-030 Ingest Canonicalization: Stored source bytes may be normalized at ingest (for example orientation correction); stored bytes are the canonical processing source.
REQ-4-031 Path Safety: Client-facing media URLs must be generated from controlled application paths only.
REQ-4-032 Print Media Validation: Print/export source media must be served through record-validated API routes.

REQ-4-040 Error Envelope: Service/API errors must map to structured, user-safe error categories and messages.
REQ-4-041 Partial Failure Visibility: Mixed page outcomes must be visible at job and page level.
REQ-4-042 Retry Support: Failed and cancelled pages must support targeted retranscription without requiring full document recreation.

REQ-4-100 Boundary Integrity: UI pages/components must not access persistence directly and must call service APIs.
REQ-4-101 Service Ownership: Aggregate writes must occur in owning service/workflow modules, not in UI handlers.
REQ-4-102 Deterministic Loading: ORM relationship reads in service/UI code must use explicit eager loading compatible with lazy="raise".
REQ-4-103 Async Safety: Long-running provider calls must not block UI event handlers directly.
REQ-4-104 Evidence Durability: Attempt evidence must survive process restart once the transaction commits.
REQ-4-105 Test Guardrails: Architecture boundary tests must remain in place for services and UI boundaries.

Source of truth for status enums:
- src/transcription/db/models.py
Source of truth for workflow transitions:
- src/transcription/services/workflows.py
- src/transcription/services/jobs.py
Source of truth for attempt evidence writes:
- src/transcription/services/sources.py