# Stage 08: Database Connection and Migration Foundation

Date: 2026-07-29

## Result

- Centralized SQLite connection policy in `SQLiteConnectionFactory`.
- Preserved WAL, foreign-key enforcement, row mapping, handle cleanup, and the existing
  20-second contention tolerance.
- Added an ordered migration runner with immutable checksums and an applied-migration ledger.
- Added savepoint rollback so a failed migration cannot be recorded or leave partial schema.
- Adopted existing databases as version `0001` only after verifying the required legacy
  tables.
- Kept the legacy idempotent bootstrap in place for compatibility with databases created by
  every previous application version.

## Forward Rule

All schema changes after this stage must be a new immutable module under
`backend/database/migrations`. Editing an applied migration is rejected by checksum. A
database containing a migration unknown to the running code is rejected rather than opened
with an older schema interpretation.

## Residual Risk

The historical inline bootstrap remains a compatibility facade during repository migration.
It may be removed only after legacy upgrade fixtures cover every supported historical shape.
No user table or row is rewritten in this stage.