namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Scripts;

/// <summary>
/// One alarm condition as seen by a site script through <c>Alarms.CurrentAsync()</c>
/// (MES alarm-status API §5.2). A flat, script-friendly projection of the instance's
/// retained <c>AlarmStateChanged</c> — computed alarms and mirrored native (OPC UA A&amp;C /
/// MxAccess Gateway) conditions alike — so a script can answer "what is currently in
/// alarm on this instance?" without knowing the actor-internal message shape.
///
/// <para>
/// <b>Read-only snapshot.</b> The values are the instance's state at the moment the
/// accessor's Ask was served; nothing here writes back to the source. Native alarms are a
/// read-only mirror by design (no ack-back).
/// </para>
///
/// <para>
/// <b>Placement in Commons</b> so the SiteRuntime runtime accessor and the ScriptAnalysis
/// compile-only surface project to the SAME type — a script that binds against the
/// design-time surface therefore also binds at the site. Commons is already in
/// <c>ScriptTrustPolicy.DefaultAssemblies</c>, so the type resolves in the script
/// compilation without widening the trust reference set.
/// </para>
/// </summary>
/// <param name="Name">
/// The alarm's name on the instance — the computed alarm's configured name, or the native
/// condition's per-condition source reference.
/// </param>
/// <param name="SourceReference">Native per-condition key (e.g. "Tank01.Level.HiHi"); empty for computed alarms.</param>
/// <param name="NativeSourceCanonicalName">
/// Canonical name of the native alarm SOURCE BINDING this condition belongs to
/// (e.g. "LeftSideAlarms"); empty for computed alarms. Scripts scope by source with this.
/// </param>
/// <param name="Active">Whether the condition is currently active (in alarm).</param>
/// <param name="Acknowledged">Whether the condition has been acknowledged at the source.</param>
/// <param name="Confirmed">Confirmed vs unconfirmed; <c>null</c> when the condition is not confirmable.</param>
/// <param name="Shelved">Whether the source has shelved the condition (any shelve sub-state).</param>
/// <param name="Suppressed">Whether the source has suppressed the condition.</param>
/// <param name="Severity">Severity on the unified 0–1000 scale.</param>
/// <param name="Kind">"Computed", "NativeOpcUa" or "NativeMxAccess".</param>
/// <param name="Message">Event/per-band operator message; may be empty.</param>
/// <param name="AlarmTypeName">Native alarm type (e.g. "AnalogLimitAlarm.HiHi"); empty for computed alarms.</param>
/// <param name="Category">Native alarm category/taxonomy; empty for computed alarms.</param>
/// <param name="OperatorUser">Operator who acknowledged at the source (display-only); empty otherwise.</param>
/// <param name="OperatorComment">Operator comment captured at the source (display-only); empty otherwise.</param>
/// <param name="OriginalRaiseTime">When the condition originally became active, if the source reports it.</param>
/// <param name="Timestamp">Timestamp of the transition this snapshot row reflects.</param>
/// <param name="AckTime">
/// When the condition was acknowledged, or <c>null</c> while unacknowledged. See
/// <c>AlarmStateChanged.AckTime</c> for provenance — source ack instant where the protocol
/// supplies one (OPC UA A&amp;C), DCL observation time of the ack transition otherwise.
/// </param>
/// <param name="CurrentValue">Current source value (display-only); empty for computed alarms.</param>
/// <param name="LimitValue">Limit/threshold value for native limit alarms (display-only); empty otherwise.</param>
/// <param name="IsConfiguredPlaceholder">
/// True for a placeholder row standing in for a CONFIGURED native source binding that
/// currently holds no conditions. Scripts enumerating real alarms should filter these out.
/// </param>
public sealed record ScriptAlarm(
    string Name,
    string SourceReference,
    string NativeSourceCanonicalName,
    bool Active,
    bool Acknowledged,
    bool? Confirmed,
    bool Shelved,
    bool Suppressed,
    int Severity,
    string Kind,
    string Message,
    string AlarmTypeName,
    string Category,
    string OperatorUser,
    string OperatorComment,
    DateTimeOffset? OriginalRaiseTime,
    DateTimeOffset Timestamp,
    DateTimeOffset? AckTime,
    string CurrentValue,
    string LimitValue,
    bool IsConfiguredPlaceholder);
