using System.Diagnostics.CodeAnalysis;

namespace NeonSprawl.Server.Game.Crafting;

/// <summary>
/// Read-only access to validated <see cref="RecipeDefRow"/> entries loaded at startup (<see cref="RecipeDefinitionCatalog"/>).
/// </summary>
/// <remarks>
/// <para><b>E3.M2 (craft / refine):</b> callers validating <c>CraftRequest</c> and resolving I/O rows should depend on this interface
/// rather than <see cref="RecipeDefinitionCatalog"/> so recipe metadata stays centralized.</para>
/// <para><b>NEO-68:</b> HTTP/read-model projections should depend on this interface rather than reaching into the catalog.</para>
/// </remarks>
public interface IRecipeDefinitionRegistry
{
    /// <summary>Attempts to resolve a recipe by stable <c>id</c> (see <c>recipe-def.schema.json</c>). Unknown ids and <c>null</c> return <c>false</c> without throwing.</summary>
    bool TryGetDefinition(string? recipeId, [NotNullWhen(true)] out RecipeDefRow? definition);

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