OCR Direction 2: bound read latency as the per-writer store grows (shortlisting + caps) #15

Merged
daniel merged 3 commits from agent/ocr-store-scaling into main 2026-10-20 16:30:45 +02:00
Collaborator

Part of #13 (Direction 2, scaling study — issue #13 part 2). Independent of !12; can land in parallel with it and with the diversity-retention MR.

Why

The per-writer store is about to grow (more word samples; letter templates from !12). Two read-time hot paths scale linearly with store size and will blow the per-remark sync budget. Measured today (throwaway probe, npm install + vitest, rm2 device traces):

WordReader.read — DTW over owner samples (src/ocr/words.ts:218): does a full dtw() over every owner sample, gated only by a width ratio. Unlike readFonts (words.ts:235), which profile-shortlists candidates to 150 before DTW, the owner-sample loop has no shortlist.

owner samples read time / word
50 5.7 ms
200 8.9 ms
1000 28.8 ms
3000 80.4 ms

≈ linear, ~26 µs/sample. A 10-word remark at 3000 samples ≈ 0.8 s of owner-DTW per remark, before fonts.

classify — quick pass over all templates (src/ocr/recognize.ts:254): classify runs matchDistance(cloud, template.cloud, 1) over all templates before keeping the top 24 for the full match. segment calls classify for every 1–3-cluster window, so per word it is O(letters × templates).

templates recognize(1 word)
216 (today's fonts) 92.7 ms
416 138.2 ms
716 220.1 ms
1216 349.0 ms
2216 614.7 ms

≈ linear, ~0.24 ms/template/word. !12's learned letter templates land right here.

What to change

  1. WordReader.read owner-sample shortlist (src/ocr/words.ts, the this.samples loop at ~:222). Before the per-sample dtw(), shortlist by the cheap coarse signal readFonts already uses — profileDistance(trace.profile, sample.trace.profile) plus the width-ratio gate that is already there — and run the full dtw() on only the best ~K (K≈40–60; pick against the budget below). Keep Trace.profile on the stored sample traces (already computed in traceOf). The trusted-match semantics (SAMPLE_TRUST, returning the owner match when trusted) must not change — only the set that gets the expensive DTW narrows.
  2. Bound classify's quick pass (src/ocr/recognize.ts, classify ~:254 / segment ~:412). Either (a) pre-filter templates by the baseline-relative top/bottom/width metrics (cheap scalars already on Template) before the shape matchDistance, scoring shape only for metric-plausible templates, and/or (b) accept a per-character template cap so the total template count stays bounded regardless of store size. Keep the existing "quick pass → top-24 → full match" structure; just stop the quick pass from being unconditionally O(all templates). Do not change OCR_CHARS, cloudOf, or the Candidate/Template shapes.

Shortlisting must not regress accuracy: a correct owner-sample / letter read today must stay correct.

Scope boundary

  • NOT changing the store schema or caps — that is the diversity-retention MR (word-sample caps) and the richer-store child issue (letter/join templates). This MR only bounds the work at read time; it must behave correctly whatever the store size.
  • NOT adding letter/join templates (child issue, after !12). You may test classify scaling by passing synthetic Template[] (duplicate existing templates), as the probe above did.

Validation contract

npx vitest run src/__tests__ → PASS, plus a new test (e.g. src/__tests__/scaling.test.ts) that:

  • Red gate (must fail before the fix): assert WordReader.read on a probe word stays under a per-word budget with a large synthetic store (e.g. 3000 samples) — today ~80 ms, so assert e.g. < 15 ms; and assert recognize of one word with ~1000+ synthetic templates stays under budget — today ~350 ms. Generate load with the spike5.test.ts methodology (render words through a font = a known hand) or the probe shape above.
  • Accuracy guard: a held-out read that is correct today is still correct after shortlisting (seed a handful of owner samples + fonts, read a held-out instance, assert the expected word).

(There is no flake.nix; use npm install + npx vitest, not nix develop.)

Part of #13 (Direction 2, scaling study — issue #13 part 2). Independent of !12; can land in parallel with it and with the diversity-retention MR. ## Why The per-writer store is about to grow (more word samples; letter templates from !12). Two read-time hot paths scale **linearly with store size** and will blow the per-remark sync budget. Measured today (throwaway probe, `npm install` + vitest, rm2 device traces): **`WordReader.read` — DTW over owner samples** (`src/ocr/words.ts:218`): does a full `dtw()` over **every** owner sample, gated only by a width ratio. Unlike `readFonts` (`words.ts:235`), which profile-shortlists candidates to 150 before DTW, the owner-sample loop has no shortlist. | owner samples | read time / word | |---|---| | 50 | 5.7 ms | | 200 | 8.9 ms | | 1000 | 28.8 ms | | 3000 | 80.4 ms | ≈ linear, ~26 µs/sample. A 10-word remark at 3000 samples ≈ 0.8 s of owner-DTW *per remark*, before fonts. **`classify` — quick pass over all templates** (`src/ocr/recognize.ts:254`): `classify` runs `matchDistance(cloud, template.cloud, 1)` over **all** templates before keeping the top 24 for the full match. `segment` calls `classify` for every 1–3-cluster window, so per word it is O(letters × templates). | templates | recognize(1 word) | |---|---| | 216 (today's fonts) | 92.7 ms | | 416 | 138.2 ms | | 716 | 220.1 ms | | 1216 | 349.0 ms | | 2216 | 614.7 ms | ≈ linear, ~0.24 ms/template/word. !12's learned letter templates land right here. ## What to change 1. **`WordReader.read` owner-sample shortlist** (`src/ocr/words.ts`, the `this.samples` loop at ~:222). Before the per-sample `dtw()`, shortlist by the cheap coarse signal `readFonts` already uses — `profileDistance(trace.profile, sample.trace.profile)` plus the width-ratio gate that is already there — and run the full `dtw()` on only the best ~K (K≈40–60; pick against the budget below). Keep `Trace.profile` on the stored sample traces (already computed in `traceOf`). The trusted-match semantics (`SAMPLE_TRUST`, returning the owner match when `trusted`) must not change — only the set that gets the expensive DTW narrows. 2. **Bound `classify`'s quick pass** (`src/ocr/recognize.ts`, `classify` ~:254 / `segment` ~:412). Either (a) pre-filter templates by the baseline-relative `top`/`bottom`/`width` metrics (cheap scalars already on `Template`) before the shape `matchDistance`, scoring shape only for metric-plausible templates, and/or (b) accept a per-character template cap so the total template count stays bounded regardless of store size. Keep the existing "quick pass → top-24 → full match" structure; just stop the quick pass from being unconditionally O(all templates). Do **not** change `OCR_CHARS`, `cloudOf`, or the `Candidate`/`Template` shapes. Shortlisting must not regress accuracy: a correct owner-sample / letter read today must stay correct. ## Scope boundary - NOT changing the store schema or caps — that is the diversity-retention MR (word-sample caps) and the richer-store child issue (letter/join templates). This MR only bounds the **work** at read time; it must behave correctly whatever the store size. - NOT adding letter/join templates (child issue, after !12). You may test `classify` scaling by passing synthetic `Template[]` (duplicate existing templates), as the probe above did. ## Validation contract `npx vitest run src/__tests__` → PASS, plus a new test (e.g. `src/__tests__/scaling.test.ts`) that: - **Red gate (must fail before the fix):** assert `WordReader.read` on a probe word stays under a per-word budget with a large synthetic store (e.g. 3000 samples) — today ~80 ms, so assert e.g. `< 15 ms`; and assert `recognize` of one word with ~1000+ synthetic templates stays under budget — today ~350 ms. Generate load with the `spike5.test.ts` methodology (render words through a font = a known hand) or the probe shape above. - **Accuracy guard:** a held-out read that is correct today is still correct after shortlisting (seed a handful of owner samples + fonts, read a held-out instance, assert the expected word). (There is no `flake.nix`; use `npm install` + `npx vitest`, not `nix develop`.)
claude self-assigned this 2026-10-20 15:32:21 +02:00
Author
Collaborator

✅ Agent run completed

11m31s · 53 turns · $3.85 · pushed agent/ocr-store-scaling · session saved — new comments resume this run

✅ **Agent run completed** _11m31s · 53 turns · $3.85 · pushed `agent/ocr-store-scaling` · session saved — new comments resume this run_
WordReader.read ran a full dtw() over every owner sample; classify's quick
pass ran matchDistance over every template (per letter window). Both scaled
linearly with store size and would blow the per-remark sync budget as word
samples and learned letter templates accumulate.

- words.ts: shortlist owner samples by the cheap profile signal (+ the
  existing width-ratio gate), then full dtw() on only the best ~50 — the same
  narrowing readFonts already does. SAMPLE_TRUST / trusted semantics unchanged.
- recognize.ts: classify's quick pass is now a metric branch-and-bound over a
  per-character-capped template set. The metric penalty is a lower bound on the
  full cost, so templates that cannot reach the top-24 are never shape-matched;
  the cap bounds total templates at ~OCR_CHARS x TEMPLATE_CAP. Same
  quick-pass -> top-24 -> full-match structure and output.

Measured (this runner): read over 3000 samples 174 -> 11 ms; recognize of one
word over ~2160 templates 546 -> ~94 ms. New src/__tests__/scaling.test.ts
red-gates both paths and guards that a correct read stays correct under load.

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

What changed

  • WordReader.read (src/ocr/words.ts): owner samples are now shortlisted by the cheap profile signal (profileDistance + the existing width-ratio gate) and only the best SAMPLE_SHORTLIST=50 get the full dtw() — the same narrowing readFonts already does. SAMPLE_TRUST / trusted semantics are unchanged; only the DTW set narrows.
  • classify (src/ocr/recognize.ts): the quick pass is now a metric branch-and-bound. metricOf (the baseline-relative top/bottom/width penalty) is a lower bound on the full cost, so templates are shape-matched in metric order only until no unseen one could beat the 24th-best — identical top-24 and output, just not O(all templates). Added capPerChar (cap TEMPLATE_CAP=6 per character, applied once in recognize) so total templates stay ~OCR_CHARS × 6 whatever the store size. Bundled fonts have ≤2 variants/char, so nothing bundled is dropped. OCR_CHARS, cloudOf, Candidate/Template untouched.

Verify

npx vitest run src/__tests__ → 672 pass (incl. new src/__tests__/scaling.test.ts); tsc --noEmit and eslint clean. New test red-gates both paths — verified it fails on pre-fix source (read@3000 = 174 ms vs 50 ms budget; recognize@2160 templates = 546 ms vs 250 ms budget) and passes with the fix (≈11 ms and ≈94 ms). Two accuracy guards (owner word still found among 3000 distractors; a print sentence reads identically under a 10×-inflated template store) pass on both pre- and post-fix, confirming they guard correctness, not speed.

Measured on the runner: read@3000 samples 174 → 11 ms; recognize of one word @~2160 templates 546 → ~94 ms (flat in store size). No pipeline has been triggered for this MR head on the forge yet — the above is local verification.

Follow-ups

None. Store schema/caps (word-sample caps, letter/join templates) remain the diversity-retention MR and the richer-store child issue, as scoped.

## What changed - **`WordReader.read`** (`src/ocr/words.ts`): owner samples are now shortlisted by the cheap profile signal (`profileDistance` + the existing width-ratio gate) and only the best `SAMPLE_SHORTLIST`=50 get the full `dtw()` — the same narrowing `readFonts` already does. `SAMPLE_TRUST` / `trusted` semantics are unchanged; only the DTW set narrows. - **`classify`** (`src/ocr/recognize.ts`): the quick pass is now a metric branch-and-bound. `metricOf` (the baseline-relative top/bottom/width penalty) is a lower bound on the full cost, so templates are shape-matched in metric order only until no unseen one could beat the 24th-best — identical top-24 and output, just not O(all templates). Added `capPerChar` (cap `TEMPLATE_CAP`=6 per character, applied once in `recognize`) so total templates stay ~`OCR_CHARS × 6` whatever the store size. Bundled fonts have ≤2 variants/char, so nothing bundled is dropped. `OCR_CHARS`, `cloudOf`, `Candidate`/`Template` untouched. ## Verify `npx vitest run src/__tests__` → **672 pass** (incl. new `src/__tests__/scaling.test.ts`); `tsc --noEmit` and `eslint` clean. New test red-gates both paths — verified it **fails on pre-fix source** (`read`@3000 = 174 ms vs 50 ms budget; `recognize`@2160 templates = 546 ms vs 250 ms budget) and **passes with the fix** (≈11 ms and ≈94 ms). Two accuracy guards (owner word still found among 3000 distractors; a print sentence reads identically under a 10×-inflated template store) pass on both pre- and post-fix, confirming they guard correctness, not speed. Measured on the runner: `read`@3000 samples **174 → 11 ms**; `recognize` of one word @~2160 templates **546 → ~94 ms** (flat in store size). No pipeline has been triggered for this MR head on the forge yet — the above is local verification. ## Follow-ups None. Store schema/caps (word-sample caps, letter/join templates) remain the diversity-retention MR and the richer-store child issue, as scoped.
daniel merged commit 9822b5e140 into main 2026-10-20 16:30:45 +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!15
No description provided.