using System.Diagnostics.CodeAnalysis;

namespace NeonSprawl.Server.Game.Encounters;

/// <summary>
/// Read-only access to validated <see cref="RewardTableDefRow"/> entries loaded at startup (<see cref="RewardTableDefinitionCatalog"/>).
/// </summary>
/// <remarks>
/// <para><b>E5.M3 (encounter completion / loot grants):</b> callers validating reward-table ids and resolving fixed grants should depend on this interface
/// rather than <see cref="RewardTableDefinitionCatalog"/> so reward tables stay centralized.</para>
/// <para><b>NEO-103:</b> HTTP/read-model projections should depend on this interface rather than reaching into the catalog.</para>
/// </remarks>
public interface IRewardTableDefinitionRegistry
{
    /// <summary>Attempts to resolve a reward table by stable <c>id</c> (see <c>reward-table.schema.json</c>). Unknown ids and <c>null</c> return <c>false</c> without throwing.</summary>
    bool TryGetDefinition(string? rewardTableId, [NotNullWhen(true)] out RewardTableDefRow? definition);

    /// <summary>Trims and lowercases <paramref name="rawRewardTableId"/>; returns <c>true</c> when the normalized id exists in the loaded catalog. <c>null</c>, empty, and whitespace return <c>false</c> without throwing.</summary>
    bool TryNormalizeKnown(string? rawRewardTableId, [NotNullWhen(true)] out string normalized);

    /// <summary>Every loaded definition, ordered by <see cref="RewardTableDefRow.Id"/> (ordinal).</summary>
    IReadOnlyList<RewardTableDefRow> GetDefinitionsInIdOrder();
}