docs(phase-02): phase execution report - 10/11 plans, findings, measurements, deploy blocker

.planning/phases/02-japanese-language-core/02-EXECUTION-REPORT.md

@@ -0,0 +1,225 @@
+# Phase 02 — Japanese Language Core: Execution Report
+
+status: blocked-on-deploy
+phase: 02-japanese-language-core
+plans_complete: 10 of 11
+commits: 54 (`df2c231`..`5411e5e`)
+written: 2026-09-12
+
+---
+
+## What the phase set out to do
+
+Give the learner a page where Japanese is *readable*, not just audible: every line broken into
+whole words, furigana over the kanji at a level the learner picks, a tap on any word explaining
+it, and an English reveal per line. Requirements JPN-01 through JPN-04.
+
+Phase 1 had shipped the voice-and-avatar loop. Phase 2 adds the language layer behind the same
+`gr.HTML` bridge, with no new transport and no GPU on the turn path.
+
+---
+
+## Status
+
+Ten of eleven plans are complete, committed and locally green. The eleventh (`02-10`) is an
+owner-gated close-out that cannot run until the build is on the Space.
+
+| Wave | Plan | What it built | Status |
+|------|------|---------------|--------|
+| 1 | 02-01 | LFS arming, stack pins, JLPT + compact JMdict data sets | ✓ Complete |
+| 2 | 02-02 | Morphemes → whole-word units; ruby alignment; reading overrides | ✓ Complete |
+| 2 | 02-03 | Ranked JMdict headword lookup; JLPT level derivation (both axes) | ✓ Complete |
+| 2 | 02-04 | OPUS-MT ja→en converted to CTranslate2 int8; translate() | ✓ Complete |
+| 3 | 02-05 | The canonical `analyze(text)`; 28-sentence golden set | ✓ Complete |
+| 4 | 02-06 | Three server functions; tokens on every directive; warm-up | ✓ Complete |
+| 5 | 02-07 | Furigana on the page: three modes, level picker, persistence | ✓ Complete |
+| 6 | 02-08 | Word-lookup popover, zero bridge calls per tap | ✓ Complete |
+| 7 | 02-09 | Inline EN reveal with per-line cache and state machine | ✓ Complete |
+| 8 | 02-11 | Nine licence rows verified; on-page credits; docs/LANGUAGE.md | ✓ Complete |
+| 9 | 02-10 | Deployed suite, latency record, phone rows, requirement marks | ⬜ **Blocked** |
+
+**Blocker:** the build has not been pushed to the Space. Local `master` is 54 commits ahead of
+`space/main`, which still runs `df2c231`. The four LFS objects the build needs **were uploaded
+successfully** (`git lfs push space master`, 87 MB); only the ref update remains.
+
+---
+
+## What shipped
+
+### Server side — `src/japanese_avatar/nlp/`
+
+| Module | Role |
+|--------|------|
+| `tokenizer.py` | Sudachi mode-C morphemes; **per-thread** instance under a build lock |
+| `units.py` | Morphemes → whole-word units (joining rules A1–A7) |
+| `ruby.py` | Surface + reading → per-kanji-run ruby spans, with an honest fallback |
+| `overrides.py` | Committed reading-override table |
+| `jmdict.py` | Compact JMdict loader; ranked headword lookup |
+| `levels.py` | JLPT level derivation on the word and kanji axes |
+| `analyzer.py` | The one canonical `analyze(text)` → 14-key token records |
+| `translate.py` | CTranslate2 int8 translator, singleton + warm-up |
+| `warm.py` | Whole-language warm-up with per-component timings and RSS |
+
+### Browser side — `avatar/`
+
+`transcript.js` owns rendering and all three reading features; `transcript.css` styles them;
+`transcript-harness.html` exercises the module with no server at all. `host.js` owns *policy*
+(which line, which cache, when to call) and holds the single `avatar.translate()` call site in
+the codebase. `avatar.js`, `avatar-iframe.js` and `stage.html` were changed by **zero lines** —
+the transport seam Phase 1 established held for the whole phase.
+
+### Data, all pinned and hash-checked
+
+| Asset | Pin | Size |
+|-------|-----|------|
+| JLPT vocabulary (yomitan-jlpt-vocab) | tag `2025.08.01.0` | 8,293 rows, 7,748 unique ids |
+| Kanji levels (kanji-data) | commit `00fd7079…` | 2,211 kanji |
+| Compact JMdict projection | jmdict-eng `3.6.2` | 218,672 entries, 7.66 MB gz (LFS) |
+| OPUS-MT ja→en → CTranslate2 int8 | Hub rev `0770961a…` | 77,339,435 B (LFS) |
+
+---
+
+## Four findings that a green test suite would not have shown
+
+These are the substance of the phase. Each was found by a check that was *built to be able to
+fail*, and each is fixed and pinned.
+
+### 1. The Japanese tokenizer is not safe to share between threads
+
+`sudachipy.Tokenizer` takes a mutable borrow for the whole `tokenize()` call. A second thread
+gets `RuntimeError: Already borrowed` — and the server's own error path swallowed it and returned
+an empty token list so the turn would still *speak*. The visible symptom was an avatar line that
+rendered without furigana, occasionally, with tests green on both sides. Five of eight concurrent
+calls were being lost.
+
+Plan 02-07 is what made it reachable: it analyses the learner's line while the turn's own analyse
+stage runs. The `Dictionary` stays process-wide (the mmapped ~110 MB); `get_tokenizer()` is now
+`threading.local` under a build lock. 288 of 288 concurrent tokenisations clean.
+
+**The guard is mutation-tested.** Reverting to a shared instance makes
+`tests/test_analyzer.py::test_analyze_is_thread_safe` fail with the real exception — the test
+cannot pass against the broken implementation.
+
+### 2. A word card could cover the word it explained
+
+On a phone column, a card clamped back into the viewport could land on top of its own anchor. The
+next tap then hit the card: the dismiss handler returned early because the target was inside the
+popover, and the open handler found no word under the pointer. The tap was swallowed in total
+silence. Placement now picks the side with more room and caps the card's height to that room.
+
+### 3. The transcript panel had never actually scrolled
+
+`#transcript-text` was an auto-height block, so *any* card anchored to the last line hung below
+the visible area — the plan's phone must-have was unreachable on the real page. It is now a fixed
+40vh scrolling column (335 px on a Pixel 7). Side effect worth knowing: `host.js`'s long-standing
+`el.scrollTop = el.scrollHeight` does something for the first time; on an auto-height element it
+had always been a no-op.
+
+### 4. Two acceptance checks could not fail
+
+In plan 02-09, the grep asserting the translate call existed was matching a **comment**, because
+the real call was chained across two lines. Deleting the actual call would have left both the grep
+and the seam test green. A second check asserted the absence of something that had existed since
+the previous plan. Both are now exact enough to break when the code they guard is removed.
+
+A third, in 02-11, was met by substitute evidence rather than literally: the dictionary credit
+string is defined **once** and interpolated into both the footer and the About panel, so the
+plan's "appears at least twice" grep returns 1. Retyping the string to satisfy the grep would
+create exactly the drift the machine-readable credits block exists to prevent. The rehearsal's own
+printout — all five credits present across footer, About panel and `GET /config` — is recorded in
+the summary in its place.
+
+---
+
+## Corrections to the research, made against primary sources
+
+The phase refused to inherit numbers it could not reproduce.
+
+| Claim in research/plan | Measured truth |
+|---|---|
+| 7,747 unique JLPT ids | **7,748**, all of which resolve in JMdict |
+| 505 ids on more than one level | **447** ids; the 505 counted *rows*, not ids |
+| jmdict-eng top-level `version` is the release tag | It is `"3.6.2"`; the plan's assertion would have rejected the correct file |
+| OPUS-MT rights holder "Language Technology Research Group" | The Hub org's own name is **"Helsinki-NLP Research Group"**, University of Helsinki |
+| SudachiDict licence resolvable from the GitHub API | API returns `license: null` (its file is `LICENSE-2.0.txt`); Apache-2.0 rests on the repo's own `LICENSE`/`LEGAL`/`README` plus PyPI. `LEGAL` also discloses bundled **UniDic** (BSD-3-Clause) and **NEologd**, which the plan did not mention |
+
+All nine Phase 2 licence rows were verified against primary sources on 2026-09-07. Every one of
+the fourteen cited URLs returned 200. Nothing was unreachable; nothing was guessed.
+
+### Honest level results that look like bugs and are not
+
+`日本語` and `ない` badge as `N1+ / beyond lists` because they sit on none of the five pinned
+lists. `こんにちは` is N3. `なる` badges N3 because the N5 list's `なる` row points at the archaic
+copula, not the verb. `いい` resolves to its own JMdict entry `2820690`, not `良い`. These are
+upstream list truths, recorded in the golden set rather than special-cased away.
+
+---
+
+## Numbers
+
+### Local suites at the end of the phase
+
+| Suite | Result |
+|---|---|
+| Quick loop (`tests`, no e2e, no mt) | **343 passed**, 17 deselected, 35.66 s (budget 40 s) |
+| Whole `tests/e2e/` | **39 passed**, 25 skipped, 0 failed |
+| Translation marker (`-m mt`) | 17 passed |
+| `ruff check` / `ruff format --check` | clean, 58 files |
+
+### Measured behaviour
+
+| Measurement | Value |
+|---|---|
+| Warm analysis, 36-mora sentence | 0.14–0.19 ms |
+| Ranked lookup, 10,000 iterations | 22.7 ms (budget 50) |
+| Compact JMdict load | 0.56–0.70 s gz; 2.0–2.4 s to indexed entries |
+| Translator warm-up | 0.35 s |
+| Translation, idle, per sentence | 22–286 ms |
+| Language warm-up, fresh process | tokenizer 0.04 s, JMdict 2.4 s, translator 0.34 s; RSS +467 MB |
+| Ruby `rt` height | 11 px; line height always-vs-never 32.39 / 29.39 |
+| Word card, requests per tap | `[]` under both transports and deployed |
+| EN reveal, deployed rehearsal | 2,062 / 2,438 ms tap→shown; cached re-show `[]` requests |
+
+**Every "deployed" number above was measured against a local `DISABLE_GPU=1 app.py` on loopback.**
+They are rehearsals awaiting the owner's push, and they are labelled that way in every summary.
+Real Space numbers are plan 02-10's job.
+
+### A caveat on browser timings
+
+Under headless SwiftShader this machine is badly starved. The learner line's analyse round trip
+measures 14.6–22.7 s of wall clock against 0.02–0.19 ms of server work, because Gradio serves it
+around a 12–19 s synthesis. Phase 1's lesson — record timings, do not assert tight budgets —
+applied throughout, and three absolute ceilings that flake under load were logged rather than
+chased.
+
+---
+
+## Deferred, with owners
+
+Six items in `deferred-items.md`. The three that matter:
+
+1. **First-turn wait behind the language warm-up on the Space is unmeasured.** Locally the warm-up
+   finishes 1.2 s before the first frame so a tap cannot overlap it, but the Space's CPU is 3–6×
+   slower. 02-10 should time a "Say hello" tapped immediately after `ready`.
+2. **The learner's furigana costs a second round trip.** The avatar echoes the same text in
+   Phase 2, so one analysis could serve both lines — but Phase 3 makes the two lines differ, so
+   the split shape was kept deliberately.
+3. **Three wall-clock ceilings flake under whole-suite load** and pass in isolation (Phase 1's
+   tap-to-running ceiling, the WASM ASR fallback, the JMdict lookup budget). All are machine-speed
+   constants on a shared laptop, not product properties.
+
+---
+
+## What 02-10 still needs
+
+1. **The push** — `git push space master:main`. The LFS objects are already uploaded.
+2. Deployed suite on the pushed revision, with `DISABLE_GPU` read back.
+3. Real translation latency into `docs/LATENCY.md § Translation` with the revision SHA, plus the
+   container's cores, memory and post-warm-up RSS into `docs/HOSTING.md`.
+4. **Phone rows** — furigana legibility, popover thumb reach and translation quality judged on a
+   real device, recorded with who judged what. These need a human and a phone.
+5. JPN-01 through JPN-04 marked complete **only** for rows that actually passed on the pushed
+   revision. Nothing has been marked yet, deliberately, across all ten plans.
+
+Note that Phase 1's `AVTR-01` also still awaits an owner phone retest, and the same push serves
+both.