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

/// <summary>
/// Rich result of an <c>Attributes.WaitForAsync</c> wait (spec §3) — the full
/// outcome of waiting for an attribute to reach a value / satisfy a predicate /
/// change at all, bounded by a timeout. The <c>Attributes.WaitAsync</c> helpers
/// surface only <see cref="Matched"/>; <c>WaitForAsync</c> returns this struct so
/// a script can also read the matched <see cref="Value"/>, its <see cref="Quality"/>,
/// and distinguish a genuine timeout (<see cref="TimedOut"/>) from a non-match.
/// </summary>
/// <param name="Matched">
/// <see langword="true"/> when the attribute reached the target / satisfied the
/// predicate within the timeout (and, in quality-gated mode, at "Good" quality).
/// </param>
/// <param name="Value">The matched value; <see langword="null"/> on timeout / error.</param>
/// <param name="Quality">
/// The attribute quality at match time; <see langword="null"/> on the non-match
/// paths (timeout / error / cap-exceeded).
/// </param>
/// <param name="TimedOut"><see langword="true"/> when the timeout fired before a match.</param>
public readonly record struct WaitResult(bool Matched, object? Value, string? Quality, bool TimedOut);
