refactor(anki): parse the known-word cache in one shared module

The cache manager and the stats server each carried a hand-written parser
for the same file. When the format went to v4 for maturity tiers only the
manager was updated, so loadKnownWordsSet fell through to null and every
session reported 0 known words from an intact cache.

Move the state union, its parser, and a knownWordsFromState accessor into
known-word-cache-format and have both readers go through it. The stats
server no longer mentions a version at all, and both version switches close
with assertNever, so adding a V5 is a compile error at every consumer
instead of a silently empty result. An unparseable cache now warns rather
than reading as "no known words".

Two stats fixtures omitted refreshedAtMs/scope and only passed because the
stats reader was laxer than the manager; they now carry the fields every
cache the app writes has always had.

changes/anki-maturity-known-word-highlighting.md

@@ -2,3 +2,4 @@ type: added
 area: overlay
 
 - Known-word subtitle highlights can now be colored by Anki card maturity (new, learning, young, mature) like asbplayer. Enable with `ankiConnect.knownWords.maturityEnabled`; the mature interval threshold (`matureThresholdDays`, default 21) and the four tier colors (`subtitleStyle.knownWordMaturityColors`) are configurable, and a runtime option toggles it in-session. The session help color legend shows the four tier colors while maturity highlighting is on.
+- Tiers follow Anki's own card counts: the interval tiers exclude cards in the learning/relearning queue, so a lapsed card shows the learning color instead of young (its interval is reset to at least 1 day, which previously made the learning tier unreachable). A note with a mature card alongside a relearning card still shows mature.

changes/fix-stats-known-word-cache-format.md

@@ -0,0 +1,5 @@
+type: fixed
+area: stats
+
+- Stats reported 0 known words for every session after the known-word cache gained maturity tiers. The stats server carried its own copy of the cache parser that only recognized versions up to 3, so the new v4 file was read as "no cache" rather than as a format it should understand.
+- The cache format, its parser, and the derived known-word set now live in one module that both the cache manager and the stats server read, and the version dispatch ends in an exhaustive check so a future format bump fails the build instead of silently reporting zero. A cache that exists but does not parse now logs a warning rather than passing for an empty one.

changes/history-post-playback-menu.md

@@ -2,3 +2,4 @@ type: added
 area: launcher
 
 - After a watch-history episode ends or mpv closes, the fzf or rofi launcher returns to that series with options to play the previous episode, rewatch, play the next episode, select another episode, or quit SubMiner. Previous and Next continue across season directories.
+- The action menu shown right after picking a series from `subminer -H` now also offers the previous episode, matching the menu shown after playback.

changes/rofi-prompt-spacing.md

@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Rofi menu prompts now keep a space between the prompt text and the input field instead of running into the search placeholder.

changes/verify-known-word-highlights-script.md

@@ -0,0 +1,7 @@
+type: internal
+area: tokenizer
+
+- Added `verify-known-word-highlights:electron` script: tokenizes a real subtitle file through the app's Yomitan/MeCab pipeline with the live known-word cache, prints each line in the configured tier colors, and summarizes the tier counts so highlighting can be checked outside of playback.
+- Added `--audit`, which re-derives every highlighted tier from live Anki card data (`notesInfo` + `cardsInfo` intervals) and reports each token whose rendered tier disagrees, catching both stale cache entries and tier-classification bugs.
+- Added `--profile-copy` so the check can run while SubMiner is open (Electron locks the Yomitan userData dir), plus `--refresh`, `--limit`, `--json`, and `--quiet`.
+- Added `KnownWordCacheManager.getKnownWordMatchNoteIds`, exposing the note ids behind a known-word match so an audit can trace a rendered tier back to the exact Anki notes.

docs-site/launcher-script.md

@@ -73,6 +73,7 @@ subminer -R -H                         # rofi history browser
 
 The first menu lists every locally watched series, most recently watched first, using the parsed media title (e.g. the anime title) when available and the directory name otherwise. Selecting a series opens an action menu:
 
+- **Previous episode**: plays the episode before the last watched one and continues into the previous season directory when the season starts
 - **Replay last watched**: replays the most recently watched episode
 - **Next episode**: plays the episode after the last watched one and continues into the next season directory when the season ends
 - **Browse episodes**: lists the video files in the series directory in episode order, using the same fzf/rofi episode picker as directory browsing; if the series has multiple season directories, a season menu appears first

docs-site/subtitle-annotations.md

@@ -49,26 +49,38 @@ Instead of one color for every known word, maturity highlighting tints each know
 
 **How it works:**
 
-1. During the known-word cache refresh, SubMiner classifies each note with Anki search filters (`prop:ivl`, `is:learn`, `is:new`) - no extra card data is downloaded.
-2. Each note gets the tier of its **most mature** card: `mature` (interval ≥ threshold), `young` (in review below the threshold), `learning` (in (re)learning), or `new` (never reviewed).
+1. During the known-word cache refresh, SubMiner classifies each note with Anki search filters (`prop:ivl`, `is:learn`) - no extra card data is downloaded.
+2. Each note gets the tier of its **most mature** card: `mature` (in review, interval ≥ threshold), `young` (in review, interval below the threshold), `learning` (in the learning or relearning queue), or `new` (never studied). The buckets are disjoint, matching Anki's own card counts: a lapsed card in relearning counts as `learning`, not `young`, even though its interval is ≥ 1 day. A note with a mature card plus a relearning card still shows `mature`.
 3. A word matched by several notes takes the most mature tier among them, with the same reading-aware matching as regular known-word highlighting.
 4. Known tokens render in the tier color instead of `subtitleStyle.knownWordColor`; if tier data is missing for a match, the token falls back to the single known-word color.
 
 **Key settings:**
 
 | Option                                           | Default   | Description                                                           |
-| -------------------------------------------- | --------- | ---------------------------------------------------------- |
+| ------------------------------------------------ | --------- | --------------------------------------------------------------------- |
 | `ankiConnect.knownWords.maturityEnabled`         | `false`   | Color known words by card maturity (requires known-word highlighting) |
 | `ankiConnect.knownWords.matureThresholdDays`     | `21`      | Card interval in days at which a word counts as mature                |
 | `subtitleStyle.knownWordMaturityColors.new`      | `#ee99a0` | Tier color for never-reviewed cards                                   |
-| `subtitleStyle.knownWordMaturityColors.learning` | `#b7bdf8` | Tier color for (re)learning cards                      |
+| `subtitleStyle.knownWordMaturityColors.learning` | `#b7bdf8` | Tier color for cards in the learning/relearning queue                 |
 | `subtitleStyle.knownWordMaturityColors.young`    | `#91d7e3` | Tier color for young review cards                                     |
 | `subtitleStyle.knownWordMaturityColors.mature`   | `#a6da95` | Tier color for mature cards                                           |
 
-Changing `maturityEnabled` or the threshold triggers a full known-word cache refresh so tiers are refetched.
+Changing `maturityEnabled` or the threshold triggers a full known-word cache refresh so tiers are refetched, as does upgrading to a build that revises the tier rules.
+
+How often the `learning` color appears depends on your deck preset: with no relearning steps configured, a lapsed card returns straight to review and shows `young` instead.
 
 While maturity highlighting is on, the session help color legend replaces its single "Known words" swatch with one row per tier (new, learning, young, mature).
 
+**Checking the colors you actually see:**
+
+Tiers are only as fresh as the last known-word cache refresh (`ankiConnect.knownWords.refreshMinutes`), so a card that crosses the mature threshold mid-day keeps its old color until the next refresh. To check a whole episode offline, run the verifier against its subtitle file:
+
+```sh
+bun run verify-known-word-highlights:electron -- --input /path/to/episode.ja.srt --audit
+```
+
+It tokenizes every cue through the real Yomitan/MeCab pipeline with your live known-word cache, prints each line in your configured tier colors, and summarizes the tier counts. `--audit` re-derives each highlighted tier from live Anki card data (`notesInfo` + `cardsInfo` intervals) and lists any token whose color disagrees, with the note ids and intervals behind it. Electron locks the Yomitan profile, so quit SubMiner first or pass `--profile-copy` to run against a scratch copy. Other useful flags: `--refresh` (refresh the cache first), `--limit <n>`, `--quiet`, `--json`.
+
 ## Character-Name Highlighting
 
 Character-name matches are built from the active merged SubMiner character dictionary, which auto-syncs character data from AniList for your recently-watched titles. When the current AniList media ID is known, SubMiner ignores loaded entries from other titles for subtitle name matching and inline portraits. Matching names are highlighted in subtitles and become available for hover-driven Yomitan character profiles - portraits, roles, voice actors, and biographical detail.

launcher/commands/history-command.ts

@@ -7,6 +7,7 @@ import {
   collectVideos,
   findRofiTheme,
   formatPickerLaunchError,
+  formatRofiPrompt,
   showFzfMenu,
   showRofiMenu,
 } from '../picker.js';
@@ -67,6 +68,34 @@ export function buildHistorySessionActions(
   return actions;
 }
 
+export function buildHistoryEntryActions(
+  lastWatchedPath: string | null,
+  previousEpisodePath: string | null,
+  nextEpisodePath: string | null,
+): HistorySessionMenuAction[] {
+  const actions: HistorySessionMenuAction[] = [];
+  if (previousEpisodePath) {
+    actions.push({
+      kind: 'previous',
+      label: `Previous episode: ${path.basename(previousEpisodePath)}`,
+    });
+  }
+  if (lastWatchedPath) {
+    actions.push({
+      kind: 'replay',
+      label: `Replay last watched: ${path.basename(lastWatchedPath)}`,
+    });
+  }
+  if (nextEpisodePath) {
+    actions.push({ kind: 'next', label: `Next episode: ${path.basename(nextEpisodePath)}` });
+  }
+  actions.push(
+    { kind: 'browse', label: 'Browse episodes' },
+    { kind: 'quit', label: 'Quit SubMiner' },
+  );
+  return actions;
+}
+
 interface HistoryPlaybackLoopDeps {
   play: (videoPath: string) => Promise<void>;
   pickPostPlaybackAction: (input: {
@@ -171,7 +200,16 @@ function showRofiIndexMenu(
   themePath: string | null,
   icons: Array<string | null> = [],
 ): number {
-  const rofiArgs = ['-dmenu', '-i', '-matching', 'fuzzy', '-format', 'i', '-p', prompt];
+  const rofiArgs = [
+    '-dmenu',
+    '-i',
+    '-matching',
+    'fuzzy',
+    '-format',
+    'i',
+    '-p',
+    formatRofiPrompt(prompt),
+  ];
   const hasIcons = icons.some(Boolean);
   if (hasIcons) rofiArgs.push('-show-icons');
   if (themePath) {
@@ -332,17 +370,14 @@ export async function runHistoryCommand(
 
   const lastPath = path.resolve(entry.lastWatched.sourcePath);
   const lastExists = fs.existsSync(lastPath);
+  const previousEpisode = findPreviousEpisode(lastPath);
   const nextEpisode = findNextEpisode(lastPath);
 
-  const actions: HistorySessionMenuAction[] = [];
-  if (lastExists) {
-    actions.push({ kind: 'replay', label: `Replay last watched: ${path.basename(lastPath)}` });
-  }
-  if (nextEpisode) {
-    actions.push({ kind: 'next', label: `Next episode: ${path.basename(nextEpisode)}` });
-  }
-  actions.push({ kind: 'browse', label: 'Browse episodes' });
-  actions.push({ kind: 'quit', label: 'Quit SubMiner' });
+  const actions = buildHistoryEntryActions(
+    lastExists ? lastPath : null,
+    previousEpisode,
+    nextEpisode,
+  );
 
   const entryIcon = seriesIcons[seriesIdx] ?? null;
   const actionIdx = pickIndex(
@@ -357,13 +392,14 @@ export async function runHistoryCommand(
   switch (actions[actionIdx]!.kind) {
     case 'replay':
       return { entry, videoPath: lastPath, themePath, entryIcon };
+    case 'previous':
+      return previousEpisode ? { entry, videoPath: previousEpisode, themePath, entryIcon } : null;
     case 'next':
       return nextEpisode ? { entry, videoPath: nextEpisode, themePath, entryIcon } : null;
     case 'browse': {
       const videoPath = browseEpisodes(entry, context, themePath);
       return videoPath ? { entry, videoPath, themePath, entryIcon } : null;
     }
-    case 'previous':
     case 'quit':
       return null;
   }

launcher/commands/history-session.test.ts

@@ -1,7 +1,11 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import path from 'node:path';
-import { buildHistorySessionActions, runHistoryPlaybackLoop } from './history-command.js';
+import {
+  buildHistoryEntryActions,
+  buildHistorySessionActions,
+  runHistoryPlaybackLoop,
+} from './history-command.js';
 import type { HistorySeriesEntry } from '../history.js';
 
 type HistoryLoop = (
@@ -186,6 +190,37 @@ test('history show menu omits previous and next when the just-played episode has
   ]);
 });
 
+test('history entry menu offers previous, replay, and next before playback starts', () => {
+  assert.equal(
+    typeof buildHistoryEntryActions,
+    'function',
+    'history entry actions not implemented',
+  );
+
+  assert.deepEqual(
+    buildHistoryEntryActions(
+      '/shows/test-show/episode-03.mkv',
+      '/shows/test-show/episode-02.mkv',
+      '/shows/test-show/episode-04.mkv',
+    ),
+    [
+      { kind: 'previous', label: 'Previous episode: episode-02.mkv' },
+      { kind: 'replay', label: 'Replay last watched: episode-03.mkv' },
+      { kind: 'next', label: 'Next episode: episode-04.mkv' },
+      { kind: 'browse', label: 'Browse episodes' },
+      { kind: 'quit', label: 'Quit SubMiner' },
+    ],
+  );
+});
+
+test('history entry menu omits replay when the last watched file is gone', () => {
+  assert.deepEqual(buildHistoryEntryActions(null, null, '/shows/test-show/episode-04.mkv'), [
+    { kind: 'next', label: 'Next episode: episode-04.mkv' },
+    { kind: 'browse', label: 'Browse episodes' },
+    { kind: 'quit', label: 'Quit SubMiner' },
+  ]);
+});
+
 test('history playback loop selects previous based on the just-played path, then re-derives previous from the new current episode', async () => {
   assert.equal(
     typeof runHistoryPlaybackLoop,

launcher/picker.test.ts

@@ -3,7 +3,22 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findRofiTheme } from './picker';
+import { findRofiTheme, formatRofiPrompt } from './picker';
+
+// ── formatRofiPrompt: spacing between prompt and input field ──────────────────
+
+test('formatRofiPrompt appends a single trailing space', () => {
+  assert.equal(formatRofiPrompt('Select Video'), 'Select Video ');
+});
+
+test('formatRofiPrompt collapses existing trailing whitespace to one space', () => {
+  assert.equal(formatRofiPrompt('Watch History   '), 'Watch History ');
+});
+
+test('formatRofiPrompt leaves an empty prompt empty', () => {
+  assert.equal(formatRofiPrompt(''), '');
+  assert.equal(formatRofiPrompt('   '), '');
+});
 
 // ── findRofiTheme: Linux packaged path discovery ──────────────────────────────
 

launcher/picker.ts

@@ -17,13 +17,22 @@ export function escapeShellSingle(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * Rofi renders the prompt flush against the input field, so keep exactly one
+ * trailing space to separate them.
+ */
+export function formatRofiPrompt(prompt: string): string {
+  const trimmed = prompt.trimEnd();
+  return trimmed ? `${trimmed} ` : '';
+}
+
 export function showRofiFlatMenu(
   items: string[],
   prompt: string,
   initialQuery = '',
   themePath: string | null = null,
 ): string {
-  const args = ['-dmenu', '-i', '-matching', 'fuzzy', '-p', prompt];
+  const args = ['-dmenu', '-i', '-matching', 'fuzzy', '-p', formatRofiPrompt(prompt)];
   if (themePath) {
     args.push('-theme', themePath);
   } else {
@@ -110,7 +119,7 @@ export async function promptOptionalJellyfinSearch(
   themePath: string | null = null,
 ): Promise<string> {
   if (useRofi && commandExists('rofi')) {
-    const rofiArgs = ['-dmenu', '-i', '-p', 'Jellyfin Search (optional)'];
+    const rofiArgs = ['-dmenu', '-i', '-p', formatRofiPrompt('Jellyfin Search (optional)')];
     if (themePath) {
       rofiArgs.push('-theme', themePath);
     } else {
@@ -157,7 +166,7 @@ function showRofiIconMenu(
   themePath: string | null = null,
 ): number {
   if (entries.length === 0) return -1;
-  const rofiArgs = ['-dmenu', '-i', '-show-icons', '-format', 'i', '-p', prompt];
+  const rofiArgs = ['-dmenu', '-i', '-show-icons', '-format', 'i', '-p', formatRofiPrompt(prompt)];
   if (initialQuery) rofiArgs.push('-filter', initialQuery);
   if (themePath) {
     rofiArgs.push('-theme', themePath);
@@ -391,7 +400,7 @@ export function showRofiMenu(
     '-dmenu',
     '-i',
     '-p',
-    'Select Video ',
+    formatRofiPrompt('Select Video'),
     '-show-icons',
     '-theme-str',
     'configuration { font: "Noto Sans CJK JP Regular 8";}',

package.json

@@ -13,6 +13,7 @@
     "get-frequency:electron": "bun run build:yomitan && bun build scripts/get_frequency.ts --format=cjs --target=node --outfile dist/scripts/get_frequency.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/get_frequency.js --pretty --color-top-x 10000 --yomitan-user-data ~/.config/SubMiner --colorized-line",
     "test-yomitan-parser": "bun run scripts/test-yomitan-parser.ts",
     "test-yomitan-parser:electron": "bun run build:yomitan && bun build scripts/test-yomitan-parser.ts --format=cjs --target=node --outfile dist/scripts/test-yomitan-parser.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/test-yomitan-parser.js",
+    "verify-known-word-highlights:electron": "bun run build:yomitan && bun build scripts/verify-known-word-highlights.ts --format=cjs --target=node --outfile dist/scripts/verify-known-word-highlights.js --packages=external && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/verify-known-word-highlights.js",
     "record-tokenizer-fixture:electron": "bun run build:yomitan && bun build scripts/record-tokenizer-fixture.ts --format=cjs --target=node --outfile dist/scripts/record-tokenizer-fixture.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/record-tokenizer-fixture.js",
     "compare-yomitan-api:electron": "bun run build:yomitan && bun build scripts/compare-yomitan-api.ts --format=cjs --target=node --outfile dist/scripts/compare-yomitan-api.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/compare-yomitan-api.js",
     "build:yomitan": "bun scripts/build-yomitan.mjs",

scripts/verify-known-word-highlights.ts

@@ -0,0 +1,587 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+import {
+  KnownWordCacheManager,
+  getKnownWordCacheLifecycleConfig,
+} from '../src/anki-integration/known-word-cache.js';
+import { getMatureIntervalThresholdDays } from '../src/anki-integration/known-word-maturity.js';
+import { resolveConfigDir } from '../src/config/path-resolution.js';
+import { ConfigService } from '../src/config/service.js';
+import { parseSubtitleCues } from '../src/core/services/subtitle-cue-parser.js';
+import { createTokenizerDepsRuntime, tokenizeSubtitle } from '../src/core/services/tokenizer.js';
+import {
+  resolveCompleteTokenReading,
+  resolveKnownWordReadingForMatch,
+  resolveKnownWordText,
+} from '../src/core/services/tokenizer/annotation-stage.js';
+import { MecabTokenizer } from '../src/mecab-tokenizer.js';
+import type { MergedToken } from '../src/types.js';
+import type { KnownWordMaturityTier } from '../src/types/subtitle.js';
+import {
+  createYomitanRuntimeStateWithSearch,
+  destroyParserWindow,
+  loadElectronModule,
+  withTimeout,
+  type YomitanRuntimeState,
+} from './yomitan-script-runtime.js';
+
+interface CliOptions {
+  input: string;
+  configDir?: string;
+  yomitanUserDataPath?: string;
+  yomitanExtensionPath?: string;
+  limit: number;
+  audit: boolean;
+  refresh: boolean;
+  json: boolean;
+  quiet: boolean;
+  profileCopy: boolean;
+}
+
+type TierOrFallback = KnownWordMaturityTier | 'known-no-tier';
+
+interface TokenReport {
+  cueIndex: number;
+  startTime: number;
+  surface: string;
+  headword: string;
+  reading: string;
+  tier: TierOrFallback;
+  noteIds: number[];
+}
+
+interface AuditMismatch extends TokenReport {
+  liveTier: KnownWordMaturityTier | 'no-notes';
+  intervals: number[];
+}
+
+const TIERS: readonly KnownWordMaturityTier[] = ['new', 'learning', 'young', 'mature'];
+const FALLBACK_TIER_COLORS: Record<KnownWordMaturityTier, string> = {
+  new: '#ee99a0',
+  learning: '#b7bdf8',
+  young: '#91d7e3',
+  mature: '#a6da95',
+};
+
+function parseCliArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    input: '',
+    limit: 0,
+    audit: false,
+    refresh: false,
+    json: false,
+    quiet: false,
+    profileCopy: false,
+  };
+  const rest: string[] = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    const takeValue = (flag: string): string => {
+      const next = argv[i + 1];
+      if (!next) {
+        throw new Error(`Missing value for ${flag}`);
+      }
+      i += 1;
+      return next;
+    };
+
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(`${usage()}\n`);
+      process.exit(0);
+    } else if (arg === '--input') {
+      options.input = takeValue(arg);
+    } else if (arg === '--config-dir') {
+      options.configDir = takeValue(arg);
+    } else if (arg === '--yomitan-user-data') {
+      options.yomitanUserDataPath = takeValue(arg);
+    } else if (arg === '--yomitan-extension-path') {
+      options.yomitanExtensionPath = takeValue(arg);
+    } else if (arg === '--limit') {
+      options.limit = Math.max(0, Number.parseInt(takeValue(arg), 10) || 0);
+    } else if (arg === '--audit') {
+      options.audit = true;
+    } else if (arg === '--refresh') {
+      options.refresh = true;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--quiet') {
+      options.quiet = true;
+    } else if (arg === '--profile-copy') {
+      options.profileCopy = true;
+    } else if (arg === '--') {
+      // `bun run <script> -- --flag ...` forwards the separator too.
+      continue;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown flag: ${arg}`);
+    } else {
+      rest.push(arg);
+    }
+  }
+
+  if (!options.input && rest.length > 0) {
+    options.input = rest.join(' ');
+  }
+  if (!options.input) {
+    throw new Error(`No subtitle file given.\n${usage()}`);
+  }
+  return options;
+}
+
+function usage(): string {
+  return [
+    'Usage: verify-known-word-highlights <subtitle.srt|.ass> [flags]',
+    '',
+    '  --limit <n>                 Only check the first n cues (default: all)',
+    '  --audit                     Re-derive every highlighted tier from live Anki card data',
+    '  --refresh                   Force a known-word cache refresh before checking',
+    '  --json                      Emit a machine-readable report',
+    '  --quiet                     Skip the per-line colored dump',
+    '  --profile-copy              Copy the Yomitan profile to a scratch dir so this can run',
+    '                              while SubMiner is open (Electron locks the userData dir)',
+    '  --config-dir <dir>          SubMiner config dir (default: auto-detected)',
+    '  --yomitan-user-data <dir>   Electron userData dir holding the Yomitan profile',
+    '  --yomitan-extension-path <dir>',
+  ].join('\n');
+}
+
+const ANSI_RESET = '\u001b[0m';
+
+function colorize(text: string, hex: string): string {
+  const normalized = hex.trim().replace(/^#/, '');
+  const expanded =
+    normalized.length === 3
+      ? normalized
+          .split('')
+          .map((char) => `${char}${char}`)
+          .join('')
+      : normalized;
+  if (!/^[0-9a-fA-F]{6}$/.test(expanded)) {
+    return text;
+  }
+  const r = Number.parseInt(expanded.slice(0, 2), 16);
+  const g = Number.parseInt(expanded.slice(2, 4), 16);
+  const b = Number.parseInt(expanded.slice(4, 6), 16);
+  return `\u001b[38;2;${r};${g};${b}m${text}${ANSI_RESET}`;
+}
+
+function formatTimestamp(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds));
+  const mm = String(Math.floor(total / 60)).padStart(2, '0');
+  const ss = String(total % 60).padStart(2, '0');
+  return `${mm}:${ss}`;
+}
+
+// The user's real config dir is copied into a scratch dir so this read-only
+// check can never rewrite config.jsonc (ConfigService migrates on load) or the
+// live known-word cache (a --refresh persists tier data).
+function createScratchState(configDir: string): { dir: string; cachePath: string } {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-highlight-verify-'));
+  for (const fileName of ['config.jsonc', 'config.json']) {
+    const source = path.join(configDir, fileName);
+    if (fs.existsSync(source)) {
+      fs.copyFileSync(source, path.join(dir, fileName));
+    }
+  }
+  const cachePath = path.join(dir, 'known-words-cache.json');
+  const liveCachePath = path.join(configDir, 'known-words-cache.json');
+  if (fs.existsSync(liveCachePath)) {
+    fs.copyFileSync(liveCachePath, cachePath);
+  }
+  return { dir, cachePath };
+}
+
+// Electron locks a userData dir, so the Yomitan profile can't be shared with a
+// running SubMiner. Copying the dictionary-bearing parts of the profile lets
+// this check run mid-session (IndexedDB alone is often over 1 GB).
+const YOMITAN_PROFILE_DIRS = [
+  'extensions',
+  'IndexedDB',
+  'Local Extension Settings',
+  'Local Storage',
+];
+
+function copyYomitanProfile(sourceUserDataPath: string): string {
+  const target = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-highlight-profile-'));
+  for (const name of YOMITAN_PROFILE_DIRS) {
+    const source = path.join(sourceUserDataPath, name);
+    if (fs.existsSync(source)) {
+      fs.cpSync(source, path.join(target, name), { recursive: true });
+    }
+  }
+  return target;
+}
+
+function readPersistedCacheScope(cachePath: string): string | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf-8')) as { scope?: unknown };
+    return typeof parsed.scope === 'string' ? parsed.scope : null;
+  } catch {
+    return null;
+  }
+}
+
+function createAnkiClient(url: string) {
+  const request = async (action: string, params: unknown): Promise<unknown> => {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action, version: 6, params }),
+    });
+    const payload = (await response.json()) as { result: unknown; error: string | null };
+    if (payload.error) {
+      throw new Error(`AnkiConnect ${action}: ${payload.error}`);
+    }
+    return payload.result;
+  };
+
+  return {
+    request,
+    findNotes: (query: string) => request('findNotes', { query }),
+    notesInfo: (noteIds: number[]) => request('notesInfo', { notes: noteIds }),
+  };
+}
+
+function resolveTokenMatch(
+  token: MergedToken,
+  cache: KnownWordCacheManager,
+  matchMode: 'surface' | 'headword',
+): { tier: KnownWordMaturityTier | null; noteIds: Set<number> } {
+  const matchText = resolveKnownWordText(token.surface, token.headword, matchMode);
+  const matchReading = resolveKnownWordReadingForMatch(token, matchMode);
+  const primaryTier = matchText ? cache.getKnownWordTier(matchText, matchReading) : null;
+  if (primaryTier) {
+    return { tier: primaryTier, noteIds: cache.getKnownWordMatchNoteIds(matchText, matchReading) };
+  }
+
+  const fallbackReading = resolveCompleteTokenReading(token);
+  if (!fallbackReading || fallbackReading === matchText.trim()) {
+    return {
+      tier: null,
+      noteIds: matchText ? cache.getKnownWordMatchNoteIds(matchText, matchReading) : new Set(),
+    };
+  }
+  const fallbackOptions = { allowReadingOnlyMatch: false } as const;
+  return {
+    tier: cache.getKnownWordTier(fallbackReading, undefined, fallbackOptions),
+    noteIds: cache.getKnownWordMatchNoteIds(fallbackReading, undefined, fallbackOptions),
+  };
+}
+
+// Ground truth straight from card data, independent of the Anki search filters
+// the cache refresh uses (prop:ivl / is:learn).
+function classifyCardsIntoTier(
+  cards: Array<{ interval: number; queue: number; type: number }>,
+  thresholdDays: number,
+): KnownWordMaturityTier {
+  if (cards.some((card) => card.interval >= thresholdDays)) return 'mature';
+  if (cards.some((card) => card.interval >= 1)) return 'young';
+  if (
+    cards.some((card) => card.type === 1 || card.type === 3 || card.queue === 1 || card.queue === 4)
+  )
+    return 'learning';
+  return 'new';
+}
+
+async function auditTokens(
+  reports: TokenReport[],
+  client: ReturnType<typeof createAnkiClient>,
+  thresholdDays: number,
+): Promise<{ mismatches: AuditMismatch[]; auditedNotes: number }> {
+  const noteIds = [...new Set(reports.flatMap((report) => report.noteIds))];
+  const cardIdsByNote = new Map<number, number[]>();
+  for (let i = 0; i < noteIds.length; i += 500) {
+    const infos = (await client.notesInfo(noteIds.slice(i, i + 500))) as Array<{
+      noteId: number;
+      cards?: number[];
+    }>;
+    for (const info of infos) {
+      cardIdsByNote.set(info.noteId, info.cards ?? []);
+    }
+  }
+
+  const allCardIds = [...cardIdsByNote.values()].flat();
+  const cardById = new Map<number, { interval: number; queue: number; type: number }>();
+  for (let i = 0; i < allCardIds.length; i += 500) {
+    const infos = (await client.request('cardsInfo', {
+      cards: allCardIds.slice(i, i + 500),
+    })) as Array<{ cardId: number; interval: number; queue: number; type: number }>;
+    for (const info of infos) {
+      cardById.set(info.cardId, {
+        interval: info.interval,
+        queue: info.queue,
+        type: info.type,
+      });
+    }
+  }
+
+  const mismatches: AuditMismatch[] = [];
+  for (const report of reports) {
+    const cards = report.noteIds
+      .flatMap((noteId) => cardIdsByNote.get(noteId) ?? [])
+      .map((cardId) => cardById.get(cardId))
+      .filter((card): card is { interval: number; queue: number; type: number } => Boolean(card));
+    const liveTier = cards.length === 0 ? 'no-notes' : classifyCardsIntoTier(cards, thresholdDays);
+    if (liveTier !== report.tier) {
+      mismatches.push({
+        ...report,
+        liveTier,
+        intervals: cards.map((card) => card.interval),
+      });
+    }
+  }
+  return { mismatches, auditedNotes: noteIds.length };
+}
+
+async function main(): Promise<void> {
+  const args = parseCliArgs(process.argv.slice(2));
+  let electronModule: typeof import('electron') | null = null;
+  let yomitanState: YomitanRuntimeState | null = null;
+  let scratchDir: string | null = null;
+  let profileCopyDir: string | null = null;
+
+  try {
+    const configDir =
+      args.configDir ??
+      resolveConfigDir({
+        homeDir: os.homedir(),
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
+        existsSync: fs.existsSync,
+      });
+    const scratch = createScratchState(configDir);
+    scratchDir = scratch.dir;
+    const config = new ConfigService(scratch.dir).getConfig();
+    const ankiConfig = config.ankiConnect;
+    const matchMode = ankiConfig.knownWords?.matchMode === 'surface' ? 'surface' : 'headword';
+    const thresholdDays = getMatureIntervalThresholdDays(ankiConfig);
+    const client = createAnkiClient(ankiConfig.url);
+    const cacheScopeKey = getKnownWordCacheLifecycleConfig(ankiConfig);
+
+    const cache = new KnownWordCacheManager({
+      client: { findNotes: (query) => client.findNotes(query), notesInfo: client.notesInfo },
+      getConfig: () => ankiConfig,
+      knownWordCacheStatePath: scratch.cachePath,
+      showStatusNotification: () => {},
+    });
+    // A cache whose persisted scope key no longer matches the config is
+    // discarded on load, so every token would come back unknown.
+    if (!args.refresh && readPersistedCacheScope(scratch.cachePath) !== cacheScopeKey) {
+      process.stderr.write(
+        'warning: the persisted known-word cache was built under different settings and will be ' +
+          'ignored (the app refetches it on its next refresh). Re-run with --refresh to fetch tiers now.\n',
+      );
+    }
+    // startLifecycle loads the persisted cache; the refresh timer it arms is
+    // cleared before the event loop can run it.
+    cache.startLifecycle();
+    cache.stopLifecycle();
+    if (args.refresh) {
+      await cache.refresh(true);
+    }
+
+    const cues = parseSubtitleCues(fs.readFileSync(args.input, 'utf-8'), args.input);
+    const selectedCues = args.limit > 0 ? cues.slice(0, args.limit) : cues;
+
+    const mecabTokenizer = new MecabTokenizer();
+    if (!(await mecabTokenizer.checkAvailability())) {
+      throw new Error('MeCab is not available; tokenization would not match the overlay.');
+    }
+    electronModule = await loadElectronModule();
+    const userDataPath = args.profileCopy
+      ? copyYomitanProfile(args.yomitanUserDataPath ?? configDir)
+      : (args.yomitanUserDataPath ?? configDir);
+    profileCopyDir = args.profileCopy ? userDataPath : null;
+    if (electronModule?.app && typeof electronModule.app.setPath === 'function') {
+      electronModule.app.setPath('userData', userDataPath);
+    }
+    yomitanState = await createYomitanRuntimeStateWithSearch(
+      userDataPath,
+      args.yomitanExtensionPath,
+    );
+    if (!yomitanState.available) {
+      throw new Error(`Yomitan tokenizer unavailable: ${yomitanState.note ?? 'unknown reason'}`);
+    }
+
+    const deps = createTokenizerDepsRuntime({
+      getYomitanExt: () => yomitanState!.yomitanExt as never,
+      getYomitanSession: () => yomitanState!.yomitanSession as never,
+      getYomitanParserWindow: () => yomitanState!.parserWindow as never,
+      setYomitanParserWindow: (window) => {
+        yomitanState!.parserWindow = window;
+      },
+      getYomitanParserReadyPromise: () => yomitanState!.parserReadyPromise as never,
+      setYomitanParserReadyPromise: (promise) => {
+        yomitanState!.parserReadyPromise = promise;
+      },
+      getYomitanParserInitPromise: () => yomitanState!.parserInitPromise as never,
+      setYomitanParserInitPromise: (promise) => {
+        yomitanState!.parserInitPromise = promise;
+      },
+      isKnownWord: (text, reading, options) => cache.isKnownWord(text, reading, options),
+      getKnownWordTier: (text, reading, options) => cache.getKnownWordTier(text, reading, options),
+      getKnownWordMatchMode: () => matchMode,
+      getKnownWordsEnabled: () => true,
+      // Other annotation layers are off so every colored token below is a
+      // known-word decision, not an N+1/frequency/name override.
+      getNPlusOneEnabled: () => false,
+      getNameMatchEnabled: () => false,
+      getJlptEnabled: () => false,
+      getFrequencyDictionaryEnabled: () => false,
+      getJlptLevel: () => null,
+      getMecabTokenizer: () => ({ tokenize: (text: string) => mecabTokenizer.tokenize(text) }),
+    });
+
+    const styleColors = {
+      ...FALLBACK_TIER_COLORS,
+      ...(config.subtitleStyle?.knownWordMaturityColors ?? {}),
+    } as Record<KnownWordMaturityTier, string>;
+    const knownWordColor = config.subtitleStyle?.knownWordColor ?? '#a6da95';
+
+    const reports: TokenReport[] = [];
+    const tierCounts: Record<string, number> = {};
+    let knownTokens = 0;
+    let totalTokens = 0;
+    const lines: string[] = [];
+
+    for (const [cueIndex, cue] of selectedCues.entries()) {
+      const { text, tokens } = await withTimeout(
+        tokenizeSubtitle(cue.text, deps),
+        20_000,
+        `Tokenizer (cue ${cueIndex + 1})`,
+      );
+      if (!tokens || tokens.length === 0) {
+        continue;
+      }
+
+      let cursor = 0;
+      let rendered = '';
+      const ordered = [...tokens].sort((a, b) => (a.startPos ?? 0) - (b.startPos ?? 0));
+      for (const token of ordered) {
+        totalTokens += 1;
+        const start = Math.min(Math.max(0, token.startPos ?? 0), text.length);
+        const end = Math.min(Math.max(start, token.endPos ?? start), text.length);
+        if (start > cursor) {
+          rendered += text.slice(cursor, start);
+        }
+        const surfaceText = text.slice(start, end);
+        cursor = end;
+
+        if (!token.isKnown) {
+          rendered += surfaceText;
+          continue;
+        }
+        knownTokens += 1;
+        const tier: TierOrFallback = token.knownMaturity ?? 'known-no-tier';
+        tierCounts[tier] = (tierCounts[tier] ?? 0) + 1;
+        rendered += colorize(
+          surfaceText,
+          tier === 'known-no-tier' ? knownWordColor : styleColors[tier],
+        );
+        reports.push({
+          cueIndex,
+          startTime: cue.startTime,
+          surface: token.surface,
+          headword: token.headword,
+          reading: token.reading,
+          tier,
+          noteIds: [...resolveTokenMatch(token, cache, matchMode).noteIds],
+        });
+      }
+      rendered += text.slice(cursor);
+      lines.push(`${formatTimestamp(cue.startTime)}  ${rendered}`);
+    }
+
+    if (totalTokens === 0 && selectedCues.length > 0) {
+      throw new Error(
+        'Yomitan returned no tokens. SubMiner is probably running and holding the Electron ' +
+          'profile lock - quit it, or re-run with --profile-copy.',
+      );
+    }
+
+    let audit: { mismatches: AuditMismatch[]; auditedNotes: number } | null = null;
+    if (args.audit) {
+      audit = await auditTokens(reports, client, thresholdDays);
+    }
+
+    if (args.json) {
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            input: args.input,
+            cues: selectedCues.length,
+            totalTokens,
+            knownTokens,
+            tierCounts,
+            matureThresholdDays: thresholdDays,
+            matchMode,
+            tokens: reports,
+            audit,
+          },
+          null,
+          2,
+        )}\n`,
+      );
+      return;
+    }
+
+    if (!args.quiet) {
+      process.stdout.write(`${lines.join('\n')}\n\n`);
+    }
+    process.stdout.write(
+      [
+        `file           : ${args.input}`,
+        `cues checked   : ${selectedCues.length} of ${cues.length}`,
+        `tokens         : ${totalTokens} (${knownTokens} known, ${totalTokens - knownTokens} unknown)`,
+        `match mode     : ${matchMode}   mature threshold: ${thresholdDays}d`,
+        '',
+        'known-token tiers:',
+        ...TIERS.map(
+          (tier) =>
+            `  ${colorize(tier.padEnd(9), styleColors[tier])} ${String(tierCounts[tier] ?? 0).padStart(5)}` +
+            `  ${styleColors[tier]}`,
+        ),
+        `  ${colorize('no tier'.padEnd(9), knownWordColor)} ${String(tierCounts['known-no-tier'] ?? 0).padStart(5)}  ${knownWordColor} (falls back to knownWordColor)`,
+        '',
+      ].join('\n'),
+    );
+
+    if (audit) {
+      process.stdout.write(
+        `audit: ${reports.length - audit.mismatches.length}/${reports.length} highlighted tokens agree with live Anki card data ` +
+          `(${audit.auditedNotes} notes)\n`,
+      );
+      for (const mismatch of audit.mismatches.slice(0, 40)) {
+        process.stdout.write(
+          `  ${formatTimestamp(mismatch.startTime)} ${mismatch.surface} (${mismatch.headword}) ` +
+            `shown=${mismatch.tier} live=${mismatch.liveTier} ivl=[${mismatch.intervals.join(', ')}] ` +
+            `notes=[${mismatch.noteIds.join(', ')}]\n`,
+        );
+      }
+      if (audit.mismatches.length > 40) {
+        process.stdout.write(`  ... ${audit.mismatches.length - 40} more\n`);
+      }
+    }
+  } finally {
+    destroyParserWindow(yomitanState?.parserWindow ?? null);
+    for (const dir of [scratchDir, profileCopyDir]) {
+      if (dir) {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    }
+    if (electronModule?.app) {
+      electronModule.app.quit();
+    }
+  }
+}
+
+main()
+  .then(() => {
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error(`Error: ${(error as Error).message}`);
+    process.exit(1);
+  });

scripts/yomitan-script-runtime.ts

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { resolveYomitanExtensionPath as resolveBuiltYomitanExtensionPath } from '../src/core/services/yomitan-extension-paths.js';
+
+// Yomitan bootstrap for CLI scripts that need the app's real tokenizer. Mirrors
+// what scripts/get_frequency.ts does inline; new scripts should import this.
+export interface YomitanRuntimeState {
+  yomitanExt: unknown | null;
+  yomitanSession: unknown | null;
+  parserWindow: unknown | null;
+  parserReadyPromise: Promise<void> | null;
+  parserInitPromise: Promise<boolean> | null;
+  available: boolean;
+  note?: string;
+}
+
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    promise
+      .then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+      })
+      .catch((error) => {
+        clearTimeout(timer);
+        reject(error);
+      });
+  });
+}
+
+export function destroyParserWindow(window: unknown): void {
+  if (!window || typeof window !== 'object') {
+    return;
+  }
+  const candidate = window as { isDestroyed?: () => boolean; destroy?: () => void };
+  if (typeof candidate.isDestroyed !== 'function' || typeof candidate.destroy !== 'function') {
+    return;
+  }
+  if (!candidate.isDestroyed()) {
+    candidate.destroy();
+  }
+}
+
+export async function loadElectronModule(): Promise<typeof import('electron') | null> {
+  try {
+    const electronImport = await import('electron');
+    return (electronImport.default ?? electronImport) as typeof import('electron');
+  } catch {
+    return null;
+  }
+}
+
+async function createYomitanRuntimeState(
+  userDataPath: string,
+  extensionPath?: string,
+): Promise<YomitanRuntimeState> {
+  const state: YomitanRuntimeState = {
+    yomitanExt: null,
+    yomitanSession: null,
+    parserWindow: null,
+    parserReadyPromise: null,
+    parserInitPromise: null,
+    available: false,
+  };
+
+  const electronImport = await loadElectronModule();
+  if (
+    !electronImport ||
+    !electronImport.app ||
+    typeof electronImport.app.whenReady !== 'function' ||
+    !electronImport.session
+  ) {
+    state.note = electronImport
+      ? 'electron runtime not available in this process'
+      : 'electron import failed';
+    return state;
+  }
+
+  try {
+    await electronImport.app.whenReady();
+    const loadYomitanExtension = (await import('../src/core/services/yomitan-extension-loader.js'))
+      .loadYomitanExtension as (options: {
+      userDataPath: string;
+      extensionPath?: string;
+      getYomitanParserWindow: () => unknown;
+      setYomitanParserWindow: (window: unknown) => void;
+      setYomitanParserReadyPromise: (promise: Promise<void> | null) => void;
+      setYomitanParserInitPromise: (promise: Promise<boolean> | null) => void;
+      setYomitanExtension: (extension: unknown) => void;
+      setYomitanSession: (session: unknown) => void;
+    }) => Promise<unknown>;
+
+    const extension = await loadYomitanExtension({
+      userDataPath,
+      extensionPath,
+      getYomitanParserWindow: () => state.parserWindow,
+      setYomitanParserWindow: (window) => {
+        state.parserWindow = window;
+      },
+      setYomitanParserReadyPromise: (promise) => {
+        state.parserReadyPromise = promise;
+      },
+      setYomitanParserInitPromise: (promise) => {
+        state.parserInitPromise = promise;
+      },
+      setYomitanExtension: (loaded) => {
+        state.yomitanExt = loaded;
+      },
+      setYomitanSession: (nextSession) => {
+        state.yomitanSession = nextSession;
+      },
+    });
+
+    if (!extension) {
+      state.note = 'yomitan extension is not available';
+      return state;
+    }
+
+    state.yomitanExt = extension;
+    state.available = true;
+    return state;
+  } catch (error) {
+    state.note = error instanceof Error ? error.message : 'failed to initialize yomitan extension';
+    return state;
+  }
+}
+
+export async function createYomitanRuntimeStateWithSearch(
+  userDataPath: string,
+  extensionPath?: string,
+): Promise<YomitanRuntimeState> {
+  const resolvedExtensionPath = resolveBuiltYomitanExtensionPath({
+    explicitPath: extensionPath,
+    cwd: process.cwd(),
+  });
+
+  if (resolvedExtensionPath) {
+    try {
+      if (fs.existsSync(path.join(resolvedExtensionPath, 'manifest.json'))) {
+        const state = await createYomitanRuntimeState(userDataPath, resolvedExtensionPath);
+        if (!state.available && !state.note) {
+          state.note = `Failed to load yomitan extension at ${resolvedExtensionPath}`;
+        }
+        return state;
+      }
+    } catch {
+      // fall through to the unconstrained loader below
+    }
+  }
+
+  return createYomitanRuntimeState(userDataPath, resolvedExtensionPath ?? undefined);
+}

src/anki-integration/known-word-cache-format.test.ts

@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  KnownWordCacheState,
+  knownWordsFromState,
+  parseKnownWordCacheState,
+} from './known-word-cache-format';
+
+function parseOrThrow(value: unknown): KnownWordCacheState {
+  const parsed = parseKnownWordCacheState(value);
+  assert.ok(parsed, 'expected the payload to parse');
+  return parsed;
+}
+
+const BASE = { refreshedAtMs: 1, scope: 'deck:test' };
+
+test('known-word cache format reads words from every version the union covers', () => {
+  assert.deepEqual(
+    knownWordsFromState(parseOrThrow({ ...BASE, version: 1, words: ['する'] })),
+    new Set(['する']),
+  );
+
+  assert.deepEqual(
+    knownWordsFromState(
+      parseOrThrow({ ...BASE, version: 2, words: ['する'], notes: { '1': ['する'] } }),
+    ),
+    new Set(['する']),
+  );
+
+  assert.deepEqual(
+    knownWordsFromState(
+      parseOrThrow({
+        ...BASE,
+        version: 3,
+        notes: { '1': [{ word: 'する', reading: 'する' }], '2': [{ word: '猫', reading: null }] },
+      }),
+    ),
+    new Set(['する', '猫']),
+  );
+
+  // v4 only adds `tiers`; the words a reader sees must not change.
+  assert.deepEqual(
+    knownWordsFromState(
+      parseOrThrow({
+        ...BASE,
+        version: 4,
+        notes: { '1': [{ word: 'する', reading: 'する' }], '2': [{ word: '猫', reading: null }] },
+        tiers: { '1': 'mature', '2': 'young' },
+      }),
+    ),
+    new Set(['する', '猫']),
+  );
+});
+
+test('known-word cache format rejects payloads that are not a known cache state', () => {
+  const notes = { '1': [{ word: 'する', reading: null }] };
+
+  assert.equal(parseKnownWordCacheState(null), null);
+  assert.equal(parseKnownWordCacheState('{}'), null);
+
+  // An unknown version must not be read as an empty cache.
+  assert.equal(parseKnownWordCacheState({ ...BASE, version: 99, notes }), null);
+
+  assert.equal(
+    parseKnownWordCacheState({ version: 4, scope: 'deck:test', notes, tiers: {} }),
+    null,
+  );
+  assert.equal(parseKnownWordCacheState({ version: 4, refreshedAtMs: 1, notes, tiers: {} }), null);
+
+  // v4 without its tiers map is a v3 payload mislabelled as v4.
+  assert.equal(parseKnownWordCacheState({ ...BASE, version: 4, notes }), null);
+
+  // v3 carries entry objects, not the bare strings v2 used.
+  assert.equal(parseKnownWordCacheState({ ...BASE, version: 3, notes: { '1': ['する'] } }), null);
+});

src/anki-integration/known-word-cache-format.ts

@@ -0,0 +1,141 @@
+// On-disk shape of the known-word cache, plus the only parser for it.
+//
+// Two processes read this file: the cache manager (which rebuilds its indexes
+// from it) and the stats server (which counts known words). They used to carry
+// separate hand-written parsers, so bumping the format to v4 for maturity tiers
+// left the stats server silently reporting zero known words. Everything that
+// touches the format now goes through here, and the version dispatch below ends
+// in assertNever so adding a V5 to the union fails the build at every consumer
+// instead of degrading to an empty result at runtime.
+
+import type { KnownWordMaturityTier } from '../types/subtitle';
+import type { KnownWordEntry } from './known-word-entries';
+
+export interface KnownWordCacheStateV1 {
+  readonly version: 1;
+  readonly refreshedAtMs: number;
+  readonly scope: string;
+  readonly words: string[];
+}
+
+export interface KnownWordCacheStateV2 {
+  readonly version: 2;
+  readonly refreshedAtMs: number;
+  readonly scope: string;
+  readonly words: string[];
+  readonly notes: Record<string, string[]>;
+}
+
+export interface KnownWordCacheStateV3 {
+  readonly version: 3;
+  readonly refreshedAtMs: number;
+  readonly scope: string;
+  readonly notes: Record<string, KnownWordEntry[]>;
+}
+
+export interface KnownWordCacheStateV4 {
+  readonly version: 4;
+  readonly refreshedAtMs: number;
+  readonly scope: string;
+  readonly notes: Record<string, KnownWordEntry[]>;
+  readonly tiers: Record<string, KnownWordMaturityTier>;
+}
+
+export type KnownWordCacheState =
+  | KnownWordCacheStateV1
+  | KnownWordCacheStateV2
+  | KnownWordCacheStateV3
+  | KnownWordCacheStateV4;
+
+// Version written by persistKnownWordCacheState. Readers accept every version
+// in the union above; only the writer pins one.
+export type CurrentKnownWordCacheState = KnownWordCacheStateV4;
+
+// Exported so every consumer that switches on `version` can close its dispatch
+// the same way: a new member of the union becomes a type error at each call
+// site rather than a case that silently falls through.
+export function assertNever(value: never): never {
+  throw new Error(`Unhandled known-word cache state: ${JSON.stringify(value)}`);
+}
+
+function isEntryRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isKnownWordEntry(entry: unknown): boolean {
+  if (!isEntryRecord(entry)) return false;
+  const candidate = entry as Partial<KnownWordEntry>;
+  return (
+    typeof candidate.word === 'string' &&
+    (candidate.reading === null || typeof candidate.reading === 'string')
+  );
+}
+
+// Returns the narrowed state, or null when the payload is not a cache state we
+// recognize. Per-entry values that are merely unusable (an unknown maturity
+// tier, a non-numeric note id) are dropped by callers at load time rather than
+// rejecting the whole file.
+export function parseKnownWordCacheState(value: unknown): KnownWordCacheState | null {
+  if (!isEntryRecord(value)) return null;
+  const candidate = value;
+  if (
+    candidate.version !== 1 &&
+    candidate.version !== 2 &&
+    candidate.version !== 3 &&
+    candidate.version !== 4
+  ) {
+    return null;
+  }
+  if (typeof candidate.refreshedAtMs !== 'number') return null;
+  if (typeof candidate.scope !== 'string') return null;
+
+  if (candidate.version === 1 || candidate.version === 2) {
+    if (!Array.isArray(candidate.words)) return null;
+    if (!candidate.words.every((entry: unknown) => typeof entry === 'string')) return null;
+  }
+
+  if (candidate.version === 4) {
+    // Per-tier values are sanitized entry-by-entry at load time.
+    if (!isEntryRecord(candidate.tiers)) return null;
+  }
+
+  if (candidate.version === 2 || candidate.version === 3 || candidate.version === 4) {
+    if (!isEntryRecord(candidate.notes)) return null;
+    const isValidNoteEntry =
+      candidate.version === 2
+        ? (entry: unknown): boolean => typeof entry === 'string'
+        : isKnownWordEntry;
+    if (
+      !Object.values(candidate.notes).every(
+        (noteEntries) => Array.isArray(noteEntries) && noteEntries.every(isValidNoteEntry),
+      )
+    ) {
+      return null;
+    }
+  }
+
+  return candidate as unknown as KnownWordCacheState;
+}
+
+// Every word the cache considers known, flattened across notes. Consumers that
+// only need membership (the stats server) use this instead of walking the
+// version-specific layout themselves.
+export function knownWordsFromState(state: KnownWordCacheState): Set<string> {
+  switch (state.version) {
+    case 1:
+    case 2:
+      return new Set(state.words);
+    case 3:
+    case 4: {
+      const words = new Set<string>();
+      for (const entries of Object.values(state.notes)) {
+        for (const entry of entries) {
+          if (entry.word) words.add(entry.word);
+        }
+      }
+      return words;
+    }
+    default:
+      return assertNever(state);
+  }
+}

src/anki-integration/known-word-cache-maturity.test.ts

@@ -98,7 +98,7 @@ test('lifecycle config key is unchanged when maturity is disabled', () => {
   };
   assert.equal(
     getKnownWordCacheLifecycleConfig(enabled),
-    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":21}',
+    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":21,"maturityRules":2}',
   );
 
   const customThreshold: AnkiConnectConfig = {
@@ -111,7 +111,19 @@ test('lifecycle config key is unchanged when maturity is disabled', () => {
   };
   assert.equal(
     getKnownWordCacheLifecycleConfig(customThreshold),
-    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":30}',
+    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":30,"maturityRules":2}',
+  );
+});
+
+test('a cache built under the old tier rules is invalidated', () => {
+  const config: AnkiConnectConfig = {
+    knownWords: { highlightEnabled: true, maturityEnabled: true, refreshMinutes: 60 },
+  };
+  // v1 rules put lapsed cards in young because the interval queries did not
+  // exclude is:learn; those persisted tiers must not be served under v2.
+  assert.notEqual(
+    getKnownWordCacheLifecycleConfig(config),
+    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":21}',
   );
 });
 
@@ -120,8 +132,8 @@ test('refresh fetches tier sets and getKnownWordTier classifies notes', async ()
 
   try {
     clientState.findNotesByQuery.set('deck:"Mining"', [1, 2, 3, 4]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', [2]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', [2]);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', [3]);
     clientState.notesInfoResult = [
       { noteId: 1, fields: { Word: { value: '猫' } } },
@@ -151,8 +163,8 @@ test('a note with cards in several tiers counts as its most mature card', async
 
   try {
     clientState.findNotesByQuery.set('deck:"Mining"', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', [1]);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', [1]);
     clientState.notesInfoResult = [{ noteId: 1, fields: { Word: { value: '猫' } } }];
 
@@ -169,8 +181,8 @@ test('a word matched by several notes takes the most mature note tier', async ()
 
   try {
     clientState.findNotesByQuery.set('deck:"Mining"', [1, 2]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', []);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', [2]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', []);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', [2]);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', [1]);
     clientState.notesInfoResult = [
       { noteId: 1, fields: { Word: { value: '猫' } } },
@@ -190,8 +202,8 @@ test('tiers are reading-aware for words with several readings', async () => {
 
   try {
     clientState.findNotesByQuery.set('deck:"Mining"', [1, 2]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', []);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', []);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', [2]);
     clientState.notesInfoResult = [
       { noteId: 1, fields: { Word: { value: '床' }, Reading: { value: 'とこ' } } },
@@ -216,8 +228,8 @@ test('reading-only fallback resolves tiers unless opted out', async () => {
 
   try {
     clientState.findNotesByQuery.set('deck:"Mining"', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', []);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', []);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', []);
     clientState.notesInfoResult = [
       { noteId: 1, fields: { Word: { value: '警告' }, Reading: { value: 'けいこく' } } },
@@ -265,7 +277,7 @@ test('refresh preserves known-word cache when maturity lookup fails', async () =
       infoLogs.push(args.map((value) => String(value)).join(' '));
     };
     clientState.findNotesByQuery.set('deck:"Mining"', [1]);
-    clientState.failedQueries.add('deck:"Mining" prop:ivl>=21');
+    clientState.failedQueries.add('deck:"Mining" prop:ivl>=21 -is:learn');
     clientState.notesInfoResult = [{ noteId: 1, fields: { Word: { value: '猫' } } }];
 
     await manager.refresh(true);
@@ -294,8 +306,8 @@ test('tiers persist to v4 state and reload without refetching', async () => {
   try {
     Date.now = () => 120_000;
     clientState.findNotesByQuery.set('deck:"Mining"', [1, 2]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', [1]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', []);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', []);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', [2]);
     clientState.notesInfoResult = [
       { noteId: 1, fields: { Word: { value: '猫' } } },
@@ -348,8 +360,8 @@ test('appendFromNoteInfo preserves an existing maturity tier', async () => {
 
   try {
     clientState.findNotesByQuery.set('deck:"Mining"', [7, 8]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21', [7]);
-    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21', []);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [7]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', []);
     clientState.findNotesByQuery.set('deck:"Mining" is:learn', [8]);
     clientState.notesInfoResult = [
       { noteId: 7, fields: { Word: { value: '猫' } } },
@@ -372,3 +384,40 @@ test('appendFromNoteInfo preserves an existing maturity tier', async () => {
     cleanup();
   }
 });
+
+test('getKnownWordMatchNoteIds reports the notes behind a tier', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    clientState.findNotesByQuery.set('deck:"Mining"', [1, 2, 3]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', [1]);
+    clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', [2]);
+    clientState.findNotesByQuery.set('deck:"Mining" is:learn', [3]);
+    clientState.notesInfoResult = [
+      { noteId: 1, fields: { Word: { value: '床' }, Reading: { value: 'とこ' } } },
+      { noteId: 2, fields: { Word: { value: '床' }, Reading: { value: 'ゆか' } } },
+      { noteId: 3, fields: { Word: { value: '警告' }, Reading: { value: 'けいこく' } } },
+    ];
+
+    await manager.refresh(true);
+
+    // Same matching rules as getKnownWordTier, so an audit can re-derive the
+    // rendered tier from the exact notes that produced it.
+    assert.deepEqual([...manager.getKnownWordMatchNoteIds('床', 'とこ')], [1]);
+    assert.deepEqual([...manager.getKnownWordMatchNoteIds('床', 'ゆか')], [2]);
+    assert.deepEqual([...manager.getKnownWordMatchNoteIds('床')].sort(), [1, 2]);
+    assert.deepEqual([...manager.getKnownWordMatchNoteIds('床', 'しょう')], []);
+    assert.deepEqual([...manager.getKnownWordMatchNoteIds('けいこく')], [3]);
+    assert.deepEqual(
+      [
+        ...manager.getKnownWordMatchNoteIds('けいこく', undefined, {
+          allowReadingOnlyMatch: false,
+        }),
+      ],
+      [],
+    );
+    assert.deepEqual([...manager.getKnownWordMatchNoteIds('馬')], []);
+  } finally {
+    cleanup();
+  }
+});

src/anki-integration/known-word-cache.ts

@@ -7,6 +7,7 @@ import { AnkiConnectConfig } from '../types/anki';
 import type { KnownWordMaturityTier } from '../types/subtitle';
 import { createLogger } from '../logger';
 import {
+  KNOWN_WORD_MATURITY_RULES_VERSION,
   classifyKnownWordNoteTier,
   fetchKnownWordMaturityTierSets,
   getKnownWordMaturityEnabled,
@@ -14,6 +15,11 @@ import {
   maxKnownWordMaturityTier,
   sanitizeKnownWordMaturityTier,
 } from './known-word-maturity';
+import {
+  CurrentKnownWordCacheState,
+  assertNever,
+  parseKnownWordCacheState,
+} from './known-word-cache-format';
 import {
   DEFAULT_KNOWN_WORD_READING_FIELDS,
   KnownWordEntry,
@@ -76,10 +82,14 @@ export function getKnownWordCacheLifecycleConfig(config: AnkiConnectConfig): str
     scope: getKnownWordCacheScopeForConfig(config),
     fieldsWord: trimToNonEmptyString(config.fields?.word) ?? '',
   };
-  // The maturity field is only added while enabled so persisted caches from
+  // The maturity fields are only added while enabled so persisted caches from
   // before the feature existed (or with it off) keep their identity.
+  // maturityRules is the classification-rule version: bump it whenever the tier
+  // queries change meaning so existing caches refetch instead of serving tiers
+  // computed under the old rules.
   if (getKnownWordMaturityEnabled(config)) {
     payload.maturity = getMatureIntervalThresholdDays(config);
+    payload.maturityRules = KNOWN_WORD_MATURITY_RULES_VERSION;
   }
   return JSON.stringify(payload);
 }
@@ -89,42 +99,6 @@ export interface KnownWordCacheNoteInfo {
   fields: Record<string, { value: string }>;
 }
 
-interface KnownWordCacheStateV1 {
-  readonly version: 1;
-  readonly refreshedAtMs: number;
-  readonly scope: string;
-  readonly words: string[];
-}
-
-interface KnownWordCacheStateV2 {
-  readonly version: 2;
-  readonly refreshedAtMs: number;
-  readonly scope: string;
-  readonly words: string[];
-  readonly notes: Record<string, string[]>;
-}
-
-interface KnownWordCacheStateV3 {
-  readonly version: 3;
-  readonly refreshedAtMs: number;
-  readonly scope: string;
-  readonly notes: Record<string, KnownWordEntry[]>;
-}
-
-interface KnownWordCacheStateV4 {
-  readonly version: 4;
-  readonly refreshedAtMs: number;
-  readonly scope: string;
-  readonly notes: Record<string, KnownWordEntry[]>;
-  readonly tiers: Record<string, KnownWordMaturityTier>;
-}
-
-type KnownWordCacheState =
-  | KnownWordCacheStateV1
-  | KnownWordCacheStateV2
-  | KnownWordCacheStateV3
-  | KnownWordCacheStateV4;
-
 const NO_READING_KEY = '';
 
 interface KnownWordCacheClient {
@@ -226,43 +200,56 @@ export class KnownWordCacheManager {
       return null;
     }
 
+    return this.maxTierForNotes(null, this.getKnownWordMatchNoteIds(text, reading, options));
+  }
+
+  // Note ids a known-word lookup matches, using the same matching rules as
+  // getKnownWordTier. Exposed for diagnostics (see
+  // scripts/verify-known-word-highlights.ts), which audits a rendered tier
+  // against the live card data of the notes that produced it.
+  getKnownWordMatchNoteIds(
+    text: string,
+    reading?: string,
+    options?: { allowReadingOnlyMatch?: boolean },
+  ): Set<number> {
+    const matches = new Set<number>();
     const normalized = this.normalizeKnownWordForLookup(text);
     if (normalized.length === 0) {
-      return null;
+      return matches;
     }
 
     const knownReadings = this.wordReadingNoteIds.get(normalized);
     if (knownReadings && knownReadings.size > 0) {
       const normalizedReading =
         typeof reading === 'string' ? normalizeKnownReadingForLookup(reading) : '';
-      let tier: KnownWordMaturityTier | null = null;
       if (normalizedReading.length === 0) {
         for (const noteIds of knownReadings.values()) {
-          tier = this.maxTierForNotes(tier, noteIds);
+          for (const noteId of noteIds) {
+            matches.add(noteId);
           }
-        return tier;
         }
-      const noReadingNotes = knownReadings.get(NO_READING_KEY);
-      if (noReadingNotes) {
-        tier = this.maxTierForNotes(tier, noReadingNotes);
+        return matches;
       }
-      const exactReadingNotes = knownReadings.get(normalizedReading);
-      if (exactReadingNotes) {
-        tier = this.maxTierForNotes(tier, exactReadingNotes);
+      for (const key of [NO_READING_KEY, normalizedReading]) {
+        for (const noteId of knownReadings.get(key) ?? []) {
+          matches.add(noteId);
         }
-      return tier;
+      }
+      return matches;
     }
 
     if (options?.allowReadingOnlyMatch === false) {
-      return null;
+      return matches;
     }
 
     const hiragana = convertKatakanaToHiragana(normalized);
     if ([...hiragana].length === 1) {
-      return null;
+      return matches;
     }
-    const readingNotes = this.readingNoteIds.get(hiragana);
-    return readingNotes ? this.maxTierForNotes(null, readingNotes) : null;
+    for (const noteId of this.readingNoteIds.get(hiragana) ?? []) {
+      matches.add(noteId);
+    }
+    return matches;
   }
 
   private maxTierForNotes(
@@ -824,8 +811,8 @@ export class KnownWordCacheManager {
         return;
       }
 
-      const parsed = JSON.parse(raw) as unknown;
-      if (!this.isKnownWordCacheStateValid(parsed)) {
+      const parsed = parseKnownWordCacheState(JSON.parse(raw) as unknown);
+      if (!parsed) {
         this.clearInMemoryState();
         this.knownWordsStateKey = this.getKnownWordCacheStateKey();
         return;
@@ -838,7 +825,36 @@ export class KnownWordCacheManager {
       }
 
       this.clearInMemoryState();
-      if (parsed.version === 3 || parsed.version === 4) {
+      switch (parsed.version) {
+        case 1:
+          // v1 has no per-note snapshots to convert; refetch from Anki.
+          this.knownWordsStateKey = this.getKnownWordCacheStateKey();
+          return;
+        case 2:
+          // Older states have no readings; load them reading-less (fail-open,
+          // matching the old behavior) but leave the cache marked stale so the
+          // next refresh upgrades entries with readings from Anki.
+          for (const [noteIdKey, words] of Object.entries(parsed.notes)) {
+            const noteId = Number.parseInt(noteIdKey, 10);
+            if (!Number.isInteger(noteId) || noteId <= 0) {
+              continue;
+            }
+            const normalizedEntries = normalizeKnownWordEntryList(
+              words.map((word) => ({
+                word: this.normalizeKnownWordForLookup(word),
+                reading: null,
+              })),
+            );
+            if (normalizedEntries.length === 0) {
+              continue;
+            }
+            this.noteEntriesById.set(noteId, normalizedEntries);
+            this.addEntriesToIndexes(noteId, normalizedEntries);
+          }
+          this.knownWordsStateKey = parsed.scope;
+          return;
+        case 3:
+        case 4:
           for (const [noteIdKey, entries] of Object.entries(parsed.notes)) {
             const noteId = Number.parseInt(noteIdKey, 10);
             if (!Number.isInteger(noteId) || noteId <= 0) {
@@ -863,32 +879,9 @@ export class KnownWordCacheManager {
           this.knownWordsLastRefreshedAtMs = parsed.refreshedAtMs;
           this.knownWordsStateKey = parsed.scope;
           return;
+        default:
+          assertNever(parsed);
       }
-
-      if (parsed.version === 2) {
-        // Older states have no readings; load them reading-less (fail-open,
-        // matching the old behavior) but leave the cache marked stale so the
-        // next refresh upgrades entries with readings from Anki.
-        for (const [noteIdKey, words] of Object.entries(parsed.notes)) {
-          const noteId = Number.parseInt(noteIdKey, 10);
-          if (!Number.isInteger(noteId) || noteId <= 0) {
-            continue;
-          }
-          const normalizedEntries = normalizeKnownWordEntryList(
-            words.map((word) => ({ word: this.normalizeKnownWordForLookup(word), reading: null })),
-          );
-          if (normalizedEntries.length === 0) {
-            continue;
-          }
-          this.noteEntriesById.set(noteId, normalizedEntries);
-          this.addEntriesToIndexes(noteId, normalizedEntries);
-        }
-        this.knownWordsStateKey = parsed.scope;
-        return;
-      }
-
-      // v1 has no per-note snapshots to convert; refetch from Anki.
-      this.knownWordsStateKey = this.getKnownWordCacheStateKey();
     } catch (error) {
       log.warn('Failed to load known-word cache state:', (error as Error).message);
       this.clearInMemoryState();
@@ -910,7 +903,7 @@ export class KnownWordCacheManager {
         }
       }
 
-      const state: KnownWordCacheStateV4 = {
+      const state: CurrentKnownWordCacheState = {
         version: 4,
         refreshedAtMs: this.knownWordsLastRefreshedAtMs,
         scope: this.knownWordsStateKey,
@@ -923,63 +916,6 @@ export class KnownWordCacheManager {
     }
   }
 
-  private isKnownWordCacheStateValid(value: unknown): value is KnownWordCacheState {
-    if (typeof value !== 'object' || value === null) return false;
-    const candidate = value as Record<string, unknown>;
-    if (
-      candidate.version !== 1 &&
-      candidate.version !== 2 &&
-      candidate.version !== 3 &&
-      candidate.version !== 4
-    ) {
-      return false;
-    }
-    if (typeof candidate.refreshedAtMs !== 'number') return false;
-    if (typeof candidate.scope !== 'string') return false;
-    if (candidate.version === 1 || candidate.version === 2) {
-      if (!Array.isArray(candidate.words)) return false;
-      if (!candidate.words.every((entry: unknown) => typeof entry === 'string')) {
-        return false;
-      }
-    }
-    if (candidate.version === 4) {
-      // Per-tier values are sanitized entry-by-entry at load time.
-      if (
-        typeof candidate.tiers !== 'object' ||
-        candidate.tiers === null ||
-        Array.isArray(candidate.tiers)
-      ) {
-        return false;
-      }
-    }
-    if (candidate.version === 2 || candidate.version === 3 || candidate.version === 4) {
-      if (
-        typeof candidate.notes !== 'object' ||
-        candidate.notes === null ||
-        Array.isArray(candidate.notes)
-      ) {
-        return false;
-      }
-      const isValidNoteEntry =
-        candidate.version === 2
-          ? (entry: unknown): boolean => typeof entry === 'string'
-          : (entry: unknown): boolean =>
-              typeof entry === 'object' &&
-              entry !== null &&
-              typeof (entry as KnownWordEntry).word === 'string' &&
-              ((entry as KnownWordEntry).reading === null ||
-                typeof (entry as KnownWordEntry).reading === 'string');
-      if (
-        !Object.values(candidate.notes as Record<string, unknown>).every(
-          (noteEntries) => Array.isArray(noteEntries) && noteEntries.every(isValidNoteEntry),
-        )
-      ) {
-        return false;
-      }
-    }
-    return true;
-  }
-
   private extractKnownWordEntriesFromNoteInfo(
     noteInfo: KnownWordCacheNoteInfo,
     preferredFields = this.getConfiguredFields(),

src/anki-integration/known-word-maturity.test.ts

@@ -46,15 +46,26 @@ test('mature threshold falls back to default for invalid values', () => {
 
 test('tier queries append Anki search props to a deck scope query', () => {
   const queries = buildKnownWordMaturityTierQueries('deck:"Mining"', 21);
-  assert.equal(queries.mature, 'deck:"Mining" prop:ivl>=21');
-  assert.equal(queries.young, 'deck:"Mining" prop:ivl>=1 prop:ivl<21');
+  assert.equal(queries.mature, 'deck:"Mining" prop:ivl>=21 -is:learn');
+  assert.equal(queries.young, 'deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn');
+  assert.equal(queries.learning, 'deck:"Mining" is:learn');
+});
+
+test('interval tiers exclude (re)learning cards so the buckets stay disjoint', () => {
+  const queries = buildKnownWordMaturityTierQueries('deck:"Mining"', 21);
+  // A lapsed card keeps an interval of at least the lapse minInt (>= 1), so
+  // without the exclusion the young query would claim every relearning card
+  // and the learning tier could only ever match brand-new cards mid-step.
+  for (const intervalQuery of [queries.mature, queries.young]) {
+    assert.ok(intervalQuery.includes('-is:learn'));
+  }
   assert.equal(queries.learning, 'deck:"Mining" is:learn');
 });
 
 test('tier queries with an empty scope query have no leading space', () => {
   const queries = buildKnownWordMaturityTierQueries('', 30);
-  assert.equal(queries.mature, 'prop:ivl>=30');
-  assert.equal(queries.young, 'prop:ivl>=1 prop:ivl<30');
+  assert.equal(queries.mature, 'prop:ivl>=30 -is:learn');
+  assert.equal(queries.young, 'prop:ivl>=1 prop:ivl<30 -is:learn');
   assert.equal(queries.learning, 'is:learn');
 });
 

src/anki-integration/known-word-maturity.ts

@@ -3,6 +3,10 @@ import type { KnownWordMaturityTier } from '../types/subtitle';
 
 export const DEFAULT_MATURE_INTERVAL_THRESHOLD_DAYS = 21;
 
+// Version of the tier classification rules; part of the known-word cache
+// identity so a rule change invalidates caches built under the old rules.
+export const KNOWN_WORD_MATURITY_RULES_VERSION = 2;
+
 // Ascending maturity; index order backs tier comparison.
 const TIER_ORDER: readonly KnownWordMaturityTier[] = ['new', 'learning', 'young', 'mature'];
 
@@ -37,14 +41,20 @@ export function getMatureIntervalThresholdDays(config: AnkiConnectConfig): numbe
 // Anki search props classify notes server-side: a note matches a tier query
 // when ANY of its cards matches, which implements most-mature-card-wins for
 // free once tiers are checked in mature > young > learning order.
+//
+// The interval tiers exclude is:learn so the per-card buckets stay disjoint and
+// match Anki's own card counts, where (re)learning is its own bucket rather
+// than part of young/mature. Without the exclusion a lapsed card - whose
+// interval is reset to at least lapse minInt, so >= 1 - is caught by the young
+// query first and the learning tier becomes unreachable in practice.
 export function buildKnownWordMaturityTierQueries(
   scopeQuery: string,
   thresholdDays: number,
 ): KnownWordMaturityTierQueries {
   const prefix = scopeQuery.trim().length > 0 ? `${scopeQuery.trim()} ` : '';
   return {
-    mature: `${prefix}prop:ivl>=${thresholdDays}`,
-    young: `${prefix}prop:ivl>=1 prop:ivl<${thresholdDays}`,
+    mature: `${prefix}prop:ivl>=${thresholdDays} -is:learn`,
+    young: `${prefix}prop:ivl>=1 prop:ivl<${thresholdDays} -is:learn`,
     learning: `${prefix}is:learn`,
   };
 }

src/core/services/__tests__/stats-server.test.ts

@@ -497,6 +497,8 @@ describe('stats server API routes', () => {
         cachePath,
         JSON.stringify({
           version: 1,
+          refreshedAtMs: 1,
+          scope: 'deck:test',
           words: ['する'],
         }),
       );
@@ -561,6 +563,69 @@ describe('stats server API routes', () => {
     });
   });
 
+  it('GET /api/stats/sessions enriches known-word metrics from a v4 maturity cache', async () => {
+    await withTempDir(async (dir) => {
+      const cachePath = path.join(dir, 'known-words.json');
+      fs.writeFileSync(
+        cachePath,
+        JSON.stringify({
+          version: 4,
+          refreshedAtMs: 1,
+          scope: 'deck:test',
+          notes: {
+            '101': [{ word: 'する', reading: 'する' }],
+            '102': [{ word: '猫', reading: null }],
+          },
+          tiers: { '101': 'mature', '102': 'young' },
+        }),
+      );
+
+      const app = createStatsApp(
+        createMockTracker({
+          getSessionWordsByLine: async (sessionId: number) =>
+            sessionId === 1
+              ? [
+                  { lineIndex: 1, headword: 'する', occurrenceCount: 2 },
+                  { lineIndex: 2, headword: '未知', occurrenceCount: 1 },
+                ]
+              : [],
+        }),
+        { knownWordCachePath: cachePath },
+      );
+
+      const res = await app.request('/api/stats/sessions?limit=5');
+      assert.equal(res.status, 200);
+      const body = await res.json();
+      const first = body[0];
+      assert.equal(first.knownWordsSeen, 2);
+      assert.equal(first.knownWordRate, 66.7);
+    });
+  });
+
+  it('GET /api/stats/sessions reports no known words when the cache format is unrecognized', async () => {
+    await withTempDir(async (dir) => {
+      const cachePath = path.join(dir, 'known-words.json');
+      fs.writeFileSync(
+        cachePath,
+        JSON.stringify({ version: 99, refreshedAtMs: 1, scope: 'deck:test', notes: {} }),
+      );
+
+      const app = createStatsApp(
+        createMockTracker({
+          getSessionWordsByLine: async () => [
+            { lineIndex: 1, headword: 'する', occurrenceCount: 2 },
+          ],
+        }),
+        { knownWordCachePath: cachePath },
+      );
+
+      const res = await app.request('/api/stats/sessions?limit=5');
+      assert.equal(res.status, 200);
+      const body = await res.json();
+      assert.equal(body[0].knownWordsSeen, 0);
+    });
+  });
+
   it('GET /api/stats/sessions/:id/events forwards event type filters to the tracker', async () => {
     let seenSessionId = 0;
     let seenLimit = 0;
@@ -609,6 +674,8 @@ describe('stats server API routes', () => {
         cachePath,
         JSON.stringify({
           version: 1,
+          refreshedAtMs: 1,
+          scope: 'deck:test',
           words: ['知る', '猫'],
         }),
       );

src/core/services/stats-server/route-support.ts

@@ -6,11 +6,18 @@ import {
   getConfiguredWordFieldName,
   getPreferredNoteFieldValue,
 } from '../../../anki-field-config.js';
+import {
+  knownWordsFromState,
+  parseKnownWordCacheState,
+} from '../../../anki-integration/known-word-cache-format.js';
+import { createLogger } from '../../../logger.js';
 import type { AnkiConnectConfig } from '../../../types.js';
 import type { StatsExcludedWord } from '../../../types/stats-wire.js';
 import type { ImmersionTrackerService } from '../immersion-tracker-service.js';
 import { splitSentenceSearchTerms } from '../immersion-tracker/query-lexical.js';
 
+const statsKnownWordsLogger = createLogger('stats:known-words');
+
 const STATS_STATIC_CONTENT_TYPES: Record<string, string> = {
   '.css': 'text/css; charset=utf-8',
   '.gif': 'image/gif',
@@ -84,24 +91,14 @@ export function parseExcludedWordsBody(body: unknown): StatsExcludedWord[] | nul
 export function loadKnownWordsSet(cachePath: string | undefined): Set<string> | null {
   if (!cachePath || !existsSync(cachePath)) return null;
   try {
-    const raw = JSON.parse(readFileSync(cachePath, 'utf-8')) as {
-      version?: number;
-      words?: string[];
-      notes?: Record<string, Array<{ word?: unknown; reading?: unknown }>>;
-    };
-    if ((raw.version === 1 || raw.version === 2) && Array.isArray(raw.words)) {
-      return new Set(raw.words);
-    }
-    if (raw.version === 3 && raw.notes && typeof raw.notes === 'object') {
-      const words = new Set<string>();
-      for (const entries of Object.values(raw.notes)) {
-        if (!Array.isArray(entries)) continue;
-        for (const entry of entries) {
-          if (entry && typeof entry.word === 'string' && entry.word) words.add(entry.word);
-        }
-      }
-      return words;
+    const state = parseKnownWordCacheState(JSON.parse(readFileSync(cachePath, 'utf-8')) as unknown);
+    if (!state) {
+      // A cache that exists but does not parse is a format mismatch, not an
+      // empty collection; say so instead of reporting zero known words.
+      statsKnownWordsLogger.warn(`Unrecognized known-word cache format at ${cachePath}`);
+      return null;
     }
+    return knownWordsFromState(state);
   } catch {
     // Treat an unreadable cache as unavailable.
   }

src/core/services/tokenizer/annotation-stage.ts

@@ -63,7 +63,7 @@ export interface AnnotationStageOptions {
   sourceText?: string;
 }
 
-function resolveKnownWordText(
+export function resolveKnownWordText(
   surface: string,
   headword: string,
   matchMode: NPlusOneMatchMode,
@@ -571,7 +571,7 @@ function isCompleteReadingForSurface(surface: string, reading: string): boolean
 // (see isCompleteReadingForSurface); undefined otherwise. Shared so the
 // known-word reading disambiguation and the reading fallback stay in sync if the
 // validity rule changes.
-function resolveCompleteTokenReading(token: MergedToken): string | undefined {
+export function resolveCompleteTokenReading(token: MergedToken): string | undefined {
   const normalizedReading = token.reading.trim();
   if (!normalizedReading || !isCompleteReadingForSurface(token.surface, normalizedReading)) {
     return undefined;
@@ -584,7 +584,7 @@ function resolveCompleteTokenReading(token: MergedToken): string | undefined {
 // inflected surface's reading does not match the dictionary form's reading,
 // and partial furigana readings (see isCompleteReadingForSurface) would cause
 // false negatives. Undefined falls back to text-only matching (fail-open).
-function resolveKnownWordReadingForMatch(
+export function resolveKnownWordReadingForMatch(
   token: MergedToken,
   knownWordMatchMode: NPlusOneMatchMode,
 ): string | undefined {

src/renderer/modals/session-help.test.ts

@@ -9,7 +9,9 @@ import {
   createSessionHelpModal,
   describeSessionHelpCommand,
   formatSessionHelpKeybinding,
+  isKnownWordMaturityLegendEnabled,
 } from './session-help.js';
+import type { RuntimeOptionId, RuntimeOptionState } from '../../types/runtime-options.js';
 
 test('session help describes sub-seek commands as subtitle-line navigation', () => {
   assert.equal(describeSessionHelpCommand(['sub-seek', 1]), 'Jump to next subtitle');
@@ -104,6 +106,34 @@ test('session help builds rows from canonical session bindings and fixed overlay
   assert.ok(rows.some((row) => row.shortcut === 'Y then D' && row.action === 'Toggle DevTools'));
 });
 
+function booleanRuntimeOption(id: RuntimeOptionId, value: boolean): RuntimeOptionState {
+  return {
+    id,
+    label: id,
+    scope: 'subtitle',
+    valueType: 'boolean',
+    value,
+    allowedValues: [true, false],
+    requiresRestart: false,
+  };
+}
+
+test('maturity legend requires both known-word highlighting and maturity coloring', () => {
+  const highlightOn = booleanRuntimeOption('subtitle.annotation.knownWords.highlightEnabled', true);
+  const highlightOff = booleanRuntimeOption(
+    'subtitle.annotation.knownWords.highlightEnabled',
+    false,
+  );
+  const maturityOn = booleanRuntimeOption('subtitle.annotation.knownWords.maturityEnabled', true);
+  const maturityOff = booleanRuntimeOption('subtitle.annotation.knownWords.maturityEnabled', false);
+
+  assert.equal(isKnownWordMaturityLegendEnabled([highlightOn, maturityOn]), true);
+  assert.equal(isKnownWordMaturityLegendEnabled([highlightOff, maturityOn]), false);
+  assert.equal(isKnownWordMaturityLegendEnabled([highlightOn, maturityOff]), false);
+  assert.equal(isKnownWordMaturityLegendEnabled([maturityOn]), false);
+  assert.equal(isKnownWordMaturityLegendEnabled([]), false);
+});
+
 function colorLegendRows(input: Parameters<typeof buildSessionHelpSections>[0]) {
   const sections = buildSessionHelpSections(input);
   return sections.find((section) => section.title === 'Color legend')?.rows ?? [];

src/renderer/modals/session-help.ts

@@ -1,4 +1,5 @@
 import type { ModalStateReader, RendererContext } from '../context';
+import type { RuntimeOptionId, RuntimeOptionState } from '../../types/runtime-options';
 import {
   buildSessionHelpSections,
   type SessionHelpSection,
@@ -19,6 +20,19 @@ type SessionHelpBindingInfo = {
   fallbackUnavailable: boolean;
 };
 
+/**
+ * Tiers only render when known-word highlighting is also on, matching
+ * getKnownWordMaturityEnabled in anki-integration/known-word-maturity.
+ */
+export function isKnownWordMaturityLegendEnabled(runtimeOptions: RuntimeOptionState[]): boolean {
+  const isOn = (id: RuntimeOptionId): boolean =>
+    runtimeOptions.some((option) => option.id === id && option.value === true);
+  return (
+    isOn('subtitle.annotation.knownWords.highlightEnabled') &&
+    isOn('subtitle.annotation.knownWords.maturityEnabled')
+  );
+}
+
 /**
  * Maturity coloring is a live runtime toggle, so the color legend reads it from
  * runtime options instead of the resolved subtitle style. A missing or failing
@@ -26,11 +40,7 @@ type SessionHelpBindingInfo = {
  */
 async function readKnownWordMaturityEnabled(): Promise<boolean> {
   try {
-    const runtimeOptions = await window.electronAPI.getRuntimeOptions();
-    return runtimeOptions.some(
-      (option) =>
-        option.id === 'subtitle.annotation.knownWords.maturityEnabled' && option.value === true,
-    );
+    return isKnownWordMaturityLegendEnabled(await window.electronAPI.getRuntimeOptions());
   } catch {
     return false;
   }