fix(db): harden interrupted restore recovery across schema versions and descriptor cleanup (#1219)

[khaira777]

Summary

Fixes #1219

This PR resolves two recovery and integrity issues identified during regression review:

1. Interrupted restore recovery across schema versions (PR fix(main): optimize order search with indexed candidate retrieval #1204 follow-up):

   • Startup recovery in recoverInterruptedDatabaseReplacement validated prepared replacement snapshots against the current build's schema reference.
   • For an interrupted replacement involving a historical database (e.g. v114 before migration 115 added FTS virtual tables), the snapshot was rejected because it lacked v115 tables and definitions, causing startup recovery to fail and blocking forward migration.
   • Solution: Allow buildIdealSchemaDb and runMigrations to accept an optional targetVersion. Cache recovery schema references per version in cachedSchemaRecoveryReferences. In isHealthyDatabaseFile, retrieve getRecoverySchemaReference(schemaVersion) so that historical databases are verified against their respective valid schema definitions before being restored and migrated forward.

2. Backup descriptor-close cleanup (PR fix(db): eliminate redundant restore snapshot staging and ensure temp cleanup #1193 follow-up):

   • In materializeRestoreSource, if fs.closeSync(sourceFd) threw in finally, the newly created temporary snapshot directory was leaked without invoking its cleanup callback.
   • Solution: Ensure that on any exception (including closeSync failures in finally), the staged snapshot directory is cleaned up immediately.

Verification

• npm run test:backup (All tests passed, including new descriptor-close cleanup and v114 recovery tests)
• npm run test:schema-health (passed)
• npm run test:schema-reference-cache (passed)
• npm run test:upgrade-path (passed)
• node scripts/ci/check-changed-format.cjs --base origin/main (passed)
• npm run lint (0 errors)
• npm run build (passed)
• npm run docs:check (passed)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: FreeOpenSourcePOS/FloCafe/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 10053cee-a83d-48fe-830b-5d97189ca31d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}