Save and load | NexusForge Persistence 0.2.0 documentation

Save and load

The slot service surface — save, load, list, info, delete, recover, export and adopt — and where each one belongs.

Core features NexusForge Persistence 0.2.0 Updated 2026-09-24

One service, eight verbs#

SaveSlotService is reachable as NexusForgePersistence.Slots, and every convenience call on the facade ends up here.

Member	Does	Notes
`SaveAsync`	Writes a model to a slot	Returns `SaveCommit`: bytes, revision, promotion strategy, backup, read-back verification.
`LoadAsync<T>`	Reads a slot back	Returns the data, metadata, migration and recovery reports, carry-over and warnings.
`ListAsync`	Lists every slot	Headers and metadata only, so a menu costs kilobytes.
`InfoAsync`	One slot's descriptor	The same cheap read.
`DeleteAsync`	Removes a slot	Explicit; never done by shutdown, disposal or reset.
`RecoverAsync`	Quarantines a damaged primary and restores the newest valid backup	Reports what it did, file by file.
`ExportAsync`	Copies a slot out	Useful for support and for moving a save between machines.
`AdoptAsync`	Takes a file in, after validating it	The import path; it will not accept an unverified file.

It also exposes the composed parts — Storage, Coordinator, Migration, Integrity — for the cases where you need to talk to one of them directly.

Everything is a result#

csharp

var saved = await NexusForgePersistence.Slots.SaveAsync(slot, model, request);
if (saved.IsSuccess && saved.Value.VerifiedByReadBack)
{
class="tok-com">    // The write was confirmed by reading it back: the strongest signal a save system can give you.
}

Error codes are stable strings, so they are the documented way to branch, and a missing slot is an outcome (LoadOutcome.NotFound) rather than a failed operation.

Concurrency in one process#

Writes within a process are coordinated so only one happens at a time; a second save while one is running is either superseded or serialised according to the coordinator. That is what makes "save on pause, then save on destroy" safe to leave switched on. Across two processes sharing one save root there is no coordination: atomic promotion keeps either version intact, but the later writer wins. See Limitations.

Next#

Your first save · Your first load — the short versions.
Error codes — every code, grouped by subsystem.
Result types — PersistenceResult, outcomes and retryability.

Something wrong on this page? Every page here describes behaviour that is checked in the repository. If a page and the package disagree, the package wins.

Report a documentation problem · Frequently asked questions · Troubleshooting