Result types

One shape for every call#

public sealed class PersistenceResult<T>
{
    public bool IsSuccess { get; }
    public T Value { get; }
    public PersistenceError Error { get; }   // Status, Code, Message, IsRetryable
}

Every public operation that can fail returns one of these. There is no try/catch around a save in a shipping game, because there is nothing to catch: the failures that matter — a full disk, a locked file, a missing key — are expected conditions with names.

Failure versus outcome#

That distinction is the difference between "start a new game" and "show the player an error", and it is why NotFound is not an error code in the first place.

Retryability#

Error.IsRetryable answers "would trying again plausibly help?" A locked file or a transient I/O failure says yes; a rejected precondition, a missing key or an authentication failure says no — and an automatic retry there would make things worse. The cloud layer uses the same flag to decide what CloudRetrier may touch.

Results that carry reports#

Some results carry a report rather than a single value:

• SaveLoadResult<T> — data, metadata, descriptor, outcome, migration report, recovery report, carry-over, warnings;
• SaveCommit — what a write did: bytes, revision, promotion strategy, backup created, verified by read-back;
• StorageRecoveryReport — what recovery moved, and why;
• UnityProjectionReport / UnityRestoreReport — findings with what/why/fix.

Every failure is explainable, and every explanation names what to do next.

The rule that follows#

Next#

• Error codes — the values Error.Code can take.
• Save and load — the calls that return these.
• Diagnostics — the log events that accompany them.