Anki maturity-based known-word highlighting (#172)

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

@@ -0,0 +1,411 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { AnkiConnectConfig } from '../types/anki';
+import { setLogLevel } from '../logger';
+import { KnownWordCacheManager, getKnownWordCacheLifecycleConfig } from './known-word-cache';
+
+interface HarnessNoteInfo {
+  noteId: number;
+  fields: Record<string, { value: string }>;
+}
+
+function createMaturityHarness(config: AnkiConnectConfig): {
+  manager: KnownWordCacheManager;
+  calls: { findNotes: number; notesInfo: number; queries: string[] };
+  statePath: string;
+  clientState: {
+    findNotesResult: number[];
+    notesInfoResult: HarnessNoteInfo[];
+    findNotesByQuery: Map<string, number[]>;
+    failedQueries: Set<string>;
+  };
+  createSiblingManager: () => KnownWordCacheManager;
+  cleanup: () => void;
+} {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-known-word-maturity-'));
+  const statePath = path.join(stateDir, 'known-words-cache.json');
+  const calls = { findNotes: 0, notesInfo: 0, queries: [] as string[] };
+  const clientState = {
+    findNotesResult: [] as number[],
+    notesInfoResult: [] as HarnessNoteInfo[],
+    findNotesByQuery: new Map<string, number[]>(),
+    failedQueries: new Set<string>(),
+  };
+  const deps = {
+    client: {
+      findNotes: async (query: string) => {
+        calls.findNotes += 1;
+        calls.queries.push(query);
+        if (clientState.failedQueries.has(query)) {
+          throw new Error(`Anki unavailable for query: ${query}`);
+        }
+        if (clientState.findNotesByQuery.has(query)) {
+          return clientState.findNotesByQuery.get(query) ?? [];
+        }
+        return clientState.findNotesResult;
+      },
+      notesInfo: async (noteIds: number[]) => {
+        calls.notesInfo += 1;
+        return clientState.notesInfoResult.filter((note) => noteIds.includes(note.noteId));
+      },
+    },
+    getConfig: () => config,
+    knownWordCacheStatePath: statePath,
+    showStatusNotification: () => undefined,
+  };
+  return {
+    manager: new KnownWordCacheManager(deps),
+    calls,
+    statePath,
+    clientState,
+    createSiblingManager: () => new KnownWordCacheManager(deps),
+    cleanup: () => {
+      fs.rmSync(stateDir, { recursive: true, force: true });
+    },
+  };
+}
+
+// The four queries a maturity refresh issues, in one place so a query-string
+// change lands in a single spot.
+function setTierQueries(
+  clientState: { findNotesByQuery: Map<string, number[]> },
+  tiers: { all: number[]; mature: number[]; young: number[]; learning: number[] },
+): void {
+  clientState.findNotesByQuery.set('deck:"Mining"', tiers.all);
+  clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=21 -is:learn', tiers.mature);
+  clientState.findNotesByQuery.set('deck:"Mining" prop:ivl>=1 prop:ivl<21 -is:learn', tiers.young);
+  clientState.findNotesByQuery.set('deck:"Mining" is:learn', tiers.learning);
+}
+
+function maturityConfig(overrides: Partial<AnkiConnectConfig> = {}): AnkiConnectConfig {
+  return {
+    deck: 'Mining',
+    fields: { word: 'Word' },
+    knownWords: {
+      highlightEnabled: true,
+      maturityEnabled: true,
+      refreshMinutes: 60,
+    },
+    ...overrides,
+  };
+}
+
+test('lifecycle config key is unchanged when maturity is disabled', () => {
+  const disabled: AnkiConnectConfig = {
+    knownWords: { highlightEnabled: true, refreshMinutes: 60 },
+  };
+  // Upgrading users keep their persisted cache: the key must not gain fields
+  // while maturity is off.
+  assert.equal(
+    getKnownWordCacheLifecycleConfig(disabled),
+    '{"refreshMinutes":60,"scope":"all","fieldsWord":""}',
+  );
+
+  const enabled: AnkiConnectConfig = {
+    knownWords: { highlightEnabled: true, maturityEnabled: true, refreshMinutes: 60 },
+  };
+  assert.equal(
+    getKnownWordCacheLifecycleConfig(enabled),
+    '{"refreshMinutes":60,"scope":"all","fieldsWord":"","maturity":21,"maturityRules":2}',
+  );
+
+  const customThreshold: AnkiConnectConfig = {
+    knownWords: {
+      highlightEnabled: true,
+      maturityEnabled: true,
+      matureThresholdDays: 30,
+      refreshMinutes: 60,
+    },
+  };
+  assert.equal(
+    getKnownWordCacheLifecycleConfig(customThreshold),
+    '{"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}',
+  );
+});
+
+test('refresh fetches tier sets and getKnownWordTier classifies notes', async () => {
+  const { manager, calls, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [1, 2, 3, 4], mature: [1], young: [2], learning: [3] });
+    clientState.notesInfoResult = [
+      { noteId: 1, fields: { Word: { value: '猫' } } },
+      { noteId: 2, fields: { Word: { value: '犬' } } },
+      { noteId: 3, fields: { Word: { value: '鳥' } } },
+      { noteId: 4, fields: { Word: { value: '魚' } } },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(calls.findNotes, 4);
+    assert.equal(manager.getKnownWordTier('猫'), 'mature');
+    assert.equal(manager.getKnownWordTier('犬'), 'young');
+    assert.equal(manager.getKnownWordTier('鳥'), 'learning');
+    assert.equal(manager.getKnownWordTier('魚'), 'new');
+    assert.equal(manager.getKnownWordTier('馬'), null);
+    // Boolean matching still works alongside tiers.
+    assert.equal(manager.isKnownWord('猫'), true);
+    assert.equal(manager.isKnownWord('魚'), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test('a note with cards in several tiers counts as its most mature card', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [1], mature: [1], young: [1], learning: [1] });
+    clientState.notesInfoResult = [{ noteId: 1, fields: { Word: { value: '猫' } } }];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.getKnownWordTier('猫'), 'mature');
+  } finally {
+    cleanup();
+  }
+});
+
+test('a word matched by several notes takes the most mature note tier', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [1, 2], mature: [], young: [2], learning: [1] });
+    clientState.notesInfoResult = [
+      { noteId: 1, fields: { Word: { value: '猫' } } },
+      { noteId: 2, fields: { Word: { value: '猫' } } },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.getKnownWordTier('猫'), 'young');
+  } finally {
+    cleanup();
+  }
+});
+
+test('tiers are reading-aware for words with several readings', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [1, 2], mature: [1], young: [], learning: [2] });
+    clientState.notesInfoResult = [
+      { noteId: 1, fields: { Word: { value: '床' }, Reading: { value: 'とこ' } } },
+      { noteId: 2, fields: { Word: { value: '床' }, Reading: { value: 'ゆか' } } },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.getKnownWordTier('床', 'とこ'), 'mature');
+    assert.equal(manager.getKnownWordTier('床', 'ゆか'), 'learning');
+    // No reading given: fail-open across readings, most mature wins.
+    assert.equal(manager.getKnownWordTier('床'), 'mature');
+    // Unknown reading for a reading-locked word: no match, no tier.
+    assert.equal(manager.getKnownWordTier('床', 'しょう'), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('reading-only fallback resolves tiers unless opted out', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [1], mature: [1], young: [], learning: [] });
+    clientState.notesInfoResult = [
+      { noteId: 1, fields: { Word: { value: '警告' }, Reading: { value: 'けいこく' } } },
+    ];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.getKnownWordTier('けいこく'), 'mature');
+    assert.equal(
+      manager.getKnownWordTier('けいこく', undefined, { allowReadingOnlyMatch: false }),
+      null,
+    );
+  } finally {
+    cleanup();
+  }
+});
+
+test('getKnownWordTier returns null and skips tier queries when maturity is disabled', async () => {
+  const config = maturityConfig();
+  config.knownWords = { ...config.knownWords, maturityEnabled: false };
+  const { manager, calls, clientState, cleanup } = createMaturityHarness(config);
+
+  try {
+    clientState.findNotesByQuery.set('deck:"Mining"', [1]);
+    clientState.notesInfoResult = [{ noteId: 1, fields: { Word: { value: '猫' } } }];
+
+    await manager.refresh(true);
+
+    assert.equal(calls.findNotes, 1);
+    assert.equal(manager.isKnownWord('猫'), true);
+    assert.equal(manager.getKnownWordTier('猫'), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('refresh preserves known-word cache when maturity lookup fails', async () => {
+  const { manager, statePath, clientState, cleanup } = createMaturityHarness(maturityConfig());
+  const originalInfo = console.info;
+  const infoLogs: string[] = [];
+  setLogLevel('info');
+
+  try {
+    console.info = (...args: unknown[]) => {
+      infoLogs.push(args.map((value) => String(value)).join(' '));
+    };
+    clientState.findNotesByQuery.set('deck:"Mining"', [1]);
+    clientState.failedQueries.add('deck:"Mining" prop:ivl>=21 -is:learn');
+    clientState.notesInfoResult = [{ noteId: 1, fields: { Word: { value: '猫' } } }];
+
+    await manager.refresh(true);
+
+    assert.equal(manager.isKnownWord('猫'), true);
+    assert.equal(manager.getKnownWordTier('猫'), null);
+    const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
+      version: number;
+      tiers: Record<string, string>;
+    };
+    assert.equal(persisted.version, 4);
+    assert.deepEqual(persisted.tiers, {});
+    assert.match(infoLogs.join('\n'), /maturityTiers=fetch-failed/);
+  } finally {
+    console.info = originalInfo;
+    setLogLevel(undefined);
+    cleanup();
+  }
+});
+
+test('tiers persist to v4 state and reload without refetching', async () => {
+  const { manager, calls, statePath, clientState, createSiblingManager, cleanup } =
+    createMaturityHarness(maturityConfig());
+  const originalDateNow = Date.now;
+
+  try {
+    Date.now = () => 120_000;
+    setTierQueries(clientState, { all: [1, 2], mature: [1], young: [], learning: [2] });
+    clientState.notesInfoResult = [
+      { noteId: 1, fields: { Word: { value: '猫' } } },
+      { noteId: 2, fields: { Word: { value: '犬' } } },
+    ];
+
+    await manager.refresh(true);
+
+    const persisted = JSON.parse(fs.readFileSync(statePath, 'utf-8')) as {
+      version: number;
+      tiers: Record<string, string>;
+    };
+    assert.equal(persisted.version, 4);
+    assert.deepEqual(persisted.tiers, { '1': 'mature', '2': 'learning' });
+
+    const callsBeforeReload = calls.findNotes;
+    const reloaded = createSiblingManager();
+    reloaded.startLifecycle();
+    try {
+      assert.equal(reloaded.getKnownWordTier('猫'), 'mature');
+      assert.equal(reloaded.getKnownWordTier('犬'), 'learning');
+      assert.equal(calls.findNotes, callsBeforeReload);
+    } finally {
+      reloaded.stopLifecycle();
+    }
+  } finally {
+    Date.now = originalDateNow;
+    cleanup();
+  }
+});
+
+test('appendFromNoteInfo marks freshly mined notes as new tier', async () => {
+  const { manager, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    manager.appendFromNoteInfo({
+      noteId: 7,
+      fields: { Word: { value: '猫' } },
+    });
+
+    assert.equal(manager.isKnownWord('猫'), true);
+    assert.equal(manager.getKnownWordTier('猫'), 'new');
+  } finally {
+    cleanup();
+  }
+});
+
+test('appendFromNoteInfo preserves an existing maturity tier', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [7, 8], mature: [7], young: [], learning: [8] });
+    clientState.notesInfoResult = [
+      { noteId: 7, fields: { Word: { value: '猫' } } },
+      { noteId: 8, fields: { Word: { value: '犬' } } },
+    ];
+    await manager.refresh(true);
+
+    manager.appendFromNoteInfo({
+      noteId: 7,
+      fields: { Word: { value: '子猫' } },
+    });
+    manager.appendFromNoteInfo({
+      noteId: 8,
+      fields: { Word: { value: '子犬' } },
+    });
+
+    assert.equal(manager.getKnownWordTier('子猫'), 'mature');
+    assert.equal(manager.getKnownWordTier('子犬'), 'learning');
+  } finally {
+    cleanup();
+  }
+});
+
+test('getKnownWordMatchNoteIds reports the notes behind a tier', async () => {
+  const { manager, clientState, cleanup } = createMaturityHarness(maturityConfig());
+
+  try {
+    setTierQueries(clientState, { all: [1, 2, 3], mature: [1], young: [2], learning: [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.test.ts

@@ -314,7 +314,7 @@ test('KnownWordCacheManager refresh incrementally reconciles deleted and edited
       version: number;
       notes?: Record<string, Array<{ word: string; reading: string | null }>>;
     };
-    assert.equal(persisted.version, 3);
+    assert.equal(persisted.version, 4);
     assert.deepEqual(persisted.notes, {
       '1': [{ word: '鳥', reading: null }],
     });

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

@@ -4,7 +4,22 @@ import path from 'path';
 import { DEFAULT_ANKI_CONNECT_CONFIG } from '../config';
 import { getConfiguredWordFieldName } from '../anki-field-config';
 import { AnkiConnectConfig } from '../types/anki';
+import type { KnownWordMaturityTier } from '../types/subtitle';
 import { createLogger } from '../logger';
+import {
+  KNOWN_WORD_MATURITY_RULES_VERSION,
+  classifyKnownWordNoteTier,
+  fetchKnownWordMaturityTierSets,
+  getKnownWordMaturityEnabled,
+  getMatureIntervalThresholdDays,
+  maxKnownWordMaturityTier,
+  sanitizeKnownWordMaturityTier,
+} from './known-word-maturity';
+import {
+  CurrentKnownWordCacheState,
+  assertNever,
+  parseKnownWordCacheState,
+} from './known-word-cache-format';
 import {
   DEFAULT_KNOWN_WORD_READING_FIELDS,
   KnownWordEntry,
@@ -62,11 +77,21 @@ export function getKnownWordCacheScopeForConfig(config: AnkiConnectConfig): stri
 }
 
 export function getKnownWordCacheLifecycleConfig(config: AnkiConnectConfig): string {
-  return JSON.stringify({
+  const payload: Record<string, unknown> = {
     refreshMinutes: getKnownWordCacheRefreshIntervalMinutes(config),
     scope: getKnownWordCacheScopeForConfig(config),
     fieldsWord: trimToNonEmptyString(config.fields?.word) ?? '',
-  });
+  };
+  // 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);
 }
 
 export interface KnownWordCacheNoteInfo {
@@ -74,30 +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[]>;
-}
-
-type KnownWordCacheState = KnownWordCacheStateV1 | KnownWordCacheStateV2 | KnownWordCacheStateV3;
-
 const NO_READING_KEY = '';
 
 interface KnownWordCacheClient {
@@ -125,12 +126,13 @@ type KnownWordQueryScope = {
 export class KnownWordCacheManager {
   private knownWordsLastRefreshedAtMs = 0;
   private knownWordsStateKey = '';
-  // word → (hiragana reading | NO_READING_KEY → note count). NO_READING_KEY
+  // word → (hiragana reading | NO_READING_KEY → note ids). NO_READING_KEY
   // entries fail open: the word matches regardless of the token's reading.
-  private wordReadingCounts = new Map<string, Map<string, number>>();
-  // hiragana reading → note count, so kana tokens still match by reading alone.
-  private readingCounts = new Map<string, number>();
+  private wordReadingNoteIds = new Map<string, Map<string, Set<number>>>();
+  // hiragana reading → note ids, so kana tokens still match by reading alone.
+  private readingNoteIds = new Map<string, Set<number>>();
   private noteEntriesById = new Map<number, KnownWordEntry[]>();
+  private noteTierById = new Map<number, KnownWordMaturityTier>();
   private knownWordsRefreshTimer: ReturnType<typeof setInterval> | null = null;
   private knownWordsRefreshTimeout: ReturnType<typeof setTimeout> | null = null;
   private isRefreshingKnownWords = false;
@@ -156,7 +158,7 @@ export class KnownWordCacheManager {
       return false;
     }
 
-    const knownReadings = this.wordReadingCounts.get(normalized);
+    const knownReadings = this.wordReadingNoteIds.get(normalized);
     if (knownReadings && knownReadings.size > 0) {
       const normalizedReading =
         typeof reading === 'string' ? normalizeKnownReadingForLookup(reading) : '';
@@ -168,7 +170,7 @@ export class KnownWordCacheManager {
     }
 
     // Callers that look up a kanji token's reading (not subtitle text) must
-    // opt out of the reading-only fallback: readingCounts holds readings of
+    // opt out of the reading-only fallback: readingNoteIds holds readings of
     // every note including kanji words, so 渓谷's けいこく would match a
     // mined 警告/けいこく.
     if (options?.allowReadingOnlyMatch === false) {
@@ -182,7 +184,86 @@ export class KnownWordCacheManager {
     if ([...hiragana].length === 1) {
       return false;
     }
-    return this.readingCounts.has(hiragana);
+    return this.readingNoteIds.has(hiragana);
+  }
+
+  // Maturity tier for a matching known word, following the exact matching
+  // rules of isKnownWord. A match with no tier data (tier fetch failed or
+  // pre-v4 cache) returns null so rendering falls back to the single
+  // known-word color.
+  getKnownWordTier(
+    text: string,
+    reading?: string,
+    options?: { allowReadingOnlyMatch?: boolean },
+  ): KnownWordMaturityTier | null {
+    if (!getKnownWordMaturityEnabled(this.deps.getConfig())) {
+      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 matches;
+    }
+
+    const knownReadings = this.wordReadingNoteIds.get(normalized);
+    if (knownReadings && knownReadings.size > 0) {
+      const normalizedReading =
+        typeof reading === 'string' ? normalizeKnownReadingForLookup(reading) : '';
+      if (normalizedReading.length === 0) {
+        for (const noteIds of knownReadings.values()) {
+          for (const noteId of noteIds) {
+            matches.add(noteId);
+          }
+        }
+        return matches;
+      }
+      for (const key of [NO_READING_KEY, normalizedReading]) {
+        for (const noteId of knownReadings.get(key) ?? []) {
+          matches.add(noteId);
+        }
+      }
+      return matches;
+    }
+
+    if (options?.allowReadingOnlyMatch === false) {
+      return matches;
+    }
+
+    const hiragana = convertKatakanaToHiragana(normalized);
+    if ([...hiragana].length === 1) {
+      return matches;
+    }
+    for (const noteId of this.readingNoteIds.get(hiragana) ?? []) {
+      matches.add(noteId);
+    }
+    return matches;
+  }
+
+  private maxTierForNotes(
+    current: KnownWordMaturityTier | null,
+    noteIds: ReadonlySet<number>,
+  ): KnownWordMaturityTier | null {
+    let tier = current;
+    for (const noteId of noteIds) {
+      tier = maxKnownWordMaturityTier(tier, this.noteTierById.get(noteId) ?? null);
+      if (tier === 'mature') {
+        break;
+      }
+    }
+    return tier;
   }
 
   refresh(force = false): Promise<void> {
@@ -229,7 +310,7 @@ export class KnownWordCacheManager {
     let didMutateCache = false;
     const currentStateKey = this.getKnownWordCacheStateKey();
     if (this.knownWordsStateKey && this.knownWordsStateKey !== currentStateKey) {
-      didMutateCache = this.wordReadingCounts.size > 0 || this.noteEntriesById.size > 0;
+      didMutateCache = this.wordReadingNoteIds.size > 0 || this.noteEntriesById.size > 0;
       this.clearKnownWordCacheState();
     }
     if (!this.knownWordsStateKey) {
@@ -247,6 +328,15 @@ export class KnownWordCacheManager {
       return didMutateCache;
     }
 
+    // A just-mined card has never been reviewed.
+    if (
+      this.isMaturityTrackingEnabled() &&
+      this.noteEntriesById.has(noteInfo.noteId) &&
+      !this.noteTierById.has(noteInfo.noteId)
+    ) {
+      this.noteTierById.set(noteInfo.noteId, 'new');
+    }
+
     if (this.knownWordsLastRefreshedAtMs <= 0) {
       this.knownWordsLastRefreshedAtMs = Date.now();
     }
@@ -290,6 +380,21 @@ export class KnownWordCacheManager {
     this.isRefreshingKnownWords = true;
     try {
       const noteFieldsById = await this.fetchKnownWordNoteFieldsById();
+      const maturityTrackingEnabled = this.isMaturityTrackingEnabled();
+      let maturityFetchFailed = false;
+      let tierSets = null;
+      if (maturityTrackingEnabled) {
+        try {
+          tierSets = await fetchKnownWordMaturityTierSets(
+            (query, options) => this.deps.client.findNotes(query, options),
+            this.getKnownWordQueryScopes().map((scope) => scope.query),
+            getMatureIntervalThresholdDays(this.deps.getConfig()),
+          );
+        } catch (error) {
+          maturityFetchFailed = true;
+          log.warn('Failed to fetch known-word maturity tiers:', (error as Error).message);
+        }
+      }
       const currentNoteIds = Array.from(noteFieldsById.keys()).sort((a, b) => a - b);
 
       if (this.noteEntriesById.size === 0) {
@@ -316,13 +421,25 @@ export class KnownWordCacheManager {
         }
       }
 
+      this.noteTierById = new Map();
+      if (tierSets) {
+        for (const noteId of currentNoteIds) {
+          this.noteTierById.set(noteId, classifyKnownWordNoteTier(noteId, tierSets));
+        }
+      }
+
       this.knownWordsLastRefreshedAtMs = Date.now();
       this.knownWordsStateKey = frozenStateKey;
       this.persistKnownWordCacheState();
       log.info(
         'Known-word cache refreshed',
         `noteCount=${currentNoteIds.length}`,
-        `wordCount=${this.wordReadingCounts.size}`,
+        `wordCount=${this.wordReadingNoteIds.size}`,
+        tierSets
+          ? `maturityTiers=${this.noteTierById.size}`
+          : maturityFetchFailed
+            ? 'maturityTiers=fetch-failed'
+            : 'maturityTiers=off',
       );
     } catch (error) {
       log.warn('Failed to refresh known-word cache:', (error as Error).message);
@@ -337,6 +454,10 @@ export class KnownWordCacheManager {
     return config.knownWords?.highlightEnabled === true || config.nPlusOne?.enabled === true;
   }
 
+  private isMaturityTrackingEnabled(): boolean {
+    return getKnownWordMaturityEnabled(this.deps.getConfig());
+  }
+
   private shouldAddMinedWordsImmediately(): boolean {
     return this.deps.getConfig().knownWords?.addMinedWordsImmediately !== false;
   }
@@ -593,12 +714,13 @@ export class KnownWordCacheManager {
       return false;
     }
 
-    this.removeEntriesFromCounts(previousEntries);
+    this.removeEntriesFromIndexes(noteId, previousEntries);
     if (normalizedEntries.length > 0) {
       this.noteEntriesById.set(noteId, normalizedEntries);
-      this.addEntriesToCounts(normalizedEntries);
+      this.addEntriesToIndexes(noteId, normalizedEntries);
     } else {
       this.noteEntriesById.delete(noteId);
+      this.noteTierById.delete(noteId);
     }
     return true;
   }
@@ -609,54 +731,68 @@ export class KnownWordCacheManager {
       return;
     }
     this.noteEntriesById.delete(noteId);
-    this.removeEntriesFromCounts(previousEntries);
+    this.noteTierById.delete(noteId);
+    this.removeEntriesFromIndexes(noteId, previousEntries);
   }
 
-  private addEntriesToCounts(entries: KnownWordEntry[]): void {
+  private addEntriesToIndexes(noteId: number, entries: KnownWordEntry[]): void {
     for (const entry of entries) {
       const readingKey = entry.reading ?? NO_READING_KEY;
-      let readings = this.wordReadingCounts.get(entry.word);
+      let readings = this.wordReadingNoteIds.get(entry.word);
       if (!readings) {
         readings = new Map();
-        this.wordReadingCounts.set(entry.word, readings);
+        this.wordReadingNoteIds.set(entry.word, readings);
       }
-      readings.set(readingKey, (readings.get(readingKey) ?? 0) + 1);
+      let noteIds = readings.get(readingKey);
+      if (!noteIds) {
+        noteIds = new Set();
+        readings.set(readingKey, noteIds);
+      }
+      noteIds.add(noteId);
       if (entry.reading) {
-        this.readingCounts.set(entry.reading, (this.readingCounts.get(entry.reading) ?? 0) + 1);
+        let readingNotes = this.readingNoteIds.get(entry.reading);
+        if (!readingNotes) {
+          readingNotes = new Set();
+          this.readingNoteIds.set(entry.reading, readingNotes);
+        }
+        readingNotes.add(noteId);
       }
     }
   }
 
-  private removeEntriesFromCounts(entries: KnownWordEntry[]): void {
+  private removeEntriesFromIndexes(noteId: number, entries: KnownWordEntry[]): void {
     for (const entry of entries) {
       const readingKey = entry.reading ?? NO_READING_KEY;
-      const readings = this.wordReadingCounts.get(entry.word);
+      const readings = this.wordReadingNoteIds.get(entry.word);
       if (readings) {
-        const nextCount = (readings.get(readingKey) ?? 0) - 1;
-        if (nextCount > 0) {
-          readings.set(readingKey, nextCount);
-        } else {
-          readings.delete(readingKey);
-          if (readings.size === 0) {
-            this.wordReadingCounts.delete(entry.word);
+        const noteIds = readings.get(readingKey);
+        if (noteIds) {
+          noteIds.delete(noteId);
+          if (noteIds.size === 0) {
+            readings.delete(readingKey);
+            if (readings.size === 0) {
+              this.wordReadingNoteIds.delete(entry.word);
+            }
           }
         }
       }
       if (entry.reading) {
-        const nextReadingCount = (this.readingCounts.get(entry.reading) ?? 0) - 1;
-        if (nextReadingCount > 0) {
-          this.readingCounts.set(entry.reading, nextReadingCount);
-        } else {
-          this.readingCounts.delete(entry.reading);
+        const readingNotes = this.readingNoteIds.get(entry.reading);
+        if (readingNotes) {
+          readingNotes.delete(noteId);
+          if (readingNotes.size === 0) {
+            this.readingNoteIds.delete(entry.reading);
+          }
         }
       }
     }
   }
 
   private clearInMemoryState(): void {
-    this.wordReadingCounts = new Map();
-    this.readingCounts = new Map();
+    this.wordReadingNoteIds = new Map();
+    this.readingNoteIds = new Map();
     this.noteEntriesById = new Map();
+    this.noteTierById = new Map();
     this.knownWordsLastRefreshedAtMs = 0;
   }
 
@@ -675,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;
@@ -689,48 +825,63 @@ export class KnownWordCacheManager {
       }
 
       this.clearInMemoryState();
-      if (parsed.version === 3) {
-        for (const [noteIdKey, entries] of Object.entries(parsed.notes)) {
-          const noteId = Number.parseInt(noteIdKey, 10);
-          if (!Number.isInteger(noteId) || noteId <= 0) {
-            continue;
+      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);
           }
-          const normalizedEntries = normalizeKnownWordEntryList(entries);
-          if (normalizedEntries.length === 0) {
-            continue;
+          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) {
+              continue;
+            }
+            const normalizedEntries = normalizeKnownWordEntryList(entries);
+            if (normalizedEntries.length === 0) {
+              continue;
+            }
+            this.noteEntriesById.set(noteId, normalizedEntries);
+            this.addEntriesToIndexes(noteId, normalizedEntries);
           }
-          this.noteEntriesById.set(noteId, normalizedEntries);
-          this.addEntriesToCounts(normalizedEntries);
-        }
-        this.knownWordsLastRefreshedAtMs = parsed.refreshedAtMs;
-        this.knownWordsStateKey = parsed.scope;
-        return;
+          if (parsed.version === 4) {
+            for (const [noteIdKey, tier] of Object.entries(parsed.tiers)) {
+              const noteId = Number.parseInt(noteIdKey, 10);
+              const sanitizedTier = sanitizeKnownWordMaturityTier(tier);
+              if (sanitizedTier && this.noteEntriesById.has(noteId)) {
+                this.noteTierById.set(noteId, sanitizedTier);
+              }
+            }
+          }
+          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.addEntriesToCounts(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();
@@ -741,17 +892,23 @@ export class KnownWordCacheManager {
   private persistKnownWordCacheState(): void {
     try {
       const notes: Record<string, KnownWordEntry[]> = {};
+      const tiers: Record<string, KnownWordMaturityTier> = {};
       for (const [noteId, entries] of this.noteEntriesById.entries()) {
         if (entries.length > 0) {
           notes[String(noteId)] = entries;
+          const tier = this.noteTierById.get(noteId);
+          if (tier) {
+            tiers[String(noteId)] = tier;
+          }
         }
       }
 
-      const state: KnownWordCacheStateV3 = {
-        version: 3,
+      const state: CurrentKnownWordCacheState = {
+        version: 4,
         refreshedAtMs: this.knownWordsLastRefreshedAtMs,
         scope: this.knownWordsStateKey,
         notes,
+        tiers,
       };
       fs.writeFileSync(this.statePath, JSON.stringify(state), 'utf-8');
     } catch (error) {
@@ -759,48 +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) {
-      return false;
-    }
-    if (typeof candidate.refreshedAtMs !== 'number') return false;
-    if (typeof candidate.scope !== 'string') return false;
-    if (candidate.version !== 3) {
-      if (!Array.isArray(candidate.words)) return false;
-      if (!candidate.words.every((entry: unknown) => typeof entry === 'string')) {
-        return false;
-      }
-    }
-    if (candidate.version === 2 || candidate.version === 3) {
-      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

@@ -0,0 +1,105 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import type { AnkiConnectConfig } from '../types/anki';
+import {
+  DEFAULT_MATURE_INTERVAL_THRESHOLD_DAYS,
+  buildKnownWordMaturityTierQueries,
+  classifyKnownWordNoteTier,
+  getKnownWordMaturityEnabled,
+  getMatureIntervalThresholdDays,
+  maxKnownWordMaturityTier,
+  sanitizeKnownWordMaturityTier,
+} from './known-word-maturity';
+
+function makeConfig(knownWords: AnkiConnectConfig['knownWords']): AnkiConnectConfig {
+  return { url: 'http://127.0.0.1:8765', knownWords } as AnkiConnectConfig;
+}
+
+test('maturity is enabled only when both highlight and maturity flags are on', () => {
+  assert.equal(
+    getKnownWordMaturityEnabled(makeConfig({ highlightEnabled: true, maturityEnabled: true })),
+    true,
+  );
+  assert.equal(
+    getKnownWordMaturityEnabled(makeConfig({ highlightEnabled: false, maturityEnabled: true })),
+    false,
+  );
+  assert.equal(
+    getKnownWordMaturityEnabled(makeConfig({ highlightEnabled: true, maturityEnabled: false })),
+    false,
+  );
+  assert.equal(getKnownWordMaturityEnabled(makeConfig({ highlightEnabled: true })), false);
+  assert.equal(getKnownWordMaturityEnabled(makeConfig(undefined)), false);
+});
+
+test('mature threshold falls back to default for invalid values', () => {
+  assert.equal(DEFAULT_MATURE_INTERVAL_THRESHOLD_DAYS, 21);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig({ matureThresholdDays: 30 })), 30);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig({ matureThresholdDays: 14.9 })), 14);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig({ matureThresholdDays: 0 })), 21);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig({ matureThresholdDays: -5 })), 21);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig({ matureThresholdDays: Number.NaN })), 21);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig({})), 21);
+  assert.equal(getMatureIntervalThresholdDays(makeConfig(undefined)), 21);
+});
+
+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 -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 -is:learn');
+  assert.equal(queries.young, 'prop:ivl>=1 prop:ivl<30 -is:learn');
+  assert.equal(queries.learning, 'is:learn');
+});
+
+test('note classification picks the most mature matching tier', () => {
+  const sets = {
+    mature: new Set([1, 4]),
+    young: new Set([2, 4]),
+    learning: new Set([3, 4, 2]),
+  };
+  assert.equal(classifyKnownWordNoteTier(1, sets), 'mature');
+  assert.equal(classifyKnownWordNoteTier(2, sets), 'young');
+  assert.equal(classifyKnownWordNoteTier(3, sets), 'learning');
+  // Note with mature, young, and learning cards: most mature card wins.
+  assert.equal(classifyKnownWordNoteTier(4, sets), 'mature');
+  assert.equal(classifyKnownWordNoteTier(99, sets), 'new');
+});
+
+test('maxKnownWordMaturityTier picks the higher tier and tolerates null', () => {
+  assert.equal(maxKnownWordMaturityTier('mature', 'new'), 'mature');
+  assert.equal(maxKnownWordMaturityTier('learning', 'young'), 'young');
+  assert.equal(maxKnownWordMaturityTier('new', null), 'new');
+  assert.equal(maxKnownWordMaturityTier(null, 'learning'), 'learning');
+  assert.equal(maxKnownWordMaturityTier(null, null), null);
+  assert.equal(maxKnownWordMaturityTier(undefined, undefined), null);
+});
+
+test('sanitizeKnownWordMaturityTier accepts only valid tiers', () => {
+  assert.equal(sanitizeKnownWordMaturityTier('mature'), 'mature');
+  assert.equal(sanitizeKnownWordMaturityTier('young'), 'young');
+  assert.equal(sanitizeKnownWordMaturityTier('learning'), 'learning');
+  assert.equal(sanitizeKnownWordMaturityTier('new'), 'new');
+  assert.equal(sanitizeKnownWordMaturityTier('MATURE'), null);
+  assert.equal(sanitizeKnownWordMaturityTier(''), null);
+  assert.equal(sanitizeKnownWordMaturityTier(21), null);
+  assert.equal(sanitizeKnownWordMaturityTier(null), null);
+  assert.equal(sanitizeKnownWordMaturityTier(undefined), null);
+});

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

@@ -0,0 +1,112 @@
+import type { AnkiConnectConfig } from '../types/anki';
+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'];
+
+export interface KnownWordMaturityTierQueries {
+  mature: string;
+  young: string;
+  learning: string;
+}
+
+export interface KnownWordMaturityTierSets {
+  mature: ReadonlySet<number>;
+  young: ReadonlySet<number>;
+  learning: ReadonlySet<number>;
+}
+
+// Maturity tiers only affect how known-word highlights render, so both flags
+// must be on before tier data is fetched or served.
+export function getKnownWordMaturityEnabled(config: AnkiConnectConfig): boolean {
+  return (
+    config.knownWords?.highlightEnabled === true && config.knownWords?.maturityEnabled === true
+  );
+}
+
+export function getMatureIntervalThresholdDays(config: AnkiConnectConfig): number {
+  const threshold = config.knownWords?.matureThresholdDays;
+  if (typeof threshold === 'number' && Number.isFinite(threshold) && threshold >= 1) {
+    return Math.floor(threshold);
+  }
+  return DEFAULT_MATURE_INTERVAL_THRESHOLD_DAYS;
+}
+
+// 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} -is:learn`,
+    young: `${prefix}prop:ivl>=1 prop:ivl<${thresholdDays} -is:learn`,
+    learning: `${prefix}is:learn`,
+  };
+}
+
+export async function fetchKnownWordMaturityTierSets(
+  findNotes: (query: string, options?: { maxRetries?: number }) => Promise<unknown>,
+  scopeQueries: string[],
+  thresholdDays: number,
+): Promise<{ mature: Set<number>; young: Set<number>; learning: Set<number> }> {
+  const sets = {
+    mature: new Set<number>(),
+    young: new Set<number>(),
+    learning: new Set<number>(),
+  };
+  for (const scopeQuery of scopeQueries) {
+    const queries = buildKnownWordMaturityTierQueries(scopeQuery, thresholdDays);
+    for (const tier of ['mature', 'young', 'learning'] as const) {
+      const noteIds = (await findNotes(queries[tier], { maxRetries: 0 })) as number[];
+      if (!Array.isArray(noteIds)) {
+        continue;
+      }
+      for (const noteId of noteIds) {
+        if (Number.isInteger(noteId) && noteId > 0) {
+          sets[tier].add(noteId);
+        }
+      }
+    }
+  }
+  return sets;
+}
+
+export function classifyKnownWordNoteTier(
+  noteId: number,
+  sets: KnownWordMaturityTierSets,
+): KnownWordMaturityTier {
+  if (sets.mature.has(noteId)) return 'mature';
+  if (sets.young.has(noteId)) return 'young';
+  if (sets.learning.has(noteId)) return 'learning';
+  return 'new';
+}
+
+export function maxKnownWordMaturityTier(
+  a: KnownWordMaturityTier | null | undefined,
+  b: KnownWordMaturityTier | null | undefined,
+): KnownWordMaturityTier | null {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  return TIER_ORDER.indexOf(a) >= TIER_ORDER.indexOf(b) ? a : b;
+}
+
+export function sanitizeKnownWordMaturityTier(value: unknown): KnownWordMaturityTier | null {
+  return typeof value === 'string' && TIER_ORDER.includes(value as KnownWordMaturityTier)
+    ? (value as KnownWordMaturityTier)
+    : null;
+}