namespace NeonSprawl.Server.Game.Mastery;

/// <summary>Persisted mastery branch picks and unlocked perks per player (NEO-47).</summary>
public interface IPlayerPerkStateStore
{
    PerkStateSnapshot GetSnapshot(string playerId);

    /// <summary>Whether <paramref name="playerId"/> can receive perk state writes (mirrors skill progression store bucket rules).</summary>
    bool CanWritePlayer(string playerId);

    /// <summary>Fails when pick already exists for <c>(skillId, tierIndex)</c> or player cannot be written.</summary>
    bool TrySetBranchPick(string playerId, string skillId, int tierIndex, string branchId);

    /// <summary>Adds perks not already unlocked; fails when player cannot be written.</summary>
    bool TryAddUnlockedPerks(string playerId, IEnumerable<string> perkIds);

    /// <summary>Removes unlocked perks present in the store; fails when player cannot be written.</summary>
    bool TryRemoveUnlockedPerks(string playerId, IEnumerable<string> perkIds);

    /// <summary>Removes a branch pick (engine rollback when perk unlock fails after pick).</summary>
    bool TryRemoveBranchPick(string playerId, string skillId, int tierIndex);

    /// <summary>Clears all branch picks and unlocked perks for the player (NEO-48 dev fixture API).</summary>
    bool TryResetPerkState(string playerId);

    /// <summary>Replaces branch picks and unlocked perks with <paramref name="snapshot"/> (grant rollback).</summary>
    bool TryRestoreSnapshot(string playerId, PerkStateSnapshot snapshot);
}