namespace NeonSprawl.Server.Game.Quests;

/// <summary>
/// Persisted per-player quest progress keyed by <c>(playerId, questId)</c> (NEO-116).
/// Missing row ⇒ <c>not_started</c>. <c>QuestStateOperations</c> (NEO-117) and HTTP (E7M1-08) consume this interface.
/// </summary>
public interface IPlayerQuestStateStore
{
    /// <summary>True when mutations for <paramref name="playerId"/> are allowed (dev bucket or Postgres <c>player_position</c> row).</summary>
    bool CanWritePlayer(string playerId);

    /// <summary>Missing row ⇒ <c>false</c> (callers treat as <c>not_started</c>).</summary>
    bool TryGetProgress(string playerId, string questId, out QuestStepState snapshot);

    /// <summary>Creates an active row at step 0 with empty counters. Returns <c>false</c> when already active/completed or player cannot be written.</summary>
    bool TryActivate(string playerId, string questId, out QuestStepState snapshot);

    /// <summary>Requires an active row; sets step index and clears objective counters. Denies when completed or <paramref name="newStepIndex"/> is not greater than current.</summary>
    bool TryAdvanceStep(string playerId, string questId, int newStepIndex, out QuestStepState snapshot);

    /// <summary>Requires an active row; sets one objective counter (non-negative). Denies when completed.</summary>
    bool TryUpdateObjectiveCounter(
        string playerId,
        string questId,
        string objectiveId,
        int newCount,
        out QuestStepState snapshot);

    /// <summary>First completion returns <c>true</c>; replays return <c>false</c> without changing <see cref="QuestStepState.CompletedAt"/>.</summary>
    bool TryMarkComplete(string playerId, string questId, DateTimeOffset completedAt, out QuestStepState snapshot);
}