Jot vocabulary — implementation spec for jot-shared

Everything 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.

Contents

0. Why this exists 1. The 19-language capability 2. BUG: multi-word tail duplication 3. BUG: multi-word placement 4. GUARD: possessives 5. GUARD: inflection (partial) 6. Confidence-conditional ceiling 7. Casing — check your side 8. Things NOT to do 9. Provenance

0. Why this exists

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.

1. The 19-language capability the main ask

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.

1.1 It is not safe everywhere — the table is the deliverable

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.

LangMax distanceFP/1k (real / adv)Note
enno cap0.27 / 0.22baseline; acoustic path preferred when the checkpoint is present
csno cap0.55 / 0.88closest pass
dano cap0.10 / 0.79
esno cap0.00 / 0.32
fino cap0.00 / 0.41predicted worst; is among the safest
frno cap0.00 / 0.08
huno cap0.34 / 0.57also predicted worst; also fine
itno cap0.09 / 0.09
nlno cap0.00 / 0.09
ptno cap0.00 / 0.09
rono cap0.09 / 0.81
skno cap0.32 / 0.11
svno cap0.29 / 0.69
bg0.251.27 adv → 0.10 / 0.20recall 50.7 → 43.8
de0.150.96 adv → 0.00 / 0.19recall 54.3 → 31.4; long words absorb an edit
el0.201.42 real → 0.27 / 0.09recall 35.7 → 18.8
pl0.200.90 adv → 0.11 / 0.45recall 51.8 → 33.9
ru0.201.73 adv → 0.32 / 0.43recall 60.3 → 56.9
uk0.200.99 adv → 0.33 / 0.22recall 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.

1.2 Unmeasured languages

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.

2. BUG — multi-word terms duplicate their trailing word

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:

3. BUG — multi-word terms are never placed when written as separate words

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:

ComparisonSkeletonsDistancevs 0.45
cloud vs Claude Codecloud(5) / claudecode(10)0.60rejected
cloud vs alias Claud codecloud(5) / claudcode(9)0.56rejected
window cloud codecloudcode(9) / claudecode(10)0.20accepted

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:

  1. Per-word alignment against a term/alias of the same width. Whole-window plausibility alone is a text-corrupting brake: 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.
  2. Cross plain spaces only, never a word's own punctuation.
  3. Span ends at the last alphanumeric of the final word — the same boundary 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.

4. GUARD — possessives

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.

5. GUARD — inflection partial — read the limits

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:

  1. Structural — span and term share a stem of ≥ 4 scalars and diverge only in a tail of ≤ 3 either side; and
  2. Lexical — the span is ≥ 7 scalars and is an everyday word minus its final character (the frequency list widened by one trailing character, built lazily per language).

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.

6. Confidence-conditional plausibility ceiling

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.

7. Casing — verify this on your side

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.

8. Things NOT to do

9. Provenance

ExpWhatCorpus
E5corrector vs spotter, head to headFLEURS en_us, 1041 clips, 2.82 h, 22,490 words, CC-BY-4.0
E6brake strength per language9,500 FLEURS clips across 19 languages + a Croatian probe
E7inflection guardE6's 1207 applied corrections
E8confidence-conditional ceiling433 spotter detections over E5's clips
casingP&C recall collapse65 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.