SubMiner/docs/plans/2026-03-14-immersion-occurrence-tracking.md

Immersion Occurrence Tracking Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add normalized counted occurrence tracking for immersion words and kanji so stats can map each item back to anime, episode, timestamp, and subtitle line context.

Architecture: Introduce imm_subtitle_lines plus counted bridge tables from lines to canonical imm_words and imm_kanji rows. Extend the subtitle write path to persist one line row per subtitle event, retain aggregate lexeme tables, and expose reverse-mapping queries without duplicating repeated token text in storage.

Tech Stack: TypeScript, Bun, libsql SQLite, existing immersion tracker storage/query/service modules

---

Task 1: Lock schema and migration shape down with failing tests

Files:

• Modify: src/core/services/immersion-tracker/storage-session.test.ts
• Modify: src/core/services/immersion-tracker/storage.ts
• Modify: src/core/services/immersion-tracker/types.ts

Steps:

1. Add a red test asserting ensureSchema() creates imm_subtitle_lines, imm_word_line_occurrences, and imm_kanji_line_occurrences, plus additive migration support from the previous schema version.
2. Run bun test src/core/services/immersion-tracker/storage-session.test.ts and confirm failure.
3. Implement the minimal schema/version/index changes.
4. Re-run the targeted test and confirm green.

Task 2: Lock counted subtitle-line persistence down with failing tests

Files:

• Modify: src/core/services/immersion-tracker-service.test.ts
• Modify: src/core/services/immersion-tracker-service.ts
• Modify: src/core/services/immersion-tracker/storage.ts

Steps:

1. Add a red service test that records a subtitle line with repeated allowed words and repeated kanji, then asserts one line row plus counted bridge rows are written.
2. Run bun test src/core/services/immersion-tracker-service.test.ts and confirm failure.
3. Implement the minimal subtitle-line insert and counted occurrence write path.
4. Re-run the targeted test and confirm green.

Task 3: Add reverse-mapping query tests first

Files:

• Modify: src/core/services/immersion-tracker/__tests__/query.test.ts
• Modify: src/core/services/immersion-tracker/query.ts
• Modify: src/core/services/immersion-tracker/types.ts

Steps:

1. Add red query tests for word -> lines and kanji -> lines mappings, including anime/video/session/timestamp/text context and per-line occurrence_count.
2. Run bun test src/core/services/immersion-tracker/__tests__/query.test.ts and confirm failure.
3. Implement the minimal query functions/types.
4. Re-run the targeted test and confirm green.

Task 4: Expose the new query surface through the tracker service

Files:

• Modify: src/core/services/immersion-tracker-service.ts
• Modify: any narrow API/service consumer files only if needed

Steps:

1. Add the service methods needed to consume the new reverse-mapping queries.
2. Keep the change narrow; do not widen unrelated UI/API contracts unless a current consumer needs them.
3. Re-run the focused affected tests.

Task 5: Verify with the maintained immersion lane

Files:

• Modify: backlog/tasks/task-171 - Add-normalized-immersion-word-and-kanji-occurrence-tracking.md

Steps:

1. Run the focused SQLite immersion tests first.
2. Escalate to broader verification only if touched files cross into API/runtime boundaries.
3. Record exact commands and results in the backlog task notes/final summary.