feat(ocr): diversity-preserving per-letter retention #18

Merged
daniel merged 2 commits from agent/ocr-letter-diversity into main 2026-10-20 17:31:02 +02:00
Collaborator

Part of #17 (OCR Direction 2 — richer persisted store), Part of #13.

Context

!12 (merged) already persists per-letter $P templates in SampleStore.letters (learnLetters, src/ocr/samples.ts:199) and wires them into reads (lettersTemplates → ocrTemplates(), src/main.ts:1918). So issue #17 part 1's "persist letter templates + wire into ocrTemplates()" is already done. What !12 does not do is retain them well: learnLetters keeps the newest PER_LETTER=3 samples per character via .slice(-PER_LETTER) (src/ocr/samples.ts:215). That collapses the owner's letter set onto however they most recently formed a letter — exactly the failure !16 fixed for word samples (keepDiverse, src/ocr/samples.ts:158). This MR closes that gap for letters (issue #17 part 1 remainder + part 4 retention policy for the letter field).

What to change (all in src/ocr/samples.ts)

  1. Generalise keepDiverse to take a cap. It is currently hard-coded to PER_WORD (while (live.length > PER_WORD), :162). Change the signature to e.g. keepDiverse(samples, cap) and update its one caller in addSample (:146) to pass PER_WORD. No behaviour change for words.
    • keepDiverse measures redundancy with the cheap $P cloud distance (cloudOf + matchDistance). That is the right space for letters too — they are the same stroke-cloud representation. (Context: the mr-16 codebase note records that retention deliberately uses the $P proxy, not the reader's DTW; keep that.)
  2. Use the diversity cap in learnLetters (:199). Replace kept[chars[i]] = [...(kept[chars[i]] ?? []), norm].slice(-PER_LETTER) (:215) with: append the new normalised sample, then if the array exceeds PER_LETTER call keepDiverse(kept[chars[i]], PER_LETTER). keepDiverse preserves newest-last order and breaks ties by age, so recency still wins ties — matching the word path.
  3. Document PER_LETTER like the other caps (PER_WORD/REMARKS_KEPT/CORRECTIONS_KEPT, :43–51). It is currently a bare const PER_LETTER = 3 (:45) with a now-wrong comment ("the oldest goes first"). Rewrite the comment to describe the diversity-preserving per-character cap, and choose the value deliberately: read-time cost is bounded by classify's metric branch-and-bound plus capPerChar/TEMPLATE_CAP = 6 per char in recognize.ts (see the mr-15 codebase note). Keep PER_LETTER ≤ TEMPLATE_CAP so no learned letter is silently dropped at read time. 6 aligns the store cap with the read cap; 3 stays conservative. Justify whichever you pick in the comment.

Scope boundary

  • NOT the versioned migrate() seam — that is the sibling MR on agent/ocr-store-migrate. This change makes no shape change (still format: 1, same letters field), so it needs no migration.
  • NOT join/ligature templates or WordReader synthesis — that is child issue #17's split (join work).
  • Do not touch lettersTemplates or the ocrTemplates() wiring — only which letter samples survive the cap.

Validation contract

npm install then npx vitest run src/__tests__ → PASS (no flake.nix).

Add a test in src/__tests__/samples.test.ts mirroring the existing word case "drops a redundant near-duplicate, not a distinct sample, when over cap" (:158):

  • Feed learnLetters (via learnCorrection, the real path) more than PER_LETTER corrections producing one character, where one sample is shape-distinct and the rest are near-duplicates of each other, with the distinct one fed early (so newest-wins would drop it). Assert the distinct sample survives in store.letters[ch].
  • Red gate (must fail on main): on main, .slice(-PER_LETTER) keeps only the newest PER_LETTER, dropping the early distinct sample — so the survival assertion fails before this change. State in the MR that you watched it fail on main first.
  • Keep src/__tests__/letterlearning.test.ts (held-out generalisation) and src/__tests__/scaling.test.ts (read-latency budget) green — the retention change must not regress either. No new latency assertion is needed: per-char template count is bounded by PER_LETTER ≤ TEMPLATE_CAP, so read work is unchanged-to-smaller.
Part of #17 (OCR Direction 2 — richer persisted store), Part of #13. ## Context !12 (merged) already **persists** per-letter $P templates in `SampleStore.letters` (`learnLetters`, `src/ocr/samples.ts:199`) and **wires** them into reads (`lettersTemplates` → `ocrTemplates()`, `src/main.ts:1918`). So issue #17 part 1's "persist letter templates + wire into `ocrTemplates()`" is **already done**. What !12 does *not* do is retain them well: `learnLetters` keeps the **newest** `PER_LETTER=3` samples per character via `.slice(-PER_LETTER)` (`src/ocr/samples.ts:215`). That collapses the owner's letter set onto however they most recently formed a letter — exactly the failure !16 fixed for **word** samples (`keepDiverse`, `src/ocr/samples.ts:158`). This MR closes that gap for letters (issue #17 part 1 remainder + part 4 retention policy for the letter field). ## What to change (all in `src/ocr/samples.ts`) 1. **Generalise `keepDiverse` to take a cap.** It is currently hard-coded to `PER_WORD` (`while (live.length > PER_WORD)`, :162). Change the signature to e.g. `keepDiverse(samples, cap)` and update its one caller in `addSample` (:146) to pass `PER_WORD`. No behaviour change for words. - `keepDiverse` measures redundancy with the cheap $P cloud distance (`cloudOf` + `matchDistance`). That is the right space for letters too — they are the same stroke-cloud representation. (Context: the mr-16 codebase note records that retention deliberately uses the $P proxy, not the reader's DTW; keep that.) 2. **Use the diversity cap in `learnLetters` (:199).** Replace `kept[chars[i]] = [...(kept[chars[i]] ?? []), norm].slice(-PER_LETTER)` (:215) with: append the new normalised sample, then if the array exceeds `PER_LETTER` call `keepDiverse(kept[chars[i]], PER_LETTER)`. `keepDiverse` preserves newest-last order and breaks ties by age, so recency still wins ties — matching the word path. 3. **Document `PER_LETTER` like the other caps** (`PER_WORD`/`REMARKS_KEPT`/`CORRECTIONS_KEPT`, :43–51). It is currently a bare `const PER_LETTER = 3` (:45) with a now-wrong comment ("the oldest goes first"). Rewrite the comment to describe the diversity-preserving per-character cap, and **choose the value deliberately**: read-time cost is bounded by `classify`'s metric branch-and-bound plus `capPerChar`/`TEMPLATE_CAP = 6` per char in `recognize.ts` (see the mr-15 codebase note). Keep `PER_LETTER ≤ TEMPLATE_CAP` so no learned letter is silently dropped at read time. `6` aligns the store cap with the read cap; `3` stays conservative. Justify whichever you pick in the comment. ## Scope boundary - **NOT** the versioned `migrate()` seam — that is the sibling MR on `agent/ocr-store-migrate`. This change makes **no shape change** (still `format: 1`, same `letters` field), so it needs no migration. - **NOT** join/ligature templates or `WordReader` synthesis — that is child issue #17's split (join work). - Do not touch `lettersTemplates` or the `ocrTemplates()` wiring — only *which* letter samples survive the cap. ## Validation contract `npm install` then `npx vitest run src/__tests__` → **PASS** (no `flake.nix`). Add a test in `src/__tests__/samples.test.ts` mirroring the existing word case "drops a redundant near-duplicate, not a distinct sample, when over cap" (:158): - Feed `learnLetters` (via `learnCorrection`, the real path) more than `PER_LETTER` corrections producing one character, where **one sample is shape-distinct** and the rest are near-duplicates of each other, with the distinct one fed **early** (so newest-wins would drop it). Assert the distinct sample survives in `store.letters[ch]`. - **Red gate (must fail on `main`):** on `main`, `.slice(-PER_LETTER)` keeps only the newest `PER_LETTER`, dropping the early distinct sample — so the survival assertion fails before this change. State in the MR that you watched it fail on `main` first. - Keep `src/__tests__/letterlearning.test.ts` (held-out generalisation) and `src/__tests__/scaling.test.ts` (read-latency budget) **green** — the retention change must not regress either. No new latency assertion is needed: per-char template count is bounded by `PER_LETTER ≤ TEMPLATE_CAP`, so read work is unchanged-to-smaller.
claude self-assigned this 2026-10-20 17:12:40 +02:00
Author
Collaborator

✅ Agent run completed

6m25s · 33 turns · $2.66 · pushed agent/ocr-letter-diversity · session saved — new comments resume this run

✅ **Agent run completed** _6m25s · 33 turns · $2.66 · pushed `agent/ocr-letter-diversity` · session saved — new comments resume this run_
Generalise keepDiverse(samples, cap) and apply it in learnLetters so the
per-letter store spans how the owner forms a letter instead of collapsing
onto the newest stroke of it — the same $P-cloud diversity cull !16 gave
word samples. Raise PER_LETTER 3 -> 6 (= TEMPLATE_CAP) so every retained
letter sample survives read-time capPerChar; no shape change, no migration.

Part of #17, Part of #13.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
Author
Collaborator

What changed

  • Generalised keepDiverse(samples, cap) in src/ocr/samples.ts (was hard-coded to PER_WORD); addSample now passes PER_WORD — no behaviour change for words.
  • learnLetters now appends the new normalised sample and, when over cap, calls keepDiverse(…, PER_LETTER) instead of .slice(-PER_LETTER), so the per-letter store keeps the owner's range of a letter rather than collapsing onto the newest stroke — the same $P-cloud diversity cull !16 gave word samples.
  • Documented PER_LETTER like the other caps and raised it 3 → 6 (= TEMPLATE_CAP): capPerChar keeps the owner's lower-weight learned letters ahead of bundled fonts, so at PER_LETTER ≤ TEMPLATE_CAP every retained letter sample survives read-time capping — store cap and read cap line up. No shape change (format: 1, same letters field), so no migration.

Verify

npm install then npx vitest run src/__tests__ → 678 pass / 0 fail, including the new samples.test.ts case "keeps a distinct letter shape fed early over later near-duplicates" and the still-green letterlearning.test.ts (held-out generalisation) and scaling.test.ts (read-latency budget). Red gate watched fail first: I temporarily restored .slice(-PER_LETTER) and the new test failed (the early distinct loop sample was dropped — expected [ …(6) ] to include [distinct]), then restored keepDiverse. tsc -noEmit and eslint on the changed files are clean. (No pipeline has run for the head SHA yet; the local vitest run is the validation contract.)

Follow-ups

None. Scope-excluded as intended: versioned migrate() seam (sibling MR on agent/ocr-store-migrate), join/ligature templates (child issue #17), and the lettersTemplates/ocrTemplates() wiring (untouched).

## What changed - Generalised `keepDiverse(samples, cap)` in `src/ocr/samples.ts` (was hard-coded to `PER_WORD`); `addSample` now passes `PER_WORD` — no behaviour change for words. - `learnLetters` now appends the new normalised sample and, when over cap, calls `keepDiverse(…, PER_LETTER)` instead of `.slice(-PER_LETTER)`, so the per-letter store keeps the owner's *range* of a letter rather than collapsing onto the newest stroke — the same $P-cloud diversity cull !16 gave word samples. - Documented `PER_LETTER` like the other caps and raised it `3 → 6` (= `TEMPLATE_CAP`): `capPerChar` keeps the owner's lower-weight learned letters ahead of bundled fonts, so at `PER_LETTER ≤ TEMPLATE_CAP` every retained letter sample survives read-time capping — store cap and read cap line up. No shape change (`format: 1`, same `letters` field), so no migration. ## Verify `npm install` then `npx vitest run src/__tests__` → **678 pass / 0 fail**, including the new `samples.test.ts` case "keeps a distinct letter shape fed early over later near-duplicates" and the still-green `letterlearning.test.ts` (held-out generalisation) and `scaling.test.ts` (read-latency budget). **Red gate watched fail first:** I temporarily restored `.slice(-PER_LETTER)` and the new test failed (the early distinct loop sample was dropped — `expected [ …(6) ] to include [distinct]`), then restored `keepDiverse`. `tsc -noEmit` and `eslint` on the changed files are clean. (No pipeline has run for the head SHA yet; the local vitest run is the validation contract.) ## Follow-ups None. Scope-excluded as intended: versioned `migrate()` seam (sibling MR on `agent/ocr-store-migrate`), join/ligature templates (child issue #17), and the `lettersTemplates`/`ocrTemplates()` wiring (untouched).
daniel merged commit 71d07885b7 into main 2026-10-20 17:31:02 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
daniel/obsidian-remarkable-round-trip!18
No description provided.