fix(database): add native reliability validation

[ucguy4u]

fix(database): add native reliability validation

---

Summary

This PR introduces changes to the native database reliability contract.
Goal: make local database backup/restore and malformed-file recovery deterministic and verifiable on current main.

Core outcome:

• adds file-based backup/restore helpers plus malformed-file recovery before native Drift open
• adds a repeatable validation suite and release runbook for database reliability

---

Changes

Code

• Added:

  • deterministic native database reliability tests
  • release runbook for database reliability validation
  • shared make test-database-reliability target

• Updated:

  • native AppDatabase with path-based construction, backup restore helpers, WAL-aware export, and malformed-file recovery
  • release checklist to include database reliability validation

Logic

• checkpoints WAL before reading backup bytes so exported backups include current writes
• recreates obviously malformed database files before Drift opens them
• supports restoring backup bytes to an explicit database path for deterministic recovery testing

---

API Changes (if any)

• AppDatabase now accepts an optional native database path.
• AppDatabase.restoreBackup(...) and restoreDatabase(...) are added for backup restore flows.

---

Database Changes (if any)

• No schema version bump.
• No destructive migration.
• Reliability behavior around open/export/restore is strengthened for the existing schema.

---

Observability / Logging

• None

---

Performance Impact

• Latency: negligible except when explicitly exporting a backup due to WAL checkpointing
• Throughput: no expected runtime regression for ordinary CRUD paths
• Memory/CPU: no meaningful steady-state change

---

Risks

• malformed-file detection currently targets obvious non-SQLite files rather than deeper logical corruption

• backup export now performs a checkpoint, which is correct for durability but should remain limited to explicit backup paths

• Rollback plan:

  • revert this PR to restore the prior database open/export behavior and remove the validation target/docs

---

Testing

• Unit tests:

  • flutter test test/core/database/app_database_reliability_test.dart

• Integration tests:

  • none

• Manual testing:

  • adb devices -l confirms a reachable Pixel 9 for device-only follow-up checks
  • focused docs/runbook validation and release checklist update

---

Deployment Notes

• Config changes:

  • none

• Order of deployment:

  • normal merge to main

---

Related Commits

• fix(database): add native reliability validation

---

Notes

• Addresses Validation: Database Reliability #516
• Device-only migration/crash-recovery/restore paths remain documented in docs/release/DATABASE_RELIABILITY_VALIDATION.md.

[github-actions]

Plugin Module Size Gate

Policy: modules over 3 MB must be delivered as plugins; plugin modules over 5 MB must document cache management.

Module	Size	Type	Status
No changed Dart/Flutter modules detected	n/a	n/a	OK

[github-actions]

🚀 PR Quick Check Summary

Check	Status	Description
PR Validation	✅ success	Title format, docs, bundled model guardrail
Code Quality	✅ success	Analyze, formatting
Core Tests	✅ success	Core package unit tests

💡 Note: Full app tests, coverage reports, and security scans run on merge to main.

View Details

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud