issues: 9 bugs closed + verification ladder + L5-verified InterleavedReader#60
Open
anantham wants to merge 22 commits into
Open
issues: 9 bugs closed + verification ladder + L5-verified InterleavedReader#60anantham wants to merge 22 commits into
anantham wants to merge 22 commits into
Conversation
…umed by #1 Live Playwright cold-boot trace on isolated worktree (port 5183, fresh IDB) shows `[Providers] All providers registered:` log fires **zero** times, while `[Store:init] initializeStore – begin` and `[DataRepair] Starting repair` each fire **two** times. The user's symptom-of-concern lives at the bootstrap layer (StrictMode double-mount, no in-flight guard at initializeStore.ts:423), not the provider-registration layer. Verdict: confusion / superseded-by-#1. Provider registration is module-level singleton via ESM module-eval; Map.set is idempotent. No own theme; the double-init pattern is already filed at #1's `completion-only-guards`. Matrix: (A2, B1, C1) — singleton-by-convention without an ADR, code is correct, vision-aligned. Closes lightweight per template's verdict guidance. Trace: issues/07-provider-registration-inefficiency/traces/cold-boot-console.log Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…policy Live Playwright cold-boot trace shows 158 console lines in ~1.5s, with the heaviest offenders catalogued by source file. Single-line winner is `store/bootstrap/initializeStore.ts:30`'s `logStep` callback (82/158 = 52% of trace volume). ~50% of all lines are pure StrictMode duplication (owned by issue #1). Categorized inventory in §5 — A. KEEP / B. CONSOLIDATE / C. DELETE / D. duplication-fix-at-#1 / E. one-time-init / F. UI-load-batch. Matrix: (A3, B3, C2) confirmed from index. No logging-policy ADR exists. Action: draft_new_ADR (proposed ADR-009 sketch in §9). Theme: propose `logging-policy-missing` (N=1, expandable to runtime). Trace: issues/08-wasted-logs-audit/traces/cold-boot-console.log Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…+ 2 escalations Live Playwright cold-boot + Dungeon Defense chapter-1 load surfaced FIVE distinct anomalies behind the user's single-line claim: A. Virtual `· Chapter N` + imported `● Ch N: Real Title` coexist for same N — 17 duplicate-pair cases. Same drift as issue #20, higher concentration. B. Foreign-novel chapter titles in catalog: chapters 478-509 show Hangul titles `네크로맨서 학교의 소환천재-XXX화` (Necromancer-School novel) inside Dungeon Defense's dropdown. **Metadata cross-contamination.** C. Untranslated raw Korean titles `· Ch N: 던전 디펜스-NNN화` for chapters 285-477 (~190 entries) where localized `Chapter N` fallback should fire. D. The user's verbatim "Chapter 1 as title" reproduces on virtual entries — bare `· Chapter N` placeholder lacks novel prefix. E. No glossary panel visible in reader. `services/glossaryService.ts` exists (3-tier layered) but no UI surface in reader view. Matrix: (A3, B2, C2) confirmed. New theme proposal: `catalog-cross-contamination`. Compound action: A waits for #20; C+D fix_local; B+E escalate_to_human (need Aditya's root-cause input). Trace: issues/03-metadata-empty-and-glossary/traces/dungeon-defense-ch1-snapshot.yml Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Static investigation (live deferred due to translation cost). System IS model-aware via getAverageTranslationTime() — but the 2-sample threshold makes the model-specific path unreachable for fresh state, so every new-model user hits the provider/global fallback. User's "aggregation ruins the value" complaint maps exactly. Code paths: - services/apiMetricsService.ts:457-503 — fallback chain (model→provider→ global→default 30s); mean, not median - components/chapter/ChapterContent.tsx:259-286 — shows source indicator - components/chapter/TranslationStatusPanel.tsx:25-54 (RetranslationTimer) — does NOT show source indicator (inconsistency) Image-side reference (components/Illustration.tsx:213) uses median; should mirror for translation. Matrix: (A3, B3, C2) confirmed. Theme: jit-vs-precompute (precomputed aggregate vs JIT per-model). Action: fix_local 4-part: 1. Show source indicator in RetranslationTimer 2. Switch mean → median 3. Lower threshold 2 → 1 with confidence tag 4. "Estimating…" on source=default Total ~2 hr work. No ADR draft needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…6 SLO
Live in-page instrumentation (MutationObserver on h1 + monkey-patched
console.log) on a Ch1 → Ch2 navigation. Chapter is already-cached, IDB warm.
Timeline:
t=0 Next clicked
t=110 AutoTranslateMediator: cache hit detected (fast path)
t=574 H1 visually changes — **exceeds CORE-006 <500ms SLO by 15%**
t=897 TranslationRepo: URL lookup returns 0 (wasted ~330ms)
t=897 Fallback to stableId index begins
t=958 ✅ stableId fallback returns 3 translations
Defects:
1. Visible transition 574ms > 500ms (CORE-006 violation)
2. Serial fallback in TranslationRepository.getTranslationVersionsByStableId
wastes ~330ms (URL lookup ALWAYS fails for stableId-migrated data)
3. 9 console.log lines fire per chapter change (runtime side of issue #8)
Matrix: (A1*, B2, C2) confirmed from index. CORE-006 isn't aspirational —
ADR's `Implemented` flag verified suspect by this measurement.
Action: enforce_existing_ADR + fix_local
9.1 Race URL + stableId lookups (Promise.any) — closes the perf gap
9.2 Add e2e perf regression test pinning <500ms
9.3 Defer log cleanup until issue #8's ADR-009 lands
Themes: jit-vs-precompute (cache-hit known but not on critical path) +
completion-only-guards (no single-flight wrapper on the two-lookup race).
Trace: issues/09-chapter-change-perf-logging/traces/ch1-to-ch2-timeline.txt
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Live repro deferred; #19's prescribed Playwright (Shape B) covers the same generator. #12 is the preload subset of #19's broader root cause: `setCurrentChapter` at store/slices/chaptersSlice.ts:170-199 explicitly cancels in-flight translation on every nav, with no distinction between user-initiated and speculative-preload work. Matrix: (A1*, B2, C1) — FEAT-001 commits to "ensure a translation is available, prevent waiting"; code violates it. Aligned vision; drifted implementation. Action: wait (subsumed by #19 Phase 1). Closing gate: #19 regression test includes preload-specific case. Theme: ratifies proposed `nav-cancels-bg-work` to N=2 (#12 + #19). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tion
Static investigation (paid liveness tests deferred per user's gating note).
System is partially dynamic per FEAT-003:
✅ OpenRouter image models: dynamic via openrouterImageModelAdapter.ts,
fetched from openrouter.ai/api/v1/models, cached under IDB key
'openrouter-image-models-v2'.
❌ Gemini / Imagen / PiAPI: hardcoded in AVAILABLE_IMAGE_MODELS at
config/constants.ts:43-54. Date-stamped preview IDs (imagen-4.0-
*-preview-06-06) suggest staleness.
❌ PiAPI Flux models filed under "Gemini" key — categorization bug.
❌ No liveness tests for any provider catalogue.
Matrix (split):
OpenRouter: (A1, B1, C1) ✓
Gemini/Imagen/PiAPI: (A2, B2, C2)
Test coverage: (A3, B2, C2)
Action: compound
9.1 enforce_existing_ADR — verify zero openrouter/* in static list ✓ already true
9.2 fix_local — re-key PiAPI from "Gemini" to "PiAPI" (~30 min)
9.3 draft_new_ADR — ADR-010 "Liveness probes for external resources"
with gated paid tests + weekly cron
Theme proposal: `unverified-external-resource` (N=1, extensible).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… decision
Static investigation (live UI repro deferred — needs chapter with
fanTranslation populated, current IDB has Dungeon Defense which lacks
fan data). User's verbatim claim has TWO entangled asks:
Ask A: Toggle should cycle 3 sources (raw / fan / google), not 2.
Ask B: Selected text should be in-place marked (faint underline),
not duplicated in a "Selected: X" preamble.
Code path: components/chapter/ComparisonPortal.tsx
- showRawComparison: boolean (line 7-15) — locked to 2 modes
- "Selected: <text>" duplication at lines 42-48 — the user's complaint
- Body switches between rawExcerpt / fanExcerpt only (lines 91-107)
- No googleExcerpt in ComparisonChunk type — service doesn't exist
Matrix: (A3, B3, C3) confirmed — explicit vision contradiction
(comparison is fundamentally a multi-source feature; 2 sources defeats
the purpose).
Action: fix_local 3-part
9.1 In-place selection marker + strip preamble (1 hr)
9.2 Boolean → enum refactor (1 hr)
9.3 Google Translate service with per-chapter batch cache (3-6 hr,
blocked on user choice: free unofficial / paid Cloud API /
browser iframe)
Theme: jit-vs-precompute (subtle — "Selected:" duplication precomputes
state already JIT-visible in the user's selection).
Open question for Aditya: §11 Google Translate provider strategy.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reflects 2026-05-15 Playwright investigation sweep results for #3, #6, #7, #8, #9, #12, #13, #15. All 8 transition `not-investigated` → `investigated` with R/V/E/T/G columns filled; A (archaeology) deferred to a follow-up. Theme density updated: - jit-vs-precompute confirmed N=10 (~50% of issues) - completion-only-guards N=2 (#7 reclassified as non-instance after live trace; the StrictMode double-init it was filed against belongs to #1) - nav-cancels-bg-work ratified to N=2 (#12 + #19) - 3 new theme proposals: logging-policy-missing (#8), unverified-external- resource (#6), catalog-cross-contamination (#3) - silent-feedback-gaps retired (all instances FIXED) New "Tier ordering (2026-05-15)" section establishes the fix-direction sequence across 4 tiers: Tier 1 foundation: #20 → #1 → #19 (~10 hr, unblocks 6-8 adjacent issues) Tier 2 quick wins: #9, #13, #10 (~5 hr parallelizable) Tier 3 ADR + escalation-gated: #3 ×2, #15, #8 ADR-009, #6 ADR-010 Tier 4 paused on user repro: #2, #16 Strategic observation: jit-vs-precompute at 50% suggests CORE-008-derived-views-recomputed-not-stored is the missing principle. Recommend `enforce_existing_ADR` on CORE-006 first; reassess CORE-008 ratification after Tier 1 lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ME staleness identified Deep git-blame + JSONL audit on suspect files revealed THREE issues whose READMEs were stale by 5-10 days, all marked as pending fix work when the fixes had actually shipped on main: #19 nav-cancels-bg-work — FIXED 2026-05-05 in `72a2a80572` (CORE-012 ratified in `5f170b0`; regression test landed at tests/store/slices/setCurrentChapter-survives-nav.test.ts). README said: "investigated / Phase 0 spec / Implementation deferred" Actually: fix shipped 10 days ago. #20 chapter-number-drift — FIXED 2026-05-10 in `bef65dd534` (bug-write removed at translationService.ts:858-876; V5 repair migration wired into bootstrap; SETTINGS.CHAPTER_NUMBER_CORRECTED_V5 flag). README said: "root-caused" Actually: fix shipped same day. #12 background-preload-spinner — FIXED via #19 (shared root cause) README said: "superseded, waiting for #19 Phase 1" Actually: #19 Phase 1 already shipped. Updated all three READMEs with a fix-status block at the top + ⚠ marker on pre-fix content. Updated issues/README.md table rows. Revised Tier ordering: - Old Tier 1: #20 → #1 → #19 (~10 hr) [WRONG — based on stale READMEs] - New Tier 1: just #1 (~2-4 hr) [correct after archaeology] DEEPER GENERATOR FUNCTION identified: `stale-issue-readme`. Issue READMEs do not get auto-updated when fixes ship. The sessions that ship fixes are multi-feature and code-focused; the sessions that update READMEs are single-issue and bookkeeping-focused. The two skill sets rarely overlap in one session. Cost in this conversation: ~4 hr of investigation work targeting stale state. The user approved "ship #20 next" based on stale-data recommendation. The recommendation was a no-op. Fix-shapes (in issues/README.md "Deeper generator" section): 1. Pre-recommendation verification (cheapest, extend CLAUDE.md's "Verify before recommending from memory" rule to issue READMEs) 2. Fix-commit closes README (convention + CI hook) 3. Periodic staleness audit script Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User asked for proper RCA reading the actual conversations. This commit delivers it: ~400-line postmortem in docs/postmortem/ that quotes verbatim from the JSONL transcripts where available. Key verbatim quotes that anchor the synthesis: #19 (session 830d8ff9, 2026-05-05): L17 — user: "can you read docs/HANDOVER.md, focus on pending thread #3" L26 — user: "I would want it stored in the background so when I navigate back it will be ready waiting for me" L269 — user: "I don't want too much of discussion and filing of documentation. I think it's time to move to actually start implementing." L276 — user: "Just start implementing unless you really think you need my input. Let's start fixing stuff and I trust you we can always make commits and in worst case we can undo it right." L445 — fix commit `72a2a80` lands at 21:22Z L515 — user (21:37Z): "we are done with phase one. let's just go to phase two" L1196 — Claude reopens README next day, edits ADR link, does NOT touch Status #20 (session 830d8ff9, 2026-05-10): L2881 — user: "it is not about fix but root cause we need to figure out what happened and why" [OPPOSITE of #19's L269] L2904 — Claude: "Smoking gun confirmed." L2910 — Claude identifies translationService.ts:858-876 + 2025-09-08 origin L2943 — Claude: "JSONL archive only goes back to Dec 21 2025. The commits introducing the bug (Sept 8 + Nov 18 2025) are both before any transcript exists." L2957 — README written with Status: root-caused at 18:08:08Z L3053 — fix `bef65dd` pushed at 18:16:42Z (8 min 34 sec later) README Status never updated to FIXED in the 5 days since. Pre-archive bugs (#3 anomaly B, #6, #7, #9, #13, #15): only commit-message evidence available. Documented honestly in §4 with "evidence type: commit-msg only" — no speculation about agent reasoning we cannot see. Cross-cutting pattern (§5): "Status: investigated" is treated as a comma but written like a period. The state machine in issues/README.md defines investigated→fixed transition, but no actor's per-fix checklist owns the transition. The user's velocity preference (L269) and rigor preference (L2881) both produced the same staleness — so the user's preference is NOT the root cause; the missing per-fix bookkeeping step is. Recommendations (§6) ranked: 6.1 Pre-recommendation verification (cheapest) — extend CLAUDE.md memory rule 6.2 Fix-commit closes README (medium) — per-fix checklist update 6.3 Periodic staleness audit (heavy, band-aid) 6.4 Acknowledge archive gap in CLAUDE.md (one-liner) §7 explicitly classifies every claim in this RCA by evidence quality — "direct quote", "computed from timestamps", "inference from commit message", or "self-report". No claim is upgraded above its evidence basis. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ses 13-day pause Issue #2 sat at 'paused on user repro' since 2026-05-02 (13 days). Agent had Playwright access the entire time and could have run the obvious test. Live repro 2026-05-15: 1. Load Dungeon Defense Ch2 (already-translated, v3 claude-sonnet-4-0) 2. Hook window.fetch + console.log 3. Click English (baseline) → Fan → English 4. Observe: 0 LLM API calls. AutoTranslateMediator fires 'Translation already cached' on the back-toggle. Both dual-layer guards (mediator hasTranslation + handleTranslate pendingTranslations) hold as static analysis predicted. Verdict: cannot-reproduce. Static analysis was correct. Framework learning: 'paused-on-user-repro' is a one-way state with no follow-up trigger. Should auto-escalate to agent-driven repro after N days without user response. This is the practice that justifies the eventual meta-protocol amendment — not the other way around. The user steered: "before we start removing things and changing things, let's try to fix some of them and understand what the solution looks like, and then I think we can actually change the meta protocol" Following that order: this commit is the practice; protocol change waits for more practice. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…sed remount)
Bug: ReaderBody rendered <InlineCommentMarkers feedback={feedbackForChapter}>
without a key tied to translation. When setActiveTranslationVersion fired
updateChapter({ translationResult }), chapter.feedback reference was
preserved — so InlineCommentMarkers' useCallback(computePositions,
[feedback, contentRef]) kept the same callback identity, useEffect did NOT
re-fire, positions stayed pointing at OLD translation's coordinates, and
markers vanished on the next render trigger.
Static-analysis root-cause was identified at issues/16's README §5 with
0.88 confidence on 2026-05-04. The issue then sat at "triaged — needs §2
live repro before ready-for-fix" for 11 days because the investigator
self-blocked on IDB-state availability. 2026-05-15 audit revealed:
(a) the IDB state was available (Dungeon Defense Ch1 has 5 versions);
(b) the live repro wasn't strictly necessary — a unit test with mocked
InlineCommentMarkers could prove the re-mount via spy.
Fix: components/chapter/ReaderBody.tsx — key prop derived from
translationResult.id ?? .version ?? 'default'. Forces React to unmount old
+ mount new on translation switch. Fresh mount → fresh useState →
useEffect re-fires → positions recomputed against the new DOM.
Test: tests/components/chapter/ReaderBody.versionSwitchRemount.test.tsx —
mocks InlineCommentMarkers with a mountSpy. 4 cases:
✓ mounts once on initial render
✓ REMOUNTS when translationResult.id changes (key change) [BUG-CATCHER]
✓ does NOT remount when same translation reference (no spurious remount)
✓ falls back to .version when .id is absent [BUG-CATCHER]
Verified via git-stash of fix: 2 BUG-CATCHER tests FAIL on unfixed code
("expected 2 calls, got 1"), all 4 PASS with fix.
Practice → protocol: this is the second bug closed since the user steered
"let's try to fix some of them and understand what the solution looks
like, and then I think we can actually change the meta protocol." First
was #2 (cannot-reproduce, 13-day pause). The pattern that's emerging from
practice — both issues had `paused/triaged on user repro` status that
should have auto-escalated to agent-driven repro/test long ago.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…edged User asked: 'are you using an actual book to test this?' Honest answer: for #2 yes (real Dungeon Defense Ch2, instrumented network); for #16 no, the prior commit landed only a unit test that mocks InlineCommentMarkers. This commit attempts real-book verification of #16 and documents what worked vs what didn't: CONFIRMED in real book (Dungeon Defense Ch2, fix in place): - store.submitFeedback succeeded with real selection text - inline marker rendered correctly in DOM ('+' for thumbs-up) - findTextTop located 'Legendary Adventurer' in v3's translation - side panel showed the feedback comment NOT CONFIRMED: - programmatic store.setActiveTranslationVersion did not change state when called outside a React event handler (returned undefined, no error, but chapter.translationResult stayed at v3 across multiple attempts with both version-number and UUID args). This blocks the full pre/post-switch DOM observation cycle. - Therefore the user-visible end-to-end symptom (marker behavior on version switch in the running app) was not directly observed. WHAT THIS MEANS for the framework: - Unit test catches the mechanical fix (key prop → React remount) - Real-book confirms the marker-render-path works on initial mount - User-driven manual test is still the ground truth for the fix's effect on the reported symptom. Trace file documents the exact click sequence the user should run. The framework's §2 hard rule was right to insist on live repro. The practice today revealed that 'live repro' is a spectrum: - Static analysis (cheapest, often sufficient) - Unit test with mocks (proves mechanism) - Programmatic real-book (proves data path, may not exercise the full user-event chain) - Headed Playwright with real clicks (proves end-to-end) - User clicking (ground truth) Each level catches different bug classes. For this fix, mechanical test passes + real-book partial; user-clicking is the close. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ss criteria Motivating incident: #16 fix landed with overclaim 'FIXED' but only L2 (unit-mechanical) + partial L3 (programmatic data-path) actually achieved. The user asked 'are you using an actual book to test this' and exposed the gap. The ladder formalizes what 'verified' means as a forcing function in the §9a closing gate, not advice: L1 Static — bug exists in code (≥ 0.7 confidence) L2 Unit-mechanical — fix mechanism works (test FAILS pre-fix) L3 Programmatic data-path — exercises store/data flow, no UI clicks L4 Real-event chain — headed Playwright clicking real UI L5 User-driven manual — user confirms 👍/👎 from trace instructions Rules force agents to pin the level achieved. Critically: - L1 alone is `triaged`, never `fixed` - L2 alone is `fixed` ONLY for purely mechanical bugs with ≥0.9 L1 - L3+ required for UI/event/async bugs - If a level is blocked, say so explicitly — no pretending lower is OK Closing-gate format updated: §9a now requires explicit per-level checkboxes. This is the practice → protocol move the user requested: 'before we start removing things and changing things, let's try to fix some of them and understand what the solution looks like, and then I think we can actually change the meta protocol.' Two bugs fixed (#2 cannot-reproduce + #16 mechanical+partial), one overclaim caught, ladder derived from that practice. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two responsive sites in ChapterHeader.tsx had button {Library}. Replaced
text with inline SVG home icon, added aria-label for accessibility,
preserved title tooltip.
Verification ladder achieved (per §6a):
L1 static — confidence 1.0 (cosmetic, unambiguous user intent)
L2 unit-mechanical — 4 tests in ChapterHeader.test.tsx; 4/4 pass post-
fix, 4/4 fail pre-fix (git stash verified)
L4 real-event chain — Playwright clicked new aria-labelled button on
Dungeon Defense Ch2; navigated to library;
h1 transitioned reader → library page
L5 user-driven — deferred (cosmetic icon with sr label)
Trace: issues/10-library-to-home-icon/traces/l4-headed-playwright-2026-05-15.txt
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bug: TranslationRepository.getTranslationVersionsByStableId ran the URL- based lookup FIRST and the stableId-index lookup ONLY IF URL returned 0. Empirical trace (issues/09-.../traces/ch1-to-ch2-timeline.txt) showed: t=574ms h1 visible transition (>500ms CORE-006 SLO) t=630ms URL lookup begins t=897ms URL lookup returns 0 (~270ms wasted) t=897ms stableId-index fallback begins t=958ms stableId fallback returns 3 translations Fix: Promise.any race. Both paths fire in parallel; first non-empty wins. Inner promises throw on empty so the race progresses past them. If both empty/throw, return []. Also strips 7 console.log calls from the hot path (runtime side of issue #8's wasted-logs concern; the navigateToChapter critical path is the worst log-noise offender per #8 §5). Verification ladder: L1 (0.95) static — empirical trace confirms the bug shape L2 (6/6 pass post-fix, 1/6 fail pre-fix) — parallelism timing test in TranslationRepository.raceLookup.test.ts. Critical test: expect(urlStarted).toHaveBeenCalledTimes(1) expect(stableIdStarted).toHaveBeenCalledTimes(1) expect(elapsed).toBeLessThan(80) // serial would be ~120ms+ L3-L5 deferred (live re-measurement of chapter-change timing). The 5 non-critical tests pass on both pre-fix and post-fix code — they verify correctness of empty-handling, throw-handling, etc., which is unchanged by the race refactor. Only the timing/parallelism test distinguishes the two implementations. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…mating 4-part landed in one commit per issue #13 §9: 1. services/apiMetricsService.ts — extracted pure helpers median() and estimateTranslationTime() + new TranslationTimeEstimate interface with confidence: 'high' | 'low' | 'unknown'. Switched from arithmetic mean to median (robust to outlier translation stalls; matches Illustration.tsx pattern). Lowered model-match threshold from ≥2 → ≥1 samples (the 2-sample cliff produced misleading provider/global aggregates for first-use of any new model — the user's "aggregation ruins the value" complaint). 2. components/chapter/ChapterContent.tsx — when source==='default', shows "Estimating…" with sub-caption "(no past calls for this model yet)" instead of the misleading 30s default ETA. 3. components/chapter/TranslationStatusPanel.tsx (RetranslationTimer) — now shows source indicator like ChapterContent does (was missing, creating inconsistency between the two timer surfaces). Also shows "Estimating…" when source==='default'. 4. Confidence field plumbed through to ChapterContent which annotates "low confidence" when sampleCount < 3. Verification ladder: L1 (0.9) static — code-read identified threshold + mean issues L2 (11/11 pass post-fix, 11/11 fail pre-fix) — pure-helper tests in apiMetricsService.eta.test.ts. 4 cases on median(), 7 on estimateTranslationTime(). Critical assertion: median(10,10,100)===10 would have been mean===40 pre-fix. L3-L5 deferred (would require 5+ real translations across models). Existing tests still pass (ChapterContent.test.tsx: 14, TranslationStatusPanel.test.tsx: 2). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bug pre-fix: store/bootstrap/initializeStore.ts:483 guarded only on `isInitialized`, which flips to true ONLY after all phases complete. React.StrictMode mounts the bootstrap effect twice rapidly; both calls arrived while isInitialized===false, both passed the guard, both ran the full pipeline in parallel. Issue #8's cold-boot trace empirically confirmed every [Store:init] marker firing exactly 2×. Fix: module-scope `initializationPromise` shared by concurrent callers. Second + later callers `await` the first's promise and return. Pipeline runs once; second call logs new 'joined in-flight init' marker. On failure, the promise is cleared so a subsequent retry can run. Successful init keeps the promise resolved so the fast-path (`if (isInitialized) return`) holds for post-init re-calls. Also exports `__resetInitializationGuard()` for tests — TypeScript private isn't enforced at runtime, but exporting the reset makes the intent explicit. Verification ladder: L1 (0.95) static — issue #1 §5 + issue #8's empirical 158-line cold- boot trace with everything 2× L2 (16/16 post-fix, 16/16 fail pre-fix) — 3 new tests in the 'issue #1 — single-flight in-flight guard' suite plus existing 13 tests that depend on the guard reset between cases (so they fail pre-fix because the export doesn't exist). L4 — real-page cold-boot trace (issues/01-.../traces/post-fix-l4- summary.txt) shows: initializeStore – begin: 2× → 1× joined in-flight init: new, 1× Total log lines: 158 → 56 (65% reduction) This is the highest-leverage fix in the issue universe — it also reduces issue #8's wasted-logs problem by 65% as a side-effect (was predicted at 50% in #8 §5; actual reduction is higher because duplicated init pulls duplicated DataRepair + migration logs too). Deferred: defects 2-6 in #1's investigation (telemetry, deep-link import, registry remap, scope validation). The single-flight guard addresses defect 1 only; the other 5 are independent and need their own focused work. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… phases) Re-scope of #15 after user pushback (2026-05-15): the original "third source button" framing was wrong. The actual desired UX is the sutta-studio reader pattern (PaliWord/EnglishWord aligned pairs with hover tooltips and sense-cycling) extended to novels. The #3 anomaly E (missing reader-side glossary UI) is the same primitive at glossary granularity — both unify under one abstraction. Three phases shipped, 35 tests across all three: Phase 1 — services/wordAlignment.ts (10 tests): Structured-output LLM call producing source↔target word pairs with char offsets. Validates LLM offsets against actual substring (drops hallucinated pairs). Cached per (chapterId, translationVersionId). Cost ~$0.005 per chapter, computed once per translation version. Phase 2 — services/perWordTranslation.ts (16 tests): Per-source-word lookup with provider abstraction. Three providers: - glossary (in-memory match against active novel's GlossaryEntry[]) - DeepL (Free tier with :fx-suffix key, or Pro) - Google Cloud Translate All lookups cached in-memory by (provider, sourceLang, targetLang, sourceWord). Returns Sense[] in provider order. Phase 3 — components/chapter/InterleavedReader.tsx (9 tests): Renders aligned WordPair tokens with source above target. Hover → fetches per-word lookups (Phase 2) and shows tooltip with all senses. Click → cycles through senses. Empty alignment shows "Compute alignment" button → triggers Phase 1 via parent. What this resolves: #15 — comparison-cycle-modes: the boolean showRawComparison toggle is replaced by the aligned interleaved view with multi-source senses cycling per-word. Per the user's clarified intent: "we need to have aligned interleave text so that it's easy to cycle through and actually see the raw translation of individual words. It's not about translating the whole thing, but in translating individual words." #3 anomaly E — glossary UI: the missing reader surface IS the InterleavedReader. Glossary entries appear as {provider: 'glossary'} senses in the hover tooltip. The earlier "translator- time only" framing was a false dichotomy I introduced; user corrected it. Verification ladder: L1 (1.0) static — re-read sutta-studio code; pattern fits novels via same data model. WordAlignment + Sense + WordPair types match PaliWord + Sense + WordSegment types. L2 (35/35 post-fix; FAIL pre-fix because modules don't exist): pure-helper tests + service tests + RTL component tests cover empty-input, validation, caching, multi-provider order, hover-fetch, sense-cycle, cycle-wrap, single-sense no-op. L3-L5 deferred — wire-up to ReaderBody + settings flag + IDB persistence not yet built. ~2-4 hr UI work to make user-visible. Wire-up steps documented in issues/15's README. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ag + IDB persistence) Completes the #15 wire-up. Users can now opt in via: Settings → Display → "Interleaved word-aligned reader (experimental)" Wire-up adds: - types.ts: * AppSettings.enableInterleavedView (default false) * AppSettings.deeplApiKey, googleTranslateApiKey (per-word lookup) * Chapter.wordAlignment field (cached per (chapterId, translationVersionId)) - components/settings/DisplayPanel.tsx: * Checkbox to toggle enableInterleavedView - components/chapter/ReaderBody.tsx: * When flag is on AND viewMode==='english' AND translation exists, renders <InterleavedReader> instead of <ChapterContent> * handleRequestAlignment: calls services/wordAlignment.alignWords(), persists result via store.updateChapter(chapterId, { wordAlignment }) * isComputingAlignment local state for the in-flight indicator Behavior: - Default off — opt-in only. - First time on a chapter: shows "Compute word alignment" button → triggers Phase 1 LLM call (~$0.005, ~3s) → caches forever. - Subsequent: renders aligned source↔target word pairs. - Hover a pair → fetches per-word lookups (Phase 2 service) → tooltip with glossary + DeepL + Google senses (whichever keys are set). - Click a pair → cycles through senses. - Without DeepL/Google API keys: glossary still works, translation's own rendering shown as primary sense. Glossary integration (resolves #3 anomaly E by absorption): glossary entries from settings.glossary are passed to InterleavedReader and surface as { provider: 'glossary' } senses in the per-word lookup tooltip. The "missing reader UI for glossary" gap closes. Verification: L1+L2: 35 #15 tests + 4 #16 tests + 6 #9 tests pass on the wire-up build (45/45 across the touched files). Existing #16 test suite still passes — the new conditional render branch doesn't break the version-switch remount path because InterleavedReader is mounted under its own key. L4: dev server hot-reload picks up the changes; user can toggle the flag in Settings and watch the InterleavedReader render against a real chapter. L5: deferred — user-driven test of (a) toggling the flag, (b) computing alignment on a real chapter (cost ~$0.005), (c) hovering a word and seeing glossary/DeepL/Google senses. Also fixes a TS2554 in TranslationRepository.raceLookup.test.ts — constructor signature requires deps. Stubbed deps for the test; runtime tests still pass because the methods we override are private (TS-only) and JS reflection bypasses that. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…l ladder cleared
L5 user-driven test on Dungeon Defense Ch 2 surfaced 3 integration bugs
that L2 mocked tests missed. Each fix preserves the L2 contract.
Bug A — LLM offset hallucination (services/wordAlignment.ts validateAlignment)
Symptom: real LLM produced correct source/target words but wrong char
offsets in CJK + reordered languages; strict-equality validation
dropped all pairs (alignment returned 0/3).
Fix: rewrote validateAlignment to RECOMPUTE offsets via indexOf rather
than trust LLM's offsets. Source-order monotonicity preserved via
sourceCursor; targetCursor allows ±50 char backtrack to handle
small reorderings.
Test update: "keeps dropped-in-translation pairs" test reordered to
reflect realistic source-order requirement (drop-in particle FIRST,
then consuming pair). Other 9 tests unchanged.
Bug B — Glossary cache blocked live additions (services/perWordTranslation.ts)
Symptom: hovering a pair with empty glossary cached []. Later
updateSettings({ glossary: [...] }) didn't surface — the cache
short-circuited the new lookup.
Fix: do NOT cache glossary results. Lookup is in-memory list filter,
essentially free. Network providers (DeepL, Google) still cache.
Test update: "caches glossary lookups" test inverted to assert NO cache
(live changes surface immediately).
Bug C — Component-level fetched flag (components/chapter/InterleavedReader.tsx)
Symptom: even with cache fix, the WordPairToken's `if (fetched) return`
early-exit prevented re-running lookupWord when glossary prop
changed after first hover. State stayed at the empty-glossary
result.
Fix: dropped `fetched` flag. Hover always fires; perWordTranslation's
service-level cache handles dedup for network providers.
Test update: "triggers lookupWord on first mouseenter, not on subsequent
re-hovers" → "triggers lookupWord on every mouseenter (cache lives
in perWordTranslation, not the component)". Comment in code
explains why.
L5 verification (issues/15/traces/l5-user-driven-test-2026-05-16.txt):
✓ Settings flag toggles ReaderBody render path
✓ Compute alignment LLM call: 3 valid pairs in 1.5s, ~$0.005
✓ Real Playwright browser_hover triggered React onMouseEnter
(synthetic dispatchEvent does NOT — mouseenter doesn't bubble)
✓ Tooltip showed all 3 senses with provider provenance:
[cache] endlessly / [glossary] extensively / [glossary] at length
✓ Click cycle: 0→1→2→0 (wraps correctly)
Screenshot: issues/15/traces/issue-15-l5-interleaved-reader-tooltip-2026-05-16.png
35/35 tests pass on the updated code.
The L5 test caught 3 bugs L2 missed. This is exactly the case the
verification ladder (§6a) was designed for: L2's mocked tests cover the
mechanism but not the integration. Each ladder rung exposes a different
class of bug.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
anantham
added a commit
that referenced
this pull request
May 16, 2026
Synthesized from JSONL after the model that did the work hit "Prompt is too long" trying to act on the final "yep go ahead" and /compact ran. Replaces 2026-05-14 handover (whose three Continue-Immediately threads — DN22 pilot, persistent segmentCache, GROUNDING Phase 4 — all merged 2026-05-15 via PRs #55/#56/#57). This session's work captured here: - 9 issues investigated + closed under the new §6a Verification Ladder - §6a Verification Ladder protocol itself (L1-L5 with hard gate) - InterleavedReader feature (issue #15 + #3 anomaly E) with L5 verification - 22 commits on feat/opus-issues-investigation, PR #60 opened (MERGEABLE) - Verbatim user-quote section preserved (JSONL is local-only) Immediate pending task: CI test gate PR (user authorized "yep go ahead" but model could not respond before compaction). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4 tasks
Owner
Author
|
@codex review |
|
To use Codex here, create a Codex account and connect to github. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Multi-day investigation pass (2026-05-15 / 2026-05-16) closing 9 issues, drafting the §6a verification ladder protocol, and shipping the InterleavedReader feature (issue #15) with L5 user-driven confirmation.
Bugs closed (verification levels per §6a)
Plus stale-README corrections on #12, #19, #20 (all already FIXED on main but READMEs were lagging by 5-10 days — caught via JSONL archaeology pass).
76 new tests in this branch. All 1487 repo tests pass (16 skipped, 0 fails).
§6a verification ladder (
c1ee1a5)Added to
issues/_template/README.md. Five levels with explicit pass criteria:#15 cleared all 5 levels. The L5 step caught 3 wire-up bugs L2 couldn't see (LLM offset hallucination, glossary cache invalidation, React event semantics).
Architecture additions
services/wordAlignment.ts— LLM-driven source↔target word alignment withindexOf-recompute validation (LLM hallucinates char offsets)services/perWordTranslation.ts— DeepL + Google Cloud Translate + glossary lookup; glossary not cached (live changes surface immediately)components/chapter/InterleavedReader.tsx— sutta-studio PaliWord/EnglishWord pattern extended to novelsenableInterleavedView,chapter.wordAlignmentfield, conditional render inReaderBody.tsxMeta-finding (
docs/postmortem/2026-05-15-issue-rca-with-jsonl-quotes.md)JSONL conversation archaeology revealed the "stale-issue-README" pattern: 3 issues (#12, #19, #20) were already FIXED on main but their READMEs asserted pre-fix state. The verification ladder + the convention "fix commits update issue Status block" address this directly.
Test plan
issues/15-comparison-cycle-modes/traces/)localhost:5183: enable Settings → Display → "Interleaved word-aligned reader (experimental)", load a chapter with a translation, click "Compute word alignment", hover an aligned wordnpm run test:e2e) — not run on this branch (heavy; would benefit from CI gate)Repo health observations (drive-by)
.github/workflows/codex-review.ymlexists. Addingvitest runon PR would prevent regressions.tests/e2e/.🤖 Generated with Claude Code