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

id, title, status, assignee, created_date, updated_date, labels, milestone, dependencies, references, documentation, parent_task_id, priority

id	title	status	assignee	created_date	updated_date	labels	milestone	dependencies	references	documentation	parent_task_id	priority
TASK-87.3	Immersion tracking verification: make SQLite-backed persistence tests visible and reproducible	Done	Kyle Yasuda	2026-03-06 03:19	2026-03-06 08:20	tests immersion-tracking	m-0		src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker-service.ts package.json	docs/reports/2026-02-22-task-100-dead-code-report.md	TASK-87	medium

Description

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.

Acceptance Criteria

• #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.

Implementation Plan

Implementation plan recorded in docs/plans/2026-03-06-immersion-sqlite-verification.md.

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.

Implementation Notes

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.

Final Summary

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.