Document that restore_backup checks a backup before replacing the database

[cb1kenobi]

⊙ Problem

HarperFast/harper#3121 changes what restore_backup does. It now stages the backup and checks it before replacing the database, refuses a backup it can't read or a copy that won't fit, and refuses symlinked or mount-point database directories. The backup reference still describes the old close-purge-restore order.

❓ Your call: Should a patch-level behavior change get release-note and reference coverage, or wait for 5.4? I've documented it as "As of v5.3.2", matching the page's existing v5.3.1 paragraph, because the core PR is milestoned v5.3. If it isn't cherry-picked to the 5.3 line, every "v5.3.2" here should become "v5.4.0" and the release-note entry should move to 5.4.

💡 Solution

• reference/backups/operations.md, restore_backup.
  • The new order.
  • The staged check: what it proves, and what it doesn't (blobs), plus what a refused rerun leaves.
  • Writes accepted while staging are replaced.
  • The space requirement, the 507, and the symlink and mount-point refusals, including what to do after an interrupted restore.
  • Subscriptions on a restore refused before the close.
  • What an interruption leaves behind.
• reference/backups/overview.md.
  • A new Limitations bullet covers staging, space, blobs and the refused layouts.
  • The "when can a database be restored" intro no longer says "purges".
  • The worked example describes staging.
• release-notes/v5-lincoln/5.3.md. A "Restore Checks a Backup Before Replacing the Database (5.3.2)" entry under Backups.

✅ Verification

• npm run build passes and npm run format:check is clean.
• Every behavior claim was checked against the core branch. The claim that a restore refused before the close leaves subscriptions running was confirmed with a probe test on that branch: the subscription received a later write and stayed open.

_{🤖 Generated by Anthropic Claude (Opus); posted via @cb1kenobi.}

Related PRs: none found
Complexity: easy

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex,cursor-muse; adjudicated=domain; declined=cursor-grok,cursor-kimi; rounds=4; full=2 @ b91aaf3}

_{Review-Attention: skim ~2m (decisions: release-target, internals-as-contract, version-marking) @ b91aaf3}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-721

This preview will update automatically when you push new commits.