test: add sqlite immersion verification lane

.github/workflows/ci.yml

@@ -20,6 +20,11 @@ jobs:
         with:
           bun-version: 1.3.5
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
+
       - name: Cache dependencies
         uses: actions/cache@v4
         with:
@@ -54,6 +59,9 @@ jobs:
       - name: Build (bundle)
         run: bun run build
 
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
       - name: Dist smoke suite
         run: bun run test:smoke:dist
 

.github/workflows/release.yml

@@ -26,6 +26,11 @@ jobs:
         with:
           bun-version: 1.3.5
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.12.0
+
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
@@ -59,6 +64,9 @@ jobs:
       - name: Build (bundle)
         run: bun run build
 
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
       - name: Dist smoke suite
         run: bun run test:smoke:dist
 

README.md

@@ -98,8 +98,12 @@ For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.m
 
 ## Verification
 
+- Run `bun run test` for the default Bun source suite.
+- Run `bun run test:immersion:sqlite` to compile `dist/**` and execute the SQLite-backed immersion tracker persistence tests under Node with `node:sqlite` support; on Node 22 this lane enables that with `--experimental-sqlite`.
+- If you only run the Bun source tests, the SQLite-backed immersion tracker cases may be skipped when `node:sqlite` is unavailable; those files now print an explicit warning telling you to use the dedicated SQLite lane for real DB coverage.
 - Run `bun run test:subtitle` to verify subtitle sync coverage for the maintained `alass`/`ffsubsync` test surface.
-- That lane reuses `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`, which are also included in the broader `bun run test:core` suite.
+- The SQLite lane covers persistence/finalization behavior beyond the seam tests, including session finalization, telemetry writes, and storage-session schema/write paths.
+- The subtitle lane reuses `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`, which are also included in the broader `bun run test:core` suite.
 
 ## Acknowledgments
 

backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md

@@ -3,10 +3,11 @@ id: TASK-87.3
 title: >-
   Immersion tracking verification: make SQLite-backed persistence tests visible
   and reproducible
-status: To Do
-assignee: []
+status: Done
+assignee:
+  - Kyle Yasuda
 created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 03:21'
+updated_date: '2026-03-06 08:20'
 labels:
   - tests
   - immersion-tracking
@@ -26,27 +27,49 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
-
 The immersion tracker is persistence-heavy, but its SQLite-backed tests are conditionally skipped in the standard Bun run when node:sqlite support is unavailable. That creates a blind spot around session finalization, telemetry persistence, and retention behavior. This task should establish a reliable automated verification path for the database-backed cases and make the prerequisite/runtime behavior explicit to contributors and CI.
-
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
-
 <!-- AC:BEGIN -->
-
-- [ ] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute.
-- [ ] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result.
-- [ ] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on.
-- [ ] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone.
+- [x] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute.
+- [x] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result.
+- [x] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on.
+- [x] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone.
 <!-- AC:END -->
 
 ## Implementation Plan
 
 <!-- SECTION:PLAN:BEGIN -->
+Implementation plan recorded in `docs/plans/2026-03-06-immersion-sqlite-verification.md`.
 
-1. Confirm which SQLite-backed immersion tests are currently skipped and why in the standard Bun environment.
-2. Establish a reproducible command or lane for the DB-backed cases, or make the unsupported-runtime limitation explicit and actionable.
-3. Document prerequisites and expected behavior for contributors and CI.
-4. Verify at least one persistence/finalization path beyond the seam tests is exercised by the new lane.
+1. Update `src/core/services/immersion-tracker-service.test.ts` and `src/core/services/immersion-tracker/storage-session.test.ts` so unsupported `node:sqlite` runtimes emit an explicit skip reason instead of a silent top-level skip alias.
+2. Add a dedicated `package.json` SQLite verification lane that runs both immersion persistence suites together under a runtime with `node:sqlite` support, likely via built `dist/**` tests executed by Node.
+3. Wire that lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` so automated verification includes a real DB-backed persistence/finalization check.
+4. Document the new command, prerequisites, and coverage in `README.md`, including the distinction between Bun's default lane and the reproducible SQLite lane.
+5. Validate the final lane by running the dedicated command and confirming it exercises persistence/finalization behavior beyond the seam-only tests.
+
+Execution adjustment: the reproducible lane uses `node --experimental-sqlite --test ...` because Node 22 exposes `node:sqlite` behind the experimental flag. Running that lane also exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`, so the final implementation includes a small SQL placeholder fix required for the new cross-runtime verification path.
 <!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Confirmed Bun 1.3.5 lacks `node:test` `t.skip()` support, so explicit unsupported-runtime messaging is surfaced with file-level warnings while the SQLite-backed tests remain conditionally skipped.
+
+Added `test:immersion:sqlite:src`, `test:immersion:sqlite:dist`, and `test:immersion:sqlite` scripts; the source lane now prints explicit warnings when `node:sqlite` is unavailable, and the dist lane runs both SQLite-backed immersion suites under Node with `--experimental-sqlite`.
+
+Wired the dist SQLite lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` after the bundle build, with explicit `actions/setup-node@v4` provisioning for Node 22.12.0.
+
+Fixed SQL prepared-statement placeholder counts in `src/core/services/immersion-tracker/storage.ts`, which the new Node-backed SQLite lane surfaced immediately.
+
+Verification: `bun run test:immersion:sqlite:src` -> pass with explicit unsupported-runtime warnings and 10 skips under Bun 1.3.5; `bun run test:immersion:sqlite` -> pass with 14/14 tests under Node 22.12.0 + `--experimental-sqlite`.
+<!-- SECTION:NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Added an explicit SQLite-backed immersion verification lane and documented it so persistence-heavy coverage is no longer hidden behind Bun-only skips. `package.json` now exposes source and dist SQLite scripts, the source test files print actionable warnings when `node:sqlite` is unavailable, and `README.md` explains the dedicated contributor command plus its Node 22 `--experimental-sqlite` prerequisite.
+
+Automated verification now includes the new dist lane in both `.github/workflows/ci.yml` and `.github/workflows/release.yml` after build output is available. While wiring the reproducible Node lane, it exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`; fixing those placeholders makes the SQLite-backed persistence/finalization tests pass cross-runtime, covering session finalization, telemetry persistence, and storage-session write paths.
+<!-- SECTION:FINAL_SUMMARY:END -->

docs/plans/2026-03-06-immersion-sqlite-verification.md

@@ -0,0 +1,155 @@
+# Immersion SQLite Verification Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the SQLite-backed immersion tracking persistence tests visible in the repo's verification surface and reproducible through at least one documented automated command.
+
+**Architecture:** Keep the existing Bun fast lane intact for routine local verification, but add an explicit SQLite verification lane that runs the database-backed immersion tests under a runtime with `node:sqlite` support. Surface unsupported-runtime behavior clearly in the source tests and contributor docs so skipped or omitted coverage is no longer mistaken for a fully green persistence lane.
+
+**Tech Stack:** TypeScript, Bun scripts in `package.json`, Node's built-in `node:test` and `node:sqlite`, GitHub Actions workflows, Markdown docs in `README.md`.
+
+---
+
+### Task 1: Audit and expose the SQLite-backed immersion test surface
+
+**Files:**
+
+- Modify: `src/core/services/immersion-tracker-service.test.ts`
+- Modify: `src/core/services/immersion-tracker/storage-session.test.ts`
+- Reference: `src/main/runtime/registry.test.ts`
+
+**Step 1: Write the failing test**
+
+Refactor the SQLite-gated immersion tests so missing `node:sqlite` support is reported with an explicit skip reason instead of a silent top-level `test.skip` alias.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts`
+Expected: the current output shows generic skips or hides the storage-session suite from normal scripted verification, which is too opaque for contributors.
+
+**Step 3: Write minimal implementation**
+
+Mirror the `src/main/runtime/registry.test.ts` pattern: add a helper that either loads `DatabaseSync` or skips with a message like `requires node:sqlite support in this runtime`, then wrap each SQLite-backed test through that helper.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts`
+Expected: PASS, with explicit skip messages in unsupported runtimes.
+
+### Task 2: Add a reproducible SQLite verification command
+
+**Files:**
+
+- Modify: `package.json`
+- Reference: `src/core/services/immersion-tracker-service.test.ts`
+- Reference: `src/core/services/immersion-tracker/storage-session.test.ts`
+
+**Step 1: Write the failing test**
+
+Add a dedicated script contract for the SQLite-backed immersion verification lane so both persistence-heavy suites are intentionally grouped and runnable together.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test:immersion:sqlite`
+Expected: FAIL because no such reproducible lane exists yet.
+
+**Step 3: Write minimal implementation**
+
+Update `package.json` with explicit scripts for the SQLite lane. Prefer a command shape that actually executes the built JS tests under Node with `node:sqlite` support, for example:
+
+- `test:immersion:sqlite:dist`: `node --test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js`
+- `test:immersion:sqlite`: `bun run build && bun run test:immersion:sqlite:dist`
+
+If build cost or runtime behavior requires a small adjustment, keep the core contract the same: one documented command must run both SQLite-backed immersion suites end-to-end.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test:immersion:sqlite`
+Expected: PASS in a Node runtime with `node:sqlite`, executing both persistence suites without Bun-only skips.
+
+### Task 3: Wire the SQLite lane into automated verification
+
+**Files:**
+
+- Modify: `.github/workflows/ci.yml`
+- Modify: `.github/workflows/release.yml`
+- Reference: `package.json`
+
+**Step 1: Write the failing test**
+
+Add the new SQLite immersion lane to the repo's automated verification so contributors and CI can rely on a real persistence check rather than the Bun fast lane alone.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test:immersion:sqlite`
+Expected: local command may pass, but CI/release workflows still omit the lane entirely.
+
+**Step 3: Write minimal implementation**
+
+Update both workflows to provision a Node version with `node:sqlite` support before the SQLite lane runs, then execute `bun run test:immersion:sqlite` in the quality gate after the bundle build produces `dist/**` test files.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test:immersion:sqlite`
+Expected: PASS locally, and workflow definitions clearly show the SQLite lane as part of automated verification.
+
+### Task 4: Document contributor-facing prerequisites and commands
+
+**Files:**
+
+- Modify: `README.md`
+- Reference: `package.json`
+- Reference: `.github/workflows/ci.yml`
+
+**Step 1: Write the failing test**
+
+Extend the verification docs so contributors can discover the SQLite lane, know why the Bun source lane may skip those cases, and understand which command reproduces the persistence coverage.
+
+**Step 2: Run test to verify it fails**
+
+Run: `grep -n "test:immersion:sqlite" README.md`
+Expected: FAIL because the dedicated immersion SQLite lane is undocumented.
+
+**Step 3: Write minimal implementation**
+
+Update `README.md` to document:
+
+- the Bun fast/default lane versus the SQLite persistence lane
+- the `node:sqlite` prerequisite for the reproducible command
+- that the dedicated lane covers session persistence/finalization behavior beyond seam tests
+
+**Step 4: Run test to verify it passes**
+
+Run: `grep -n "test:immersion:sqlite" README.md && grep -n "node:sqlite" README.md`
+Expected: PASS, with clear contributor guidance.
+
+### Task 5: Verify persistence coverage end-to-end
+
+**Files:**
+
+- Test: `src/core/services/immersion-tracker-service.test.ts`
+- Test: `src/core/services/immersion-tracker/storage-session.test.ts`
+- Reference: `README.md`
+- Reference: `package.json`
+
+**Step 1: Write the failing test**
+
+Prove the final lane exercises real DB-backed persistence/finalization paths, not just the seam tests.
+
+**Step 2: Run test to verify it fails**
+
+Run: `bun run test:immersion:sqlite`
+Expected: before implementation, the command does not exist or does not cover both SQLite-backed suites.
+
+**Step 3: Write minimal implementation**
+
+Keep the dedicated lane pointed at both existing SQLite-backed test files so it covers representative finalization and persistence behavior such as:
+
+- `destroy finalizes active session and persists final telemetry`
+- `start/finalize session updates ended_at and status`
+- `executeQueuedWrite inserts event and telemetry rows`
+
+**Step 4: Run test to verify it passes**
+
+Run: `bun run test:immersion:sqlite`
+Expected: PASS, with those DB-backed persistence/finalization cases executing successfully under Node.

package.json

@@ -38,7 +38,10 @@
     "build:appimage": "bun run build && electron-builder --linux AppImage",
     "build:mac": "bun run build && electron-builder --mac dmg zip",
     "build:mac:unsigned": "bun run build && env -u APPLE_ID -u APPLE_APP_SPECIFIC_PASSWORD -u APPLE_TEAM_ID -u CSC_LINK -u CSC_KEY_PASSWORD CSC_IDENTITY_AUTO_DISCOVERY=false electron-builder --mac dmg zip",
-    "build:mac:zip": "bun run build && electron-builder --mac zip"
+    "build:mac:zip": "bun run build && electron-builder --mac zip",
+    "test:immersion:sqlite:src": "bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts",
+    "test:immersion:sqlite:dist": "node --experimental-sqlite --test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js",
+    "test:immersion:sqlite": "bun run tsc && bun run test:immersion:sqlite:dist"
   },
   "keywords": [
     "anki",

src/core/services/immersion-tracker-service.test.ts

@@ -27,6 +27,12 @@ const DatabaseSync: DatabaseSyncCtor | null = (() => {
 })();
 const testIfSqlite = DatabaseSync ? test : test.skip;
 
+if (!DatabaseSync) {
+  console.warn(
+    'Skipping SQLite-backed immersion tracker persistence tests in this runtime; run `bun run test:immersion:sqlite` for real DB coverage.',
+  );
+}
+
 let trackerCtor: ImmersionTrackerServiceCtor | null = null;
 
 async function loadTrackerCtor(): Promise<ImmersionTrackerServiceCtor> {

src/core/services/immersion-tracker/storage-session.test.ts

@@ -23,6 +23,12 @@ const DatabaseSync: DatabaseSyncCtor | null = (() => {
 })();
 const testIfSqlite = DatabaseSync ? test : test.skip;
 
+if (!DatabaseSync) {
+  console.warn(
+    'Skipping SQLite-backed immersion tracker storage/session tests in this runtime; run `bun run test:immersion:sqlite` for real DB coverage.',
+  );
+}
+
 function makeDbPath(): string {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-imm-storage-session-'));
   return path.join(dir, 'immersion.sqlite');

src/core/services/immersion-tracker/storage.ts

@@ -315,7 +315,7 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar
         lookup_hits, pause_count, pause_ms, seek_forward_count,
         seek_backward_count, media_buffer_events, CREATED_DATE, LAST_UPDATE_DATE
       ) VALUES (
-        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
       )
     `),
     eventInsertStmt: db.prepare(`
@@ -323,7 +323,7 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar
         session_id, ts_ms, event_type, line_index, segment_start_ms, segment_end_ms,
         words_delta, cards_delta, payload_json, CREATED_DATE, LAST_UPDATE_DATE
       ) VALUES (
-        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+        ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
       )
     `),
     wordUpsertStmt: db.prepare(`