namespace NeonSprawl.Server.Game.Items;

/// <summary>Result of <see cref="PlayerInventoryOperations.TryAddStack"/> or <see cref="PlayerInventoryOperations.TryRemoveStack"/> (NEO-54).</summary>
public enum PlayerInventoryMutationKind
{
    /// <summary>Validation or rules deny — inventory unchanged.</summary>
    Denied,

    /// <summary><see cref="IPlayerInventoryStore"/> could not read or write the player bucket.</summary>
    StoreMissing,

    /// <summary>Mutation applied and persisted.</summary>
    Applied,
}

/// <param name="ReasonCode">Populated when <see cref="Kind"/> is <see cref="PlayerInventoryMutationKind.Denied"/>.</param>
/// <param name="Snapshot">Authoritative snapshot after apply, or unchanged snapshot on deny; null when store missing.</param>
public readonly record struct PlayerInventoryMutationOutcome(
    PlayerInventoryMutationKind Kind,
    string? ReasonCode,
    PlayerInventorySnapshot? Snapshot);