using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using GB5Shared.DTO.Framework.Login;
using GB5Shared.GEF;

namespace GB5Shared.SIP;

/// <summary>
/// Thin, directly-referenceable contract for SIP (Signal &amp; Insight Processor) — any module
/// emits a signal here without a hard reference to the SIP implementation
/// (<c>FrameworkBLL.SIP.SIPSignalService</c>), same reasoning as
/// <c>GB5Shared.GEF.IGEFEngine</c>. Reuses <see cref="SignalDTO"/> from <c>GB5Shared.GEF</c>
/// rather than a duplicate — it is the same signal shape GEF consumes as
/// <c>SituationDTO.SupportingSignals</c> input.
/// <para>
/// One-way dependency: GEF may read SIP's output; SIP never calls GEF (canvas §8.2).
/// </para>
/// </summary>
public interface ISIPSignalService
{
    /// <summary>Appends one immutable signal to the Interaction Pattern Ledger.</summary>
    Task EmitSignalAsync(
        SignalDTO signal,
        string domain,
        string entityCode,
        int entityId,
        LoginDTO login,
        CancellationToken ct);

    /// <summary>Returns per-SignalType occurrence summaries for the given entity.</summary>
    Task<IReadOnlyList<PatternSummaryDTO>> GetPatternSummaryAsync(
        string domain,
        string entityCode,
        int entityId,
        LoginDTO login,
        CancellationToken ct);
}