[maxmad64bis]

⚠️ base-red inherited: #12732

Summary

A long-running server never closes its DB, so the only thing reclaiming the WAL file is the periodic wal_checkpoint(TRUNCATE) — and until now that checkpoint never actually looked at its own result. checkpointDb ignored the pragma return and always reported success, so a checkpoint that hit a busy database silently did nothing and the next try came 6 hours later. It's the kind of bug you only notice when the WAL file is suddenly bigger than the database itself.

This moves the whole WAL lifecycle out of core.ts into src/lib/db/walMaintenance.ts. The new module reads the checkpoint result row: a busy checkpoint now warns with its streak (... still busy (streak 3)) and schedules one lightweight PASSIVE retry a minute later (which moves pages without waiting on writers; shrinking stays the next TRUNCATE tick's job). Closing-time checkpoints no longer print success on builds that never had a database file. core.ts just calls in — about 50 lines lighter, no signature changes for operators.

The busy totals also surface in the authenticated monitoring health payload (walMaintenance key: ticks, current streak, lifetime busy count, last busy/ok timestamps), so an operator watching contention over time doesn't have to grep logs. Deliberately no persisted counter: the streak lives in memory and resets on stop.

Related Issues

• Related to 🔴 Release branch not green: release/v3.8.51 #12732 (base-red tracking — this PR inherits the red base, adds no new failures)

Validation

• Change type: DB
• Focused tests and category gates from the golden path
• npm run lint
• Reconciled with the current active release base; focused checks rerun afterward
• Production-code changes include a new or updated automated test in this PR
• SonarQube is temporarily opt-in while the private project has no quota; it is not a PR gate.

Tests Added Or Updated

• tests/unit/wal-maintenance.test.ts (new, 11 tests): busy/clean/sentinel--1/bare-object/undefined-null-[] parsing, pragma-throw never propagates, guarded ctx skips, interval parsing (default/garbage/0), __resetForTests, start silent under test gate, bun:sqlite checkpoint shape (passes under bun test, skips under Node).
• tests/unit/db-wal-truncate-scheduler.test.ts (rewritten 5 wiring tests + 1 new close-table test): new anchors on ./walMaintenance import, startWalMaintenance(db / stopWalMaintenance() / runCheckpointNow, env literal + 6h default + self-gate in the new module, streakBefore ctx at close.
• tests/unit/observability-payloads.test.ts (+1 test): walMaintenance allowlist projection — documented scalars pass, timer internals never leak, null state degrades to null.
• Neighbors green: tests/unit/db-core-init.test.ts (14/14, incl. checkpointMode: null pin), tests/unit/db/vacuum-scheduler.test.ts (11/11), combined WAL+vacuum single-process run (21/21, shared resetter coupling).

Coverage Notes

• Change touches src/lib/db/ (walMaintenance.ts new, core.ts rewired) plus an additive health key (observability.ts, health route). Covered by the new wal-maintenance.test.ts (every outcome branch: busy/clean/sentinel/bare-object/fail-open×3/throw/skipped) plus the rewritten scheduler wiring tests plus the new projection test. No coverage regression expected — new code ships with its tests in the same PR; core.ts only loses deleted lines.

Reviewer Notes

• Two deliberate behavior changes to be aware of: (1) a busy checkpoint at close now warns instead of logging success — that's the visibility fix itself, called out here so it's not mistaken for a regression; (2) the PASSIVE retry costs one extra cheap checkpoint per busy event max, never re-arms, never touches the WAL shrink path.
• walMaintenance.ts never imports ./core (cycle gate clean); clearDbHealthCheckScheduler() ordering in closeDbInstance preserved so no timer leaks. Health addition is one additive key (walMaintenance), management-auth-gated like the rest of the payload — nothing existing moves.
• Verified: focused tests 52 pass / 0 fail (+1 Bun-only skip under Node), typecheck:core clean, ESLint clean on changed files, check:cycles OK, check:file-size silent, check:docs-counts drift is pre-existing (169→170 migrations, untouched). test:bun:db 22/22.