SubMiner/backlog/tasks/task-179 - Tune-immersion-tracker-SQLite-pragmas-and-maintenance-defaults.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, documentation, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	documentation	priority	ordinal
TASK-179	Tune immersion tracker SQLite pragmas and maintenance defaults	Done	codex	2026-03-17 15:15	2026-03-18 05:28	sqlite immersion-tracking performance		/Users/sudacode/projects/japanese/SubMiner/docs/plans/2026-03-17-sqlite-tuning.md	medium	111500

Description

Apply low-risk SQLite tuning improvements for the immersion tracker: add modern recommended maintenance/tuning pragmas where appropriate, cover them with regression tests, and update user-facing docs to reflect the actual tuning policy. Scope limited to low-risk local-DB changes already discussed: keep WAL + synchronous=NORMAL, add optimize path, consider WAL growth control, and document workload-dependent knobs left at defaults.

Acceptance Criteria

• #1 Immersion tracker applies the agreed low-risk SQLite tuning changes without regressing current behavior
• #2 Regression tests cover the new pragma/maintenance behavior
• #3 Immersion tracking docs describe the tuning policy and notable defaults left unchanged

Implementation Plan

1. Add regression coverage for connection pragmas and verify the new WAL growth cap fails before implementation.
2. Add regression coverage for maintenance-time PRAGMA optimize and verify the test fails before implementation.
3. Implement the minimal SQLite tuning changes.
4. Update immersion-tracking docs for the new tuning policy.
5. Run targeted SQLite verification lanes and record results.

Implementation Notes

Verification: bun test src/core/services/immersion-tracker/storage-session.test.ts src/core/services/immersion-tracker/maintenance.test.ts passed (15 tests).

Verification: bun run test:immersion:sqlite:src passed (37 tests).

Verification: bun run typecheck, bun run docs:test, bun run docs:build, bun run test:fast, bun run test:env, and bun run build all passed.

Final Summary

Added low-risk SQLite tuning improvements for the immersion tracker: journal_size_limit now bounds WAL growth, periodic maintenance runs PRAGMA optimize, regression tests cover both behaviors, and the immersion-tracking docs explain the maintained pragmas plus workload-dependent defaults left unchanged.