transcription/docs/requirements.md

System Requirements (Version 4)

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

Functional Requirements

Domain and Record Management

• 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.

Job and Workflow Behavior

• 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, 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.

Transcription and Evidence

• 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.

Media and Access

• 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.

Error and UX Contracts

• 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.

Non-Functional Requirements

• 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.

Requirement Interpretation Notes

Status and lifecycle semantics

• REQ-4-013 and REQ-4-015 intentionally bind success to transcribed, not a generic completed, so docs, tests, and runtime transitions stay consistent.
• REQ-4-016 and REQ-4-042 distinguish cancellation from failure at page level (cancelled vs failed) while still allowing targeted retranscription.

Evidence semantics

• REQ-4-020 through REQ-4-024 separate authoritative history (ExecutionAttempt) from operational projection (Source.raw_transcription).
• This supports immutable provenance while allowing explicit candidate promotion for operator workflows.

Boundary and loading semantics

• REQ-4-100 and REQ-4-101 codify aggregate/service ownership and keep UI out of persistence concerns.
• REQ-4-102 exists to enforce deterministic query shape under lazy="raise" and avoid hidden data access in rendering callbacks.

Verification Anchors

• Service boundary enforcement: tests/test_service_boundaries.py
• UI boundary enforcement: tests/test_ui_boundaries.py
• Job lifecycle reliability and terminal status behavior: tests/services/test_workflows_reliability.py
• Evidence append-only and projection behavior: tests/services/test_store.py, tests/services/test_transcription_service.py

Traceability Notes

• 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