namespace Svrnty.CQRS.Altcha.Abstractions;

/// <summary>
/// Resolves a per-request PoW complexity (search-space upper bound) for the
/// next Altcha challenge the server will mint. Implementations may consult
/// per-actor signals — repeat-offender counters, threat-intel headers,
/// reputation scores — to scale difficulty up for suspicious actors while
/// keeping the baseline cheap for everyone else.
/// </summary>
/// <remarks>
/// The framework ships a no-op <see cref="IAltchaDifficultyAdvisor"/> that
/// always returns <c>null</c>, meaning "use the upstream service's configured
/// default complexity." Applications opt into adaptive difficulty by
/// replacing the registration with their own implementation; consult request
/// context via <see cref="Microsoft.AspNetCore.Http.IHttpContextAccessor"/>
/// or scoped DI.
/// </remarks>
public interface IAltchaDifficultyAdvisor
{
    /// <summary>
    /// Returns the desired <c>maxNumber</c> (PoW search-space upper bound)
    /// for the next challenge, or <c>null</c> to defer to the upstream
    /// service default. The Altcha server clamps to its configured min/max,
    /// so callers don't need to enforce bounds here.
    /// </summary>
    Task<uint?> GetComplexityAsync(CancellationToken cancellationToken = default);
}