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,
}

/// <summary>
/// Result of <see cref="PlayerInventoryOperations.TryAddStack"/> or <see cref="PlayerInventoryOperations.TryRemoveStack"/> (NEO-54).
/// <see cref="ReasonCode"/> is populated when <see cref="Kind"/> is <see cref="PlayerInventoryMutationKind.Denied"/>.
/// <see cref="Snapshot"/> is the authoritative snapshot after apply, or unchanged snapshot on deny; null when store missing.
/// </summary>
public readonly record struct PlayerInventoryMutationOutcome(
    PlayerInventoryMutationKind Kind,
    string? ReasonCode,
    PlayerInventorySnapshot? Snapshot);