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

/// <summary>
/// One execution within an execution chain returned by
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories.IAuditLogRepository.GetExecutionTreeAsync"/>.
/// Each node summarises the <c>AuditLog</c> rows sharing a single
/// <see cref="ExecutionId"/>; the Central UI renders the set as a tree by
/// joining <see cref="ParentExecutionId"/> to a parent node's
/// <see cref="ExecutionId"/>.
/// </summary>
/// <remarks>
/// <para>
/// <b>Stub nodes.</b> An execution that performed a trust-boundary action but
/// crossed it without emitting any audit row — or whose own rows have been
/// purged — still appears as a node when a child references it via
/// <see cref="ParentExecutionId"/>. Such a stub node has <see cref="RowCount"/>
/// = 0, empty <see cref="Channels"/>/<see cref="Statuses"/>, null
/// <see cref="SourceSiteId"/>/<see cref="SourceInstanceId"/>, null timestamps,
/// and a null <see cref="ParentExecutionId"/> (a purged/ghost parent leaves no
/// row from which its own parent could be read — the upward walk ends there).
/// </para>
/// <para>
/// <see cref="Channels"/> and <see cref="Statuses"/> are the distinct sets of
/// the corresponding enum names present across the execution's rows, modelled
/// as <see cref="IReadOnlyList{T}"/> of string to mirror how the repository's
/// query filters already pass small bounded sets around.
/// </para>
/// </remarks>
/// <param name="ExecutionId">The execution this node summarises.</param>
/// <param name="ParentExecutionId">
/// The <see cref="ExecutionId"/> of the spawning execution, or null for the
/// root (and for stub nodes, whose own parent is unknowable).
/// </param>
/// <param name="RowCount">
/// Number of <c>AuditLog</c> rows carrying this <see cref="ExecutionId"/>; 0 for
/// a stub node.
/// </param>
/// <param name="Channels">
/// Distinct <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditChannel"/> names
/// present across this execution's rows; empty for a stub node.
/// </param>
/// <param name="Statuses">
/// Distinct <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditStatus"/> names
/// present across this execution's rows; empty for a stub node.
/// </param>
/// <param name="SourceSiteId">
/// Source site of the execution's rows when consistent; null for a stub node
/// (or when the rows carry no site).
/// </param>
/// <param name="SourceInstanceId">
/// Source instance of the execution's rows when consistent; null for a stub
/// node (or when the rows carry no instance).
/// </param>
/// <param name="FirstOccurredAtUtc">
/// Earliest <c>OccurredAtUtc</c> across this execution's rows; null for a stub
/// node.
/// </param>
/// <param name="LastOccurredAtUtc">
/// Latest <c>OccurredAtUtc</c> across this execution's rows; null for a stub
/// node.
/// </param>
public sealed record ExecutionTreeNode(
    Guid ExecutionId,
    Guid? ParentExecutionId,
    int RowCount,
    IReadOnlyList<string> Channels,
    IReadOnlyList<string> Statuses,
    string? SourceSiteId,
    string? SourceInstanceId,
    DateTime? FirstOccurredAtUtc,
    DateTime? LastOccurredAtUtc);
