Transcription checkpoints and recovery

Approved 2026-11-04. Extend the same checkpoint job to accept finalized chunks while its recording is still open. This is one inference per saved chunk, not repeated inference over a moving audio buffer or live word-by-word captions.

Concurrency tests must cover catching up before Stop (no publication/polish), new chunks arriving during inference and at worker exit, Stop during inference, Stop before job creation, an unregistered final tail, live failure followed by continued capture and explicit Retry, process reopen, append generations, duplicate/conflicting sealing, and migration of existing frozen jobs. Physical device acceptance must check continuous audio, screen-off progress, and sustained heat/speed. Smaller post-Stop wait is expected, but real-time completion is not promised when inference is slower than capture. Existing source audio remains the recovery authority; no new transcription path repairs or deletes it.

Save each successfully transcribed WAV chunk before starting the next one. When interrupted work resumes, load those results and start at the first unfinished chunk. If chunks 0 through 11 have committed and the process dies while transcribing chunk 12, recovery starts at chunk 12. No completed chunk needs Whisper again, and no saved text is appended twice.

Recovery also needs to know whether Whisper has finished, whether automatic polish has finished, and whether the recording has been incorporated into its session. A chunk counter alone cannot protect those later steps.

Keep the existing worker pool. On the Motorola Edge 50 Fusion the current CPU selector chooses four threads: four cores report 1,958,400 kHz and four report 2,400,000 kHz; the selector counts the faster group. The code currently detects this count rather than fixing it globally. Persist the selected count in each job so retries use the same setting. This implementation does not change the CPU selection policy or the debug benchmark’s thread choices.

Review clarification: retain CPU-aware selection rather than a universal four-thread limit. The existing upstream heuristic has edge cases to assess separately: its minimum of two can oversubscribe a single available CPU, while equal-frequency cores can fall through to two threads even on a larger device. Any hardening should bound the result by available processors and handle homogeneous CPUs explicitly. More threads are not automatically faster; the current phone’s representative results support four workers, not a rule that every core must be used. No selector changes are included in this implementation.

These are source-derived failure windows, not evidence that every one occurred in the user’s historical runs. Source entry points are listed below.

Use the existing SQLDelight/SQLite database for both results and work state. Avoid a second checkpoint file plus a database counter: those would require a separate protocol to keep two stores consistent.

The additive migration creates two tables and records active-job/capture intent on a recording:

Empty result text is a valid successful checkpoint for silence. Null means unfinished. Do not derive completion from nonblank text, a progress callback, or the presence of a WAV alone. A unique job/chunk key prevents double insertion; an identical duplicate commit is harmless, while a conflicting result is an error rather than an overwrite. Derive progress and the next unfinished chunk from the manifest/results; an independently maintained cursor is unnecessary.

For completed captures, freeze and validate the ordered manifest after capture is finalized. The extension above registers a growing closed prefix before sealing it. Parse numeric indices from canonical chunk filenames, reject gaps/duplicates and invalid WAVs, and select the append range by those indices. Validate the expected PCM format and whole samples. A valid finalized zero-sample tail can commit an empty result without invoking Whisper; an incomplete/invalid header is not equivalent to that valid empty WAV. No silent skipping of damaged files. Compute identity from the same bytes decoded for inference. Source files are immutable during a job; recheck their identities on recovery, including files whose results were already saved. Unexpected additions or changes pause the job for diagnosis rather than extending its manifest or deleting checkpoints.

Identify the actual model contents and the decoder contract (vendored revision, language, decoding parameters, audio format, text-joining rules). A filename or the app version alone is insufficient. Reuse a verified download fingerprint if available, otherwise hash the model when establishing/validating identity; do not hash the whole model for every chunk. A mismatch pauses recovery and preserves all results. Explicitly starting a different transcription generation can be designed later without erasing the previous one.

The job’s start index remains distinct from its saved-result frontier. A later microphone resume creates a new Append job for new chunks and retains the earlier job and transcript versions. Do not infer job kind from rawText after the job has started.

The durable stages are:

Failure or a conflict can pause any unfinished stage without moving it back to the beginning. Recording status is a UI/queue projection; the job determines which operation needs to run. Each database transition checks the expected job ID, attempt ID, stage, recording existence, and relevant version IDs inside a short transaction. Model inference, filesystem reads, and suspend calls stay outside that transaction. A process-local mutex alone is not a durable completion guard. Each new worker ownership gets an attempt ID, so a delayed result from a stopped service instance cannot commit over its successor. Duplicate requests to a live owner do not replace that token. Checkpoint completion guards and explicit deletion queries must work even if the driver has not enabled foreign keys; verify the driver’s configuration rather than assuming declared FKs enforce it.

Edits to the existing prefix are retained when publishing an Append job. If source raw text or recording membership changed incompatibly before publication, preserve the checkpoint results and current versions and pause for review. Do not overwrite a newer user version to satisfy an outdated job. Serialize membership changes, deletion, and finalization through transactional repository operations with these guards. Explicit recording/session deletion removes its checkpoint rows as part of the same operation; a late inference result cannot recreate a deleted recording or its job.

Title generation stays with its existing durable queue after transcript finalization. Completion notifications are best-effort signals after commits; they do not determine recovery state. Chunk text stays in checkpoint rows until the complete range is published, so title generation and ordinary transcript editing never mistake a partial prefix for the finished raw transcript.

On the next app launch, reuse the existing foreground queue to resume an unfinished job from its recorded stage. Explicit Retry on a failed job continues that job and keeps its results. Duplicate startup/Retry requests converge on the same job. Jobs already Complete and existing Ready recordings are not replayed.

First scope: resume on app launch or explicit Retry. This does not promise that Android will restart the process immediately after an OEM kill or reboot. Force stop requires user interaction to leave the stopped state; checkpointing preserves work for that later opportunity. See the Android stopped-state documentation.

Keep one FIFO Whisper worker and the existing foreground notification. Reuse the scoped wake-lock approach for production inference, with release on every exit and a documented timeout/renewal policy suitable for long recordings. Restore progress from committed rows, for example 12/47, rather than resetting to zero. Show stage-specific failure and Retry even when an earlier transcript already exists. Keep microphone "resume recording" distinct from transcription Retry. The debug benchmark continues to read WAVs without publishing results into production jobs or transcript versions.

Handle service shutdown/timeout as interruption, preserving committed results. Android places time limits on background dataSync foreground services; a foreground notification does not make a job uninterruptible. A timeout handler must stop promptly and cannot wait indefinitely for native inference to finish. Invalidate the old attempt, cancel its orchestration scope, and reject late commits. Serialize native release after any in-flight call; never free the model context while JNI is executing. A timed-out bound service creates a fresh orchestration scope when started again; cancellation completion handlers release queue/title ownership even for coroutines that never started. JNI is not forcibly aborted mid-call: a surviving in-flight call can finish, but its invalidated attempt cannot commit. A replacement on that same service waits for serialized inference to return. Process death ends the call; the unfinished chunk is repeated. See foreground service timeouts.

Crash-loop guard: allow one automatic recovery at an unchanged chunk/stage boundary, then require explicit Retry if another process death occurs without a durable advance. Persist the count and reset it on a committed advance; duplicate requests within one live owner are not recovery attempts. Explicit Retry resets this guard without removing saved chunk results.

For diagnostics, persist monotonic durations for committed chunks and separately record known failed-attempt durations. Do not count overnight queue/suspension time as transcription CPU work or claim an exact total for a process that died before recording its final timing. Log job/chunk/stage identifiers and outcomes, not recognized speech.

SQLite transactions provide the all-or-nothing database boundary described in SQLite’s atomic commit documentation. Validate journaling/synchronous settings on the actual app driver before making power-loss durability claims. This protects committed progress; it cannot recover speech never flushed to storage or repair a physically failed storage device. Audio-file repair after interrupted microphone capture remains a separate, explicitly invoked operation, outside transcription recovery.

The during-capture extension adds migration 11.sqm (schema version 12): nullable recordingEntity.captureEndChunkIndex and transcriptionJobEntity.endChunkIndex. Version-11 jobs came from finalized manifests, so their end is backfilled from their last registered chunk plus one. Preserve their identities, results, stages, attempts, text, and history. New open jobs have no end until Stop. Existing Ready recordings receive only a null column; no transcript/audio/history is rewritten.

The previous generated SQLDelight schema was version 10 (migrations through 9.sqm). The additive 10.sqm migration produces version 11. Add tables/reference fields without deleting or rewriting existing audio, raw text, versions, or session membership. Use normal upgrade migrations; no uninstall, database reset, or destructive fallback.

The user confirmed during review that there are currently no unfinished runs. There is therefore no known ambiguous legacy run to repair for this device. The rules below remain defensive upgrade behaviour, not a required cleanup of the user’s current recordings.

Tests must interrupt before/after each durable boundary and reconstruct the coordinator/repository from disk. Assert which chunk indices inference actually receives, exact final text, unchanged original/edited prefixes, version counts and IDs, session membership, and final job stage. Cover initial and multiple appended ranges, empty successful text, injected native/storage failures, duplicate requests, stale worker attempts/edits, deleted targets, and incompatible inputs. Inject an SQL failure during publication/finalization to prove rollback of all effects. A killed process test must demonstrate committed chunks are skipped; a progress-count assertion alone is insufficient. Use deterministic inference substitutes for exact assembly assertions; device tests must establish saved results are reused rather than requiring a fresh native process to reproduce every previously generated character.

Run destructive interruption tests only on a disposable emulator/test install containing synthetic fixtures. Before an in-place device update, back up and verify audio/database data; afterwards compare saved files and existing recording/session/version contents. Do not interrupt or fault-inject the user’s important recordings. Performance/energy costs of hashing and database commits need a representative recording check, separate from correctness acceptance.