feat: add guarded resume recovery comparison tooling (#3460)

* feat: add synthetic resume recovery procedure

* fix: harden resume recovery comparison

* fix: validate recovery objects before serialization

* fix: require serialized recovery requests

* fix: reject ambiguous recovery requests

* [autofix.ci] apply automated fixes

* fix: reject format characters in recovery IDs

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

docs/guides/accessing-the-previous-version.mdx

@@ -3,24 +3,24 @@ title: "Accessing the previous version"
 description: "Access the previous version (v4) of Reactive Resume to retrieve old resumes, and export them for import into the latest version."
 ---
 
-## The previous version is still available
+## Check whether the previous version is available
 
-If you've used Reactive Resume for a while, you may have resumes saved in the previous version. Version 4 (v4) is still fully accessible and will remain online for the foreseeable future.
+If you've used Reactive Resume for a while, you may have resumes saved in version 4 (v4). Access depends on whether
+your self-hosted instance or the hosted previous-version service is currently available.
 
-<Info>The previous version of Reactive Resume is available at [https://v4.rxresu.me](https://v4.rxresu.me).</Info>
+<Info>
+  When the hosted previous version is available, its address is
+  [https://v4.rxresu.me](https://v4.rxresu.me). Availability is not guaranteed.
+</Info>
 
-## Why keep the old version running?
+Self-hosted operators control their own v4 instance and backups. The [v4 to v5 migration
+guide](/self-hosting/migration) applies only to infrastructure they are authorized to operate. It does not authorize
+access to hosted databases or backups.
 
-Anyone who created resumes in v4 can still open, edit, and export them there. Some people also prefer the interface they already know, and moving to a new version takes time.
+## When v4 is accessible
 
-## How long will v4 be available?
-
-The previous version will keep running for as long as possible, until the maintainer runs out of breath or funds to keep the server active. There are no immediate plans to shut it down.
-
-<Warning>
-  v4 will stay accessible for the foreseeable future, but I recommend moving to the latest version when you can. That
-  is where new features and ongoing support land.
-</Warning>
+Open, export, and securely back up each resume you need. Import the export into v5 as a new resume; keep the v5 version
+until you have compared both copies.
 
 ## Accessing your v4 resumes
 
@@ -39,7 +39,7 @@ The previous version will keep running for as long as possible, until the mainta
   </Step>
 
   <Step title="Access your resumes">
-    Once signed in, you'll find all your previously created resumes in your dashboard, exactly as you left them.
+    If the dashboard contains your resumes, export each one as JSON before making more changes.
   </Step>
 </Steps>
 
@@ -53,10 +53,28 @@ If you'd like to move your resumes to the latest version of Reactive Resume, you
 4. Use the import feature to upload your JSON file (select the "Reactive Resume v4 (JSON)" option)
 
 <Info>
-  Your existing resumes should already be available in the new version. If you don't see them, you can manually import
-  them using the steps above.
+  Import creates a separate resume. It should not be used to replace a newer v5 copy until you have compared both
+  versions.
 </Info>
 
+## When hosted v4 or a resume is unavailable
+
+Only an authorized hosted service operator can determine whether a source snapshot exists. Open a GitHub issue without
+including resume contents, account credentials, reset links, or other private data. A useful request identifies the
+approximate time of the missing edits, the sign-in method, and whether the resume is missing or merely not visible.
+
+Recovery is handled per owner. Before accessing content, the operator must record a private case with source snapshot
+time, owner verification, source-to-target mapping, target resume ID, content hashes, and proposed outcome. A matching
+email address, username, or resume title alone is not proof of ownership.
+
+Default recovery result is a private JSON export delivered through an approved channel to a verified recipient. Old-only
+or divergent content must remain a separate copy; it must not overwrite a current v5 resume. If no source snapshot is
+available, the factual outcome is that the records cannot be recovered from the service. Local tooling cannot recreate
+missing source data.
+
+An empty workspace with successful create responses or name conflicts can instead be a listing or account-mapping
+problem. That requires a separate session, create, list, and reload diagnosis; a v4 recovery export does not resolve it.
+
 ## Questions or issues?
 
 If you run into problems accessing v4, or have questions about migrating your resumes, open an issue on [GitHub](https://github.com/amruthpillai/reactive-resume/issues).

docs/self-hosting/migration.mdx

@@ -12,6 +12,12 @@ To move a Reactive Resume installation from **v4 to v5**, you set up a new v5 in
   Docker](/self-hosting/docker) guide. v5 schema migrations run automatically on app startup.
 </Info>
 
+<Warning>
+  This guide applies only to infrastructure and backups you are authorized to operate. It does not grant access to
+  hosted Reactive Resume data. Only the hosted service operator can verify whether a hosted snapshot exists and
+  authorize access to it.
+</Warning>
+
 <Warning>
   **Keep your v4 instance running** until you have migrated all data to v5 and checked that everything works. That way
   you have a fallback if the migration goes wrong.
@@ -48,6 +54,58 @@ The best migration approach depends on the size of your instance:
   </Card>
 </CardGroup>
 
+## Recover one owner's resumes without overwriting v5
+
+Use a recovery case when an owner changed resumes after an earlier migration. Keep the case record private and outside
+Git because it may connect account and resume identifiers. Record these fields before inspecting resume content:
+
+- Recovery case ID
+- Source snapshot capture time
+- Owner verification status
+- Source resume ID and mapped target resume ID, if one exists
+- Source and target content hashes
+- Proposed outcome: `no-op`, `export-copy`, or `blocked`
+
+Case IDs, source resume IDs, and non-null target resume IDs must contain a non-whitespace character after trimming and
+must not contain Unicode control or format characters. Valid identifiers are preserved verbatim.
+
+These hashes prove content equality only; they never prove ownership, source authenticity, or recipient identity.
+
+An authorized operator should follow this order:
+
+<Steps>
+  <Step title="Verify source availability">
+    Confirm that a source snapshot exists and record when it was captured. If no source snapshot exists, report that
+    factual limit. Recovery tooling cannot reconstruct records that are absent from every available source.
+  </Step>
+
+  <Step title="Verify owner and mapping">
+    Verify the requester using the operator's approved account-ownership process. Confirm the old-to-new owner mapping;
+    a matching email address, resume title, or username alone is not ownership proof. Stop if either check is incomplete.
+  </Step>
+
+  <Step title="Compare without writing">
+    Build one serialized JSON comparison request containing the case IDs, safety flags, and source and target values. The
+    comparator accepts only this request string, not an object argument. Source and target data must already conform
+    exactly to the current v5 resume-data schema before content hashes are calculated. Raw v4 exports are unsupported,
+    and the comparator performs no format conversion. Identical content is a `no-op`. Source-only or divergent content
+    is an `export-copy`. Missing identity evidence, mapping, valid current-v5 data, or a source snapshot is `blocked`.
+  </Step>
+
+  <Step title="Deliver a separate private export">
+    Default to a private JSON export. Never overwrite the current v5 resume. After the recipient and delivery channel are
+    approved, deliver the recovered JSON privately so the owner can import it as a separate resume. Record source and
+    delivered hashes outside Git and confirm they match.
+  </Step>
+</Steps>
+
+Repository contributors can rehearse this decision with the pure comparator in
+`tooling/recovery/compare-resume.ts`. It accepts one serialized JSON comparison request and rejects object arguments.
+The request's source and target values must already conform exactly to the current v5 resume-data schema. It does not
+accept raw v4 exports or perform legacy conversion; review the historical converter at tag `v5.0.20` separately before
+processing legacy-format data. The comparator produces a deterministic dry-run manifest and has no database, network,
+or write path. Use synthetic IDs and content only; keep any operational manifest outside the repository.
+
 ## Manual migration (small instances)
 
 If you have only a few resumes to migrate, the simplest approach is to use the **Import Dialog** feature in v5.
@@ -213,8 +271,9 @@ Both migration scripts support graceful shutdown and resume:
 - **Resume migration**: Run the script again to continue from where you left off
 
 <Tip>
-  If you need to restart the migration from scratch, delete the progress files and the user ID mapping file before
-  running the scripts again.
+  Preserve progress files and the user ID mapping as recovery evidence. Do not delete them or replay the historical
+  scripts against a populated target as a recovery shortcut. Review the `v5.0.20` scripts, source backup, mapping, and
+  target state before any rerun.
 </Tip>
 
 ## Post-migration steps
@@ -290,8 +349,9 @@ After completing the migration:
 </Accordion>
 
 <Accordion title="Resume data parsing fails">
-  If a resume can't be parsed from v4 format, it will be created with default empty data. Check the console output for
-  warnings about specific resumes, and consider manually importing those using the Import Dialog.
+  Historical scripts can create default empty data when a v4 resume cannot be parsed. Treat that result as a failed
+  conversion, not a recovered resume. Preserve the source export, review the `v5.0.20` converter, and use the Import
+  Dialog only after valid source data is confirmed.
 </Accordion>
 
   <Accordion title="Migration is slow">