using System.Diagnostics.CodeAnalysis;

namespace NeonSprawl.Server.Game.Gathering;

/// <summary>
/// Read-only access to validated resource-node definitions and yield rows loaded at startup
/// (<see cref="ResourceNodeCatalog"/>).
/// </summary>
/// <remarks>
/// <para><b>E3.M1 (gather / depletion / interact):</b> callers resolving node defs or yields should depend on this
/// interface rather than <see cref="ResourceNodeCatalog"/> so gather lens, capacity, and yield metadata stay
/// centralized.</para>
/// <para><b>NEO-60:</b> HTTP/read-model projections should depend on this interface rather than reaching into the
/// catalog.</para>
/// </remarks>
public interface IResourceNodeDefinitionRegistry
{
    /// <summary>
    /// Attempts to resolve a node def by stable <c>nodeDefId</c> (see <c>resource-node-def.schema.json</c>).
    /// Unknown ids and <c>null</c> return <c>false</c> without throwing.
    /// </summary>
    bool TryGetDefinition(string? nodeDefId, [NotNullWhen(true)] out ResourceNodeDefRow? definition);

    /// <summary>
    /// Attempts to resolve the fixed yield row for <paramref name="nodeDefId"/> (see
    /// <c>resource-yield-row.schema.json</c>). Unknown ids and <c>null</c> return <c>false</c> without throwing.
    /// </summary>
    bool TryGetYield(string? nodeDefId, [NotNullWhen(true)] out ResourceYieldRow? yield);

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