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 a branch pick (engine rollback when perk unlock fails after pick).</summary>
    bool TryRemoveBranchPick(string playerId, string skillId, int tierIndex);
}