namespace NeonSprawl.Server.Game.Factions;

/// <summary>
/// Persisted per-player faction standing keyed by <c>(playerId, factionId)</c> (NEO-135).
/// Missing row ⇒ neutral <c>0</c> at read. Consumed by <c>ReputationOperations</c> (NEO-136) and gate eval (NEO-137).
/// </summary>
public interface IFactionStandingStore
{
    /// <summary>Whether mutations for <paramref name="playerId"/> are allowed (dev bucket or Postgres <c>player_position</c> row).</summary>
    bool CanWritePlayer(string playerId);

    /// <summary>
    /// Reads standing for one faction. Missing row ⇒ <c>0</c> clamped to faction min/max.
    /// Unknown faction id ⇒ structured deny with <see cref="FactionStandingReasonCodes.UnknownFaction"/>.
    /// </summary>
    FactionStandingReadOutcome TryGetStanding(string playerId, string factionId);

    /// <summary>
    /// Applies a signed delta, clamps resulting standing to faction min/max, and persists.
    /// Does not append audit rows — <see cref="IReputationDeltaStore"/> is orchestrated by NEO-136.
    /// </summary>
    FactionStandingMutationOutcome TryApplyStandingDelta(string playerId, string factionId, int deltaAmount);

    /// <summary>
    /// Removes persisted standing for one faction (missing row reads as neutral <c>0</c>).
    /// Dev fixture / Bruno reset only — not for gameplay rollback.
    /// </summary>
    bool TryClearStanding(string playerId, string factionId);
}