transcription/docs/requirements.md

System Requirements (Current Baseline: V6.1)

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

Requirement IDs encode the baseline that introduced them (REQ-4-* from V4, REQ-6-* from V6) and are stable. Never renumber an existing ID; retire it explicitly instead.

Functional Requirements

Domain and Record Management

• REQ-4-001 Document Registry: The system must create and update Document records with title, type, date metadata, optional location, optional archive identifier, and optional notes.
• 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, support many-to-many links to Document with role, and support many-to-many Person tagging via the shared Tag registry.
• 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.

Person Imagery

• REQ-6-001 Photo Records: The system must store reusable Photo records that are either owned by a Person or unowned for homepage gallery use.
• REQ-6-002 Primary Photo: At most one photo per owning Person may be marked is_primary; setting a new primary must clear the previous one.
• REQ-6-003 Primary Reassignment: Deleting an owner's primary photo must promote a remaining photo of that owner rather than leaving the owner without a primary.

Operational Maintenance

• REQ-6-010 Queued Maintenance Runs: Settings-initiated maintenance must persist a MaintenanceRun and execute in the worker, not inline in the request that started it.
• REQ-6-011 Maintenance Run Types: MaintenanceRun.job_type must use one of backup, storage_reconciliation, gedcom_import.
• REQ-6-012 Maintenance Status Lifecycle: MaintenanceRun.status must use one of queued, processing, succeeded, failed.
• REQ-6-013 Single Claim: A queued run must be claimed by at most one worker, using a conditional status update rather than read-then-write.
• REQ-6-014 Run History: Completed runs must retain status, timing, summary, log reference, and error detail, and expose the log for viewing and download.
• REQ-6-015 GEDCOM Upload Import: Settings must support manual .ged upload and queue-backed import into genealogy tables.
• REQ-6-016 GEDCOM Idempotent Upsert: GEDCOM import must upsert GenealogyPerson and GenealogyFamily by FamilySearch IDs and avoid duplicate imported citations on re-run.

Deployment and Runtime Configuration

• REQ-6-020 Production Persistence: Production must run against PostgreSQL; SQLite remains supported for local development and tests.
• REQ-6-021 Split Worker Deployment: Production must support running the worker as its own process with the app started at RUN_EMBEDDED_WORKER=false.
• REQ-6-022 Runtime Settings Persistence: Runtime settings edits must persist to the mounted production environment file and survive container restart.
• REQ-6-023 Configuration Contract Sync: .env.production.example must stay synchronized with Settings keys and production-safe defaults.
• REQ-6-024 Health Reporting: The deployed stack must report app and worker health through /healthz.
• REQ-6-025 Backup and Restore: Database and media/config backups must be produced on a host-visible path with a tested restore procedure.

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
• Person photo ownership and primary selection: tests/services/test_photo_service.py
• Maintenance run lifecycle and worker execution: tests/services/test_maintenance_service.py
• Runtime settings persistence: tests/ui/test_runtime_settings_store.py, tests/services/test_settings_services.py
• Configuration contract synchronization: tests/test_meta_contract_guards.py
• Deployment health reporting: tests/api/test_health.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