jot-sharedEverything the Windows port measured, written so a Swift agent can implement it in
JotVocabCore. Generated 2026‑07‑26 from the shipping Windows implementation
(jot-windows @ ae2ce1c, 749 tests green).
Read this first. Every claim below is measured, on real human speech, and says which experiment produced it. Where something is unknown or partial, it says so explicitly. Nothing here is a guess dressed as a finding.
The golden fixtures in Tests/JotVocabCoreTests/Fixtures/ are the contract. New cases
covering this work are being added in a PR; they are expected to fail until you implement
this. Drive the work red→green from them rather than from this prose.
Windows ported JotVocabCore to C# and drove it from your golden fixtures, so the two
implementations agree by construction. Running it against real speech then surfaced things the
fixtures could not: two real bugs in applyFromDetections that Swift still
has, two precision guards, and a way to serve 18 more languages with no model at all.
The fixtures missed the bugs for a specific, fixable reason: every case in
detections_apply.json uses a single-word term with no aliases. Both bugs
are multi-word-only. Worth remembering when writing fixtures for the next feature.
A model-free corrector: instead of spotting terms acoustically, fuzzy-match transcript words against the user's terms after decoding, and feed the results through the same gate as a detection source. No model, no download, no licence, works anywhere you already ship a common-word list.
Measured value (E5, English, FLEURS, 1041 clips / 22,490 words): the corrector recovers 34.1 % of terms the engine got wrong, at 0.27 false applies per 1000 words on a realistic 25-term list.
For languages with no acoustic checkpoint, that is 0 % → ~35 % for zero bytes.
The corrector's only safety net beyond its own edit budget is the common-word brake, and the brake's strength is simply how much of running text a 24,000-entry frequency list covers: 88.8 % of English types, 76.3 % of German, 60.1 % of Finnish, 56.9 % of Greek. Shipping to 19 languages on an English measurement would have been unsafe, so E6 measured all of them: 9,500 FLEURS clips through the real engine and the real gate.
Budget: 1.0 false applies / 1000 words, on a realistic 25-term list and a mechanically adversarial one. At or above 0.9 (one measured event from the line) → tighten to the loosest distance bringing both arms ≤ 0.5. Cannot reach that without losing half its recall → do not serve the language at all.
| Lang | Max distance | FP/1k (real / adv) | Note |
|---|---|---|---|
| en | no cap | 0.27 / 0.22 | baseline; acoustic path preferred when the checkpoint is present |
| cs | no cap | 0.55 / 0.88 | closest pass |
| da | no cap | 0.10 / 0.79 | |
| es | no cap | 0.00 / 0.32 | |
| fi | no cap | 0.00 / 0.41 | predicted worst; is among the safest |
| fr | no cap | 0.00 / 0.08 | |
| hu | no cap | 0.34 / 0.57 | also predicted worst; also fine |
| it | no cap | 0.09 / 0.09 | |
| nl | no cap | 0.00 / 0.09 | |
| pt | no cap | 0.00 / 0.09 | |
| ro | no cap | 0.09 / 0.81 | |
| sk | no cap | 0.32 / 0.11 | |
| sv | no cap | 0.29 / 0.69 | |
| bg | 0.25 | 1.27 adv → 0.10 / 0.20 | recall 50.7 → 43.8 |
| de | 0.15 | 0.96 adv → 0.00 / 0.19 | recall 54.3 → 31.4; long words absorb an edit |
| el | 0.20 | 1.42 real → 0.27 / 0.09 | recall 35.7 → 18.8 |
| pl | 0.20 | 0.90 adv → 0.11 / 0.45 | recall 51.8 → 33.9 |
| ru | 0.20 | 1.73 adv → 0.32 / 0.43 | recall 60.3 → 56.9 |
| uk | 0.20 | 0.99 adv → 0.33 / 0.22 | recall 59.0 → 47.5 |
Slovenian is deliberately absent. 1.72 adversarial FP/1k, and the only setting that gets it under 0.5 recovers 16 % of missed terms — 43 % of what it recovers uncapped. The engine is also at 58.6 % WER there, so the premise (a mostly-right transcript with a few mis-spelled terms) does not hold. A feature that corrupts at the budget line and recovers one term in six is not a feature.
Serbian is absent for a different reason: it has a 24,000-entry list but no engine locale, so nothing can select it.
Croatian and Arabic have no common-word list at all. Running the corrector — or the spotter — there means running with the brake absent. Do not enable them on the basis that a model exists.
Default for anything not in the table is the tightest shipped value (0.15), not the loosest — and on Windows it is unreachable, because the mode selector answers Off for anything absent. Fail closed.
Swift has this Reported as jot-shared#1.
transcript: "Claude code generated most of the boiler plate"
term: "Claude Code"
produces: "Claude Code code generated most of the boiler plate" ← wrong
applyFromDetections places a detection onto exactly one whitespace-delimited
token. The two-word term lands on Claude; the transcript's own code
survives after it. decide step (2) then waves every multi-word term through as "precise
and self-gating", so nothing downstream catches it.
The rescore path already has the fix — absorbTrailingDuplicates, whose
own doc comment names this exact string. applyFromDetections has neither it nor
alignmentWindow. Reuse it verbatim; do not re-derive.
Windows notes, from implementing it:
ask Claude, code
review). Widening eats the comma; not widening publishes the duplicate. Both mutate text on a
guess, so block instead and log.Swift has this Found by real dictation, not theory.
user said: "I love Claude Code"
engine wrote: "I love cloud code."
term: "Claude Code"
produces: "I love cloud code." ← no correction, and it is silent
The placement loop compares one token against the whole term:
| Comparison | Skeletons | Distance | vs 0.45 |
|---|---|---|---|
cloud vs Claude Code | cloud(5) / claudecode(10) | 0.60 | rejected |
cloud vs alias Claud code | cloud(5) / claudcode(9) | 0.56 | rejected |
window cloud code | cloudcode(9) / claudecode(10) | 0.20 | accepted |
So a multi-word term only ever worked when the engine happened to merge it into one token.
It looked fine in our synthetic test purely by luck: the engine wrote "Claude code", and
Claude alone scores exactly 0.40 — just under the ceiling.
Fix: scan contiguous N-word windows, widths driven by the word count of the term and each alias (width 1 always tried, so single-word behaviour is byte-identical). Three rules apply to multi-word windows only:
claude wrote measures 0.27 against "Claude
Code" and load code 0.40 — both inside the ceiling. Per-word alignment
(wrote↔Code = 0.60) is what refuses them.absorbTrailingDuplicates picks, so both mechanisms produce identically-shaped spans.Selection: proportional-position distance among plausible candidates; on an exact tie the wider window wins. Mark every word of the chosen window claimed so two detections cannot take the same words. The chosen range is the single identity — anchors, decide input, published text, review row, revert range.
The skeleton drops apostrophes, so Mariana's measures 0.00 against the
term Marianas — a perfect match, and the gate silently rewrites a correct word. This was
5 of 20 false applies in the English measurement; adding the guard took the shipping spotter from
0.89 → 0.67 FP/1k.
The worst failure class outside English. The corrector overwrites a correctly transcribed inflected form with a term's base form:
Russian: Версали (Versailles) → Версаче (Versace) ← brake blocked nothing
Аризона → Аризоны
Finnish: jaavalainen → Jaavalaisten
Czech: Fatima → Fatimě
German: gewürzten → Gewürzen
The honest result: shape alone does not discriminate, and we could not fully fix this. Over 1207 applied corrections (17.4 % base false rate), the inflection shape appears in 76 false applies and 266 correct ones — firing on it destroys 30 real corrections to prevent 33 bad ones.
Proper nouns in an oblique case are unreachable: the same Russian corpus contains
Аризона→Аризоны (wrong) and Аризоне→Аризоны (right) from the same term —
identical length, stem, tail and distance, neither in any frequency list. No threshold separates them.
What shipped is a conjunction, which lifts precision ×4.65 on a small slice:
Measured effect: catches 5 of 29 overwrites (all the same word), Greek 1.42 → 0.89 FP/1k, Polish overwrites 3 → 0, Russian 4 → 2, at a cost of 4 correct corrections, all Greek. English unaffected — it fires zero times there.
Put it in applyFromDetections, not decide — decide is pinned by
the shared fixtures.
clean win Applies to acoustic detections only.
29 % of all correction opportunities sit beyond the 0.45 ceiling — and 35 of them were
already detected by the spotter and then discarded. Herrakit → Parakeet is 0.62
string distance but was heard at −0.313, the best score of five terms. Acoustic evidence is doing work
string similarity cannot see.
effectiveCeiling(score) =
0.45 for score ≤ -1.8
linear ramp for -1.8 < score < -1.0
0.65 for score ≥ -1.0
Every anchor is read off 433 real detections:
Result: +4.7 points of end-to-end recall for zero additional false applies (0-in-22,490-words baseline holds). WER improved in all four measured arms.
It must be conditional. A flat 0.65 admits 30 right and 25 wrong. Beyond 0.45, score > −1.5 is 17 right / 1 wrong; below it, 19 / 34. Two populations.
It needs an acoustic flag on Detection (default false, set
only by the spotter), because score carries two incompatible scales. The corrector must
keep 0.45 — its per-language distances are its knob.
Also: whatever admits a detection at 0.60 during placement must pass the same ceiling into
decide, or it vanishes with no proposal, no row and no log.
Windows shipped a silent zero-recall bug here. The CTC checkpoint is a
punctuation-and-capitalisation model, so token ids differ by casing. A term typed OKTA had
0 % recall — no error, no log, and a UI badge claiming the term was valid.
Measured over 65 words of real speech: as-emitted 100 %, all-lowercase 97 %, Title Case 68 %, ALL CAPS 0 %.
Counter-intuitively lowercase is nearly harmless (models render most words lowercase mid-sentence);
the killers are Title Case on a word the model renders lowercase, and ALL CAPS — i.e. exactly the
initialisms (AWS, NVIDIA) a vocabulary feature exists for.
Fix: search several casing forms per surface (as-typed first and unconditionally, so nothing regresses), take the best-scoring occurrence, report the user's spelling. Windows uses ≤ 5 forms under a 12-query-per-term budget; cost was 20.5 → 73.7 ms of DP on 200 terms.
This may or may not apply to FluidAudio — it depends on that tokenizer, which we did not test. Check whether casing changes ids for your terms before assuming you are unaffected. Do NOT normalize casing at input: the term's casing is what gets pasted into the user's text.
| Exp | What | Corpus |
|---|---|---|
| E5 | corrector vs spotter, head to head | FLEURS en_us, 1041 clips, 2.82 h, 22,490 words, CC-BY-4.0 |
| E6 | brake strength per language | 9,500 FLEURS clips across 19 languages + a Croatian probe |
| E7 | inflection guard | E6's 1207 applied corrections |
| E8 | confidence-conditional ceiling | 433 spotter detections over E5's clips |
| casing | P&C recall collapse | 65 words decoded from real speech |
All real human speech. No TTS — a synthetic voice gives one canonical pronunciation per term, so it can establish that recall is possible but never what it is. That distinction is why the multi-word placement bug survived our synthetic test and died on the first real dictation.
Windows source of truth: jot-windows @ ae2ce1c —
src/Jot/Vocabulary/ and docs/plans/vocabulary-*.md. The C# is a direct port of
JotVocabCore and is conformance-locked to your golden fixtures, so it is a faithful
reference for anything ambiguous here.