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

namespace GB5Shared.GEF;

/// <summary>
/// Thin, directly-referenceable contract for GEF (Guided Execution Framework) — deterministic
/// situation→guidance evaluation that any module (SalesMind, Marketing, and later
/// Production/Quality/Service) injects and calls in-process, with no cross-module BLL project
/// reference needed (same reasoning as <c>GB5Shared.RecordingIntelligence.IAICapabilityService</c>).
/// <para>
/// No persistence of its own. The real implementation
/// (<c>FrameworkBLL.GEF.GEFEngine</c>) configures behavior entirely through the existing
/// Qualifier tables (MQUALIFIERDEFINITION/MQUALIFIERENTITY/MQUALIFIERRULEGROUP/
/// MQUALIFIERRULECONDITION/MQUALIFIEROUTPUT/MQUALIFIERMETHOD/MQUALIFIERVERSION) via
/// <c>GB5Shared.GOP.Qualifier.IQualifierFacadeImpl</c> — GEF does not invent its own rule/condition
/// storage.
/// </para>
/// <para>
/// Deterministic, config-driven rule evaluation only in v1 — no ML/LLM inference here. AI-provided
/// suggestions (EAI, a later module) feed in only as <see cref="SignalDTO"/> input, never as a
/// guardrail override (canvas §9: AI may summarize/suggest/detect, never decide).
/// </para>
/// </summary>
public interface IGEFEngine
{
    /// <summary>
    /// Evaluates the given situation against whatever qualifier bindings exist for
    /// <c>context.EntityCode</c>/<c>context.Stage</c>, returning guidance. Returns an empty/neutral
    /// <see cref="GuidanceOutputDTO"/> (no exception) when no qualifier is configured yet for the
    /// caller's domain — GEF must degrade gracefully, not fail, when a consumer module (e.g.
    /// SalesMind/Marketing) is not yet wired up.
    /// </summary>
    Task<GuidanceOutputDTO> EvaluateAsync(
        ExecutionContextDTO context,
        IEnumerable<SignalDTO> signals,
        LoginDTO login,
        CancellationToken ct);

    /// <summary>
    /// Persists whether the actor followed a prior <see cref="GuidanceOutputDTO.Focus"/> and what
    /// happened. A log-append operation, not a primary business entity save — see
    /// <c>FrameworkBLL.GEF.GEFEngine.RecordOutcomeFeedbackAsync</c> for why this does not route
    /// through <c>ExecuteSaveAsync</c>.
    /// </summary>
    Task RecordOutcomeFeedbackAsync(
        OutcomeFeedbackDTO feedback,
        LoginDTO login,
        CancellationToken ct);
}