Recover from a damaged Japanese dictionary and stop stale word speech

A dictionary file that fails to load as a zip or with an I/O error is
now deleted, so the next attempt downloads it again instead of failing
the same way forever. A failed or interrupted download no longer
leaves its .part file behind, and the whole transfer is bounded by a
10 minute call timeout.

Moving the selection from a word that is being recorded or played to
a phrase now stops that word's speech, so it cannot start late.

Spec: docs/specs/2026-09-30-dictionary-recovery-and-speech-stop.md

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CKhgrZwwyTSRbNNCiRGy6s

Author: claude

app/src/main/java/com/kienhoang/dualsubreplay/data/JapaneseDictionaryStore.kt

@@ -65,28 +65,41 @@ internal class JapaneseDictionaryStore(
     internal fun installFrom(input: InputStream): Boolean {
         directory.mkdirs()
         val partial = File(directory, JapaneseDictionaryRelease.FILE_NAME + ".part")
-        val digest = MessageDigest.getInstance("SHA-256")
-        var total = 0L
-        partial.outputStream().use { output ->
-            val buffer = ByteArray(BUFFER_BYTES)
-            while (total <= expectedSize) {
-                val read = input.read(buffer)
-                if (read < 0) break
-                total += read
-                digest.update(buffer, 0, read)
-                output.write(buffer, 0, read)
+        var installed = false
+        try {
+            val digest = MessageDigest.getInstance("SHA-256")
+            var total = 0L
+            partial.outputStream().use { output ->
+                val buffer = ByteArray(BUFFER_BYTES)
+                while (total <= expectedSize) {
+                    val read = input.read(buffer)
+                    if (read < 0) break
+                    total += read
+                    digest.update(buffer, 0, read)
+                    output.write(buffer, 0, read)
+                }
             }
+            val sha256 = digest.digest().joinToString("") { "%02x".format(it) }
+            installed = total == expectedSize && sha256.equals(expectedSha256, ignoreCase = true) && partial.renameTo(file)
+            return installed
+        } finally {
+            // Also after a dropped connection or a failed write: no partial file stays behind.
+            if (!installed) partial.delete()
         }
-        val sha256 = digest.digest().joinToString("") { "%02x".format(it) }
-        if (total != expectedSize || !sha256.equals(expectedSha256, ignoreCase = true) || !partial.renameTo(file)) {
-            partial.delete()
-            return false
-        }
-        return true
     }
 
-    /** Builds Kuromoji's analyzer from the installed dictionary. Takes about a second and ~50 MB. */
-    fun loadTokenizer(): Tokenizer = ZipFile(file).use { zip -> ZipDictionaryBuilder(zip).build() }
+    /**
+     * Builds Kuromoji's analyzer from the installed dictionary. Takes about a second and ~50 MB.
+     * A file that cannot be read as the dictionary is deleted, so the next attempt downloads it
+     * again instead of failing the same way forever. Running out of memory keeps the file.
+     */
+    fun loadTokenizer(): Tokenizer =
+        try {
+            ZipFile(file).use { zip -> ZipDictionaryBuilder(zip).build() }
+        } catch (error: IOException) {
+            file.delete()
+            throw error
+        }
 
     /**
      * Kuromoji 0.9.0's IPADIC builder always reads the dictionary from its own classpath package.
@@ -122,6 +135,8 @@ internal class JapaneseDictionaryStore(
                 .Builder()
                 .connectTimeout(20, TimeUnit.SECONDS)
                 .readTimeout(60, TimeUnit.SECONDS)
+                // Bounds the whole 13 MB transfer, so a connection that trickles cannot hold the one download forever.
+                .callTimeout(10, TimeUnit.MINUTES)
                 .build()
         }
 

app/src/main/java/com/kienhoang/dualsubreplay/ui/PronunciationCache.kt

@@ -21,12 +21,18 @@ internal class PronunciationCache(
         language: String,
     ): File? = audio?.takeIf { ready && key == keyOf(text, language) && it.isFile && it.length() > 0 }
 
+    /** Whether the cached (or still recording) speech is for [text] in [language]. */
+    fun holds(
+        text: String,
+        language: String,
+    ): Boolean = key == keyOf(text, language)
+
     /** Deletes the cached speech unless it belongs to [text] in [language]. */
     fun keepOnly(
         text: String,
         language: String,
     ) {
-        if (key != keyOf(text, language)) clear()
+        if (!holds(text, language)) clear()
     }
 
     /**

app/src/main/java/com/kienhoang/dualsubreplay/ui/WordPronouncer.kt

@@ -50,11 +50,15 @@ internal class WordPronouncer(context: Context) {
         }
     }
 
-    /** Drops the recorded speech of the last word unless the learner is still on [word]. */
+    /**
+     * Drops the recorded speech of the last word unless the learner is still on [word], and stops
+     * that word's speech if it is still being recorded or played, so it cannot start late.
+     */
     fun forgetUnless(
         word: String,
         language: String,
     ) {
+        if (!cache.holds(word, language)) stop()
         cache.keepOnly(word, language)
     }
 

app/src/test/java/com/kienhoang/dualsubreplay/data/JapaneseDictionaryStoreTest.kt

@@ -79,6 +79,41 @@ class JapaneseDictionaryStoreTest {
         assertTrue(store(directory) { error("must not download again") }.install())
     }
 
+    @Test
+    fun aDroppedConnectionLeavesNoPartialFile() {
+        val directory = folder.newFolder("dictionary")
+        val dropping =
+            object : java.io.InputStream() {
+                private var sent = 0
+
+                override fun read(): Int = if (sent++ < 8) 1 else throw IOException("connection reset")
+            }
+
+        assertFalse(store(directory) { dropping }.install())
+        assertTrue(directory.listFiles().orEmpty().isEmpty())
+    }
+
+    @Test
+    fun aCorruptInstalledDictionaryIsDownloadedAgainAfterItFailsToLoad() {
+        val directory = folder.newFolder("dictionary")
+        // Same size as the real file, so the cheap size check still calls it installed.
+        File(directory, JapaneseDictionaryRelease.FILE_NAME).writeBytes(ByteArray(dictionaryJar.length().toInt()))
+        var downloads = 0
+        val store =
+            store(directory) {
+                downloads++
+                dictionaryJar.inputStream()
+            }
+        assertTrue(store.isInstalled())
+
+        assertTrue(runCatching { store.loadTokenizer() }.exceptionOrNull() is IOException)
+        assertFalse(store.isInstalled())
+
+        assertTrue(store.install())
+        assertEquals(1, downloads)
+        assertEquals(listOf("日本語"), japaneseLearnerWords(store.loadTokenizer(), "日本語").map { it.text })
+    }
+
     @Test
     fun releasePinMatchesTheMavenArtifactName() {
         assertTrue(

app/src/test/java/com/kienhoang/dualsubreplay/ui/PronunciationCacheTest.kt

@@ -55,6 +55,21 @@ class PronunciationCacheTest {
         assertNull(cache.lookup("春", "ja"))
     }
 
+    @Test
+    fun aWordBeingRecordedBelongsToItsSelectionUntilAnotherIsChosen() {
+        val cache = PronunciationCache(folder.newFolder("speech"))
+        assertFalse(cache.holds("春", "ja"))
+
+        // Recording has started but not finished: extending the selection to a phrase must stop it.
+        cache.prepare("春", "ja")
+        assertTrue(cache.holds(" 春 ", "ja"))
+        assertFalse(cache.holds("春ですね", "ja"))
+        assertFalse(cache.holds("春", "en"))
+
+        cache.keepOnly("春ですね", "ja")
+        assertFalse(cache.holds("春", "ja"))
+    }
+
     @Test
     fun anUnfinishedRecordingIsNeverReplayed() {
         val cache = PronunciationCache(folder.newFolder("speech"))

docs/specs/2026-09-30-dictionary-recovery-and-speech-stop.md

@@ -0,0 +1,109 @@
+# Dictionary recovers from a bad file; a phrase selection stops the word's speech
+
+## Status
+
+Implemented. Approved for implementation by the owner on 2026-09-30 ("do what you recommend",
+after the review of the external Sol 6.1 audit, items 4 and 5 in their smaller recommended
+form). Local checks pass; see the PR for the final-head CI.
+
+## Context / problem
+
+Three small problems, reproduced on 2026-09-30 by compiling the unchanged
+`JapaneseDictionaryStore.kt` with a harness, or confirmed by reading the code:
+
+1. **A same-size corrupt dictionary never recovers.** `isInstalled()` checks only the file's size.
+   If the stored jar is damaged after a verified install (storage corruption), every load fails with
+   `ZipException`, the file stays, and every retry fails the same way. Japanese keeps the heuristic
+   tokenizer for good.
+2. **An interrupted download leaves a `.part` file.** `installFrom` deleted the partial file only on
+   its normal path, so a dropped connection left up to 13 MB behind until the next attempt
+   overwrote it.
+3. **The download had no overall deadline.** Connect (20 s) and read (60 s) timeouts do not bound a
+   connection that keeps trickling bytes, and only one download runs at a time.
+4. **A word's speech could start after the selection became a phrase.** With "Pronounce tapped
+   words" on, tapping a word starts recording and playing it. Extending the selection to a phrase
+   called `WordPronouncer.forgetUnless`, which cleared the cache but left the speech job running,
+   so the word could still play a moment later.
+
+## Goals
+
+- A dictionary that fails to load as a zip or with an I/O error is deleted, so the next retry
+  downloads it again. Running out of memory keeps the file.
+- No partial file remains after any failed download.
+- The whole transfer is bounded (OkHttp call timeout, 10 minutes for 13 MB).
+- Moving the selection away from the word being pronounced stops that word's speech.
+
+## Non-goals
+
+- No hashing on every start, no new status model or retry UI, no Wi-Fi-only rule (the owner chose
+  first-use download on any network).
+- No change to phrases never auto-speaking, the explicit Pronounce action, reuse of the last word's
+  recording, or the tap-inside-selection-to-clear behavior.
+- `MediaPlayer.prepare()` on the small local recording stays synchronous.
+
+## User-visible behavior
+
+- **Before:** a damaged dictionary file left Japanese on heuristic word splitting permanently; a
+  tapped word could still speak after extending the selection to a phrase.
+- **After:** the dictionary downloads again on the next retry (about a minute later, or the next
+  launch); extending a selection silences the word right away.
+
+## Technical constraints / invariants
+
+- Keep the pinned size and SHA-256 check and the atomic rename; an intact file is never replaced by
+  a failed download (downloads only start when the file is missing or was just deleted).
+- Plain JUnit4 tests through the existing injectable `open` function.
+
+## Proposed approach / plan
+
+1. `installFrom`: `try/finally` deletes `.part` unless the rename succeeded.
+2. `loadTokenizer`: on `IOException` (including `ZipException`), delete the file and rethrow.
+3. OkHttp client: `callTimeout(10, MINUTES)`.
+4. `PronunciationCache.holds`; `WordPronouncer.forgetUnless` calls `stop()` when the cache is not for
+   the new selection.
+
+## Acceptance criteria
+
+- [x] A dropped connection returns false and leaves the dictionary folder empty.
+- [x] A same-size corrupt file fails to load, is no longer installed, and the next `install()`
+  downloads once and loads.
+- [x] Existing dictionary tests (verified install, mirror fallback, damaged/oversized rejects, no
+  second download) pass.
+- [x] The cache reports which word it holds while recording, so a phrase selection stops it.
+- [ ] Owner's phone: tap a Japanese word, then drag to a phrase before it speaks; the word stays
+  silent (not run).
+
+## Validation plan
+
+| Category | Command/scenario and expected result | Environment / applicability |
+| --- | --- | --- |
+| Unit tests | `./gradlew testDebugUnitTest`, including new `JapaneseDictionaryStoreTest` and `PronunciationCacheTest` cases | Local Linux, CI |
+| Android lint/build | `formatCheck complexityCheck lintDebug assembleDebug assembleDebugAndroidTest` | Local Linux, CI |
+| Managed-device/emulator | Existing suite | CI |
+| Physical-device/manual | Word → phrase during speech; real first-use download | Owner's phone (not run) |
+
+## Risks / edge cases
+
+- An `IOException` while reading a healthy file (for example the storage being unmounted) now also
+  deletes it, costing one extra 13 MB download. That is rare and self-healing.
+- Moving the selection to another word or phrase also clears a speech message left from the previous
+  selection (for example "No voice is available"), since it no longer describes what is selected.
+
+## Release intent
+
+`release:patch` (repository default for a bug fix). The version number depends on merge order with
+the other audit PRs and is an estimate until reserved.
+
+## Implementation result
+
+As planned.
+
+## Validation result
+
+- `./gradlew formatCheck complexityCheck testDebugUnitTest lintDebug assembleDebug assembleDebugAndroidTest`:
+  passed locally (Linux, JDK 21, Android SDK 36).
+- With `JapaneseDictionaryStore.kt` reverted, `aDroppedConnectionLeavesNoPartialFile` and
+  `aCorruptInstalledDictionaryIsDownloadedAgainAfterItFailsToLoad` fail; with the fix both pass.
+- The speech stop itself runs on Android's text-to-speech and `MediaPlayer`, so it is covered only
+  through `PronunciationCache.holds`; the phone check above is not run.
+- Final-head CI: see the PR.