namespace ZB.MOM.WW.ScadaBridge.SiteEventLogging;

/// <summary>
/// Interface for recording operational events to the local SQLite event log.
/// </summary>
public interface ISiteEventLogger
{
    /// <summary>
    /// Record an event asynchronously. The call enqueues the event onto a background
    /// writer and returns without blocking the caller on disk I/O. The returned
    /// <see cref="Task"/> completes once the event is durably persisted and faults if
    /// the write fails, so callers that <c>await</c> it observe success or failure.
    /// </summary>
    /// <param name="eventType">Category: script, alarm, deployment, connection, store_and_forward, instance_lifecycle</param>
    /// <param name="severity">Info, Warning, or Error</param>
    /// <param name="instanceId">Optional instance ID associated with the event</param>
    /// <param name="source">Source identifier, e.g., "ScriptActor:MonitorSpeed"</param>
    /// <param name="message">Human-readable event description</param>
    /// <param name="details">
    /// Optional free-form detail text (stack traces, compilation errors, etc.).
    /// Stored verbatim — JSON is conventional but not validated or enforced.
    /// </param>
    Task LogEventAsync(
        string eventType,
        string severity,
        string? instanceId,
        string source,
        string message,
        string? details = null);

    /// <summary>
    /// SiteEventLogging-018: total number of event writes that have failed
    /// (SQLite error, disk full, bounded-queue overflow drop, etc.) since this
    /// logger was created. Available for future Health Monitoring integration —
    /// promoted onto the interface so a Health consumer can read it without a
    /// concrete-type downcast. Not yet polled by Health Monitoring; the wiring
    /// is tracked separately.
    /// </summary>
    long FailedWriteCount { get; }
}