V1 mostly complete except for some testing. Linting in the last step changed nearly every file which is why this commit is so larger.

2026-07-29 17:27:21 -05:00
parent bc21a97019
commit a3b3bab571
37 changed files with 1383 additions and 410 deletions
@@ -0,0 +1,92 @@
+# V1 Data Migration and Recovery Guidance
+
+This document defines migration/backfill and rollback guidance for the V1 SQLite baseline.
+
+## Purpose
+
+- provide safe procedures for local schema evolution and recovery
+- reduce data-loss risk during version upgrades
+- establish repeatable pre-change and post-change checks
+
+## Current Baseline
+
+- canonical relational store: SQLite
+- default DB path: `./transcription.db`
+- schema bootstrap may apply compatibility updates for dev/test scenarios
+
+## Pre-Change Checklist
+
+Before changing runtime version or schema behavior:
+
+1. Stop the app process.
+2. Create a timestamped DB backup copy.
+3. Capture current app commit/version.
+4. Export a quick status inventory:
+   - job counts by status
+   - total documents/sources/revisions
+5. Ensure sufficient disk space.
+
+## Backup Procedure (SQLite)
+
+Minimum procedure:
+
+1. Stop app.
+2. Copy DB file to a safe location with timestamp.
+3. Store backup path in release notes or change log.
+
+## Upgrade Procedure (V1)
+
+1. Perform pre-change checklist.
+2. Deploy updated app version.
+3. Start app and observe startup logs.
+4. Verify schema bootstrap completes (if enabled).
+5. Run smoke flow:
+   - upload valid file
+   - observe terminal status
+   - open job detail
+
+## Backfill Guidance
+
+V1 backfill is limited and conservative:
+
+- for records missing newly introduced non-null defaults, use explicit one-time SQL updates only after backup
+- avoid destructive rewrites of `Job.text` or `Revision.text`
+- never backfill by overwriting original immutable transcription output
+
+## Rollback Procedure
+
+If upgrade fails or causes data inconsistency:
+
+1. Stop app.
+2. Restore prior DB backup file.
+3. Revert app version to last known-good commit.
+4. Restart app.
+5. Run smoke flow and confirm stability.
+
+## Recovery Scenarios
+
+### Stale processing jobs after crash/restart
+
+- restart app and allow stale-job recovery to re-queue timed-out `processing` jobs
+- monitor for terminal progression
+
+### Schema mismatch symptoms
+
+- errors during startup or writes indicating missing columns/indexes
+- rollback to last good DB + app version
+- reattempt with documented upgrade path
+
+## Validation Evidence
+
+For each upgrade rehearsal, capture:
+
+- backup filename/path
+- pre and post job status counts
+- smoke test result
+- rollback rehearsal result (recommended)
+
+## Operational Constraints
+
+- treat DB backups as required before non-trivial upgrades
+- do not perform in-place DB edits while app is running
+- do not skip post-upgrade smoke validation