namespace ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;

/// <summary>
/// A single attribute value change on a deployed instance — published to the
/// site-wide stream and routed to the interested child actors (Script Actors,
/// Alarm Actors) of the owning Instance Actor.
/// </summary>
/// <param name="InstanceUniqueName">Unique name of the instance the attribute belongs to.</param>
/// <param name="AttributePath">Path-qualified canonical name of the attribute.</param>
/// <param name="AttributeName">Canonical name of the attribute.</param>
/// <param name="Value">The new value.</param>
/// <param name="Quality">Quality of the new value (<c>Good</c>/<c>Bad</c>/<c>Uncertain</c>).</param>
/// <param name="Timestamp">UTC timestamp of the change.</param>
/// <param name="SourceExecutionId">
/// Audit Log #23 (ParentExecutionId tag-cascade): the <c>ExecutionId</c> of the
/// script execution / inbound API request whose write produced this change, or
/// <c>null</c> when the change did not originate from an audited execution —
/// which is the case for every value that arrives from the Data Connection
/// Layer (external device data), for deployment-time seeding, and for the
/// confirmed value of a data-sourced write (the device echo arrives on the
/// subscription long after the writing execution ended).
///
/// <para>
/// The Alarm Actor records this id as the <c>ParentExecutionId</c> of the
/// on-trigger script run the change fires, so a script-initiated write that
/// trips an alarm chains under the writing execution in the audit tree.
/// </para>
///
/// <para>
/// Deliberately site-local: the field is NOT projected onto the gRPC
/// <c>DebugAttributeValueDto</c> / <c>SiteStreamEvent</c> wire shapes — the
/// cascade is resolved entirely inside the site node that owns the Instance
/// Actor, and central reads the linkage from the audit rows instead.
/// </para>
/// </param>
public record AttributeValueChanged(
    string InstanceUniqueName,
    string AttributePath,
    string AttributeName,
    object? Value,
    string Quality,
    DateTimeOffset Timestamp,
    Guid? SourceExecutionId = null) : ISiteStreamEvent;
