Recovery

Recovery is explicit#

Reading a slot never changes it. When a save is damaged, the framework reports that and stops — and you decide whether to recover:

var recovery = await NexusForgePersistence.Slots.RecoverAsync(new SaveSlotId(class="tok-str">"default"));

if (recovery.IsSuccess)
{
    var report = recovery.Value;      // StorageRecoveryReport
class="tok-com">
    // Which file was damaged, which backup was used, what was quarantined, and why.
    diagnostics.Log(report.Summary);
}

That separation is deliberate: a transient read failure (a locked file, a permissions blip) should not be answered by rewriting a player's save. Recovery happens when you say it happens.

What recovery does, in order#

1. Reads the primary and checks its integrity value before parsing anything.
2. If it is unusable, moves it aside into quarantine with a reason — evidence, not garbage.
3. Finds the newest backup that does verify.
4. Restores that backup through the same verified path a normal write uses.
5. Reports each step, file by file.

What a report contains#

StorageRecoveryReport tells you:

• which file was treated as damaged, and the code that said so;
• which backup was chosen and why it was the newest valid one;
• what was quarantined, under which name;
• whether the restored file verified.

It is enough to explain to a support agent, and enough to decide whether the underlying cause is your storage, the platform, or a genuine defect worth reporting.

When recovery should not run#

• An unverifiable file is not a damaged file. If the save is encrypted and no key is available, the framework reports a missing key (NF.PERSIST.SECURITY.KEY_UNAVAILABLE) and leaves the file strictly alone, rather than quarantining a perfectly good save.
• A backup is not a time machine. Recovery restores the previous version in that slot, not an arbitrary older one. Use checkpoints or your own export for "go back further".

Next#

• Corruption handling — the checks that decide "damaged".
• Backups — the files recovery chooses from.
• Troubleshooting — the integrity and key error codes.