namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;

/// <summary>
///     Per-device runtime diagnostics surfaced by the TwinCAT probe loop (PR 3.2 / issue #314).
///     Built by reading four well-known system symbols once per probe interval and stashed on
///     <see cref="TwinCATDriver.DeviceState.LastDiagnostics"/> alongside the existing reachability
///     state. The driver also folds the latest snapshot into
///     <see cref="Core.Abstractions.DriverHealth.Diagnostics"/> so the cross-driver
///     <c>driver-diagnostics</c> RPC (introduced for Modbus task #154) can render TwinCAT
///     cycle-time / jitter / online-change counters next to its peers without a per-driver
///     special-case.
/// </summary>
/// <param name="AppName">
///     Value of <c>TwinCAT_SystemInfoVarList._AppInfo.AppName</c>. Identifies the running PLC
///     application (e.g. <c>"Plc1"</c>) so an operator can tell which project is loaded against
///     the AMS target.
/// </param>
/// <param name="OnlineChangeCnt">
///     Value of <c>TwinCAT_SystemInfoVarList._AppInfo.OnlineChangeCnt</c>. Increments on every
///     accepted online-change. Diffing the value across probe ticks lets operators (and the
///     driver itself) react to runtime symbol-table churn — see the
///     <c>TwinCAT.OnlineChangeCntDelta</c> diagnostic key.
/// </param>
/// <param name="CycleTimeMs">
///     Value of <c>TwinCAT_SystemInfoVarList._TaskInfo[1].CycleTime</c> after the
///     100 ns → ms conversion. Configured task period; constant under normal operation.
/// </param>
/// <param name="LastExecTimeMs">
///     Value of <c>TwinCAT_SystemInfoVarList._TaskInfo[1].LastExecTime</c> after the
///     100 ns → ms conversion. Wall-clock time the last task tick spent running. Compared to
///     <see cref="CycleTimeMs"/> to surface jitter / overrun.
/// </param>
/// <param name="JitterMs">
///     <c>LastExecTimeMs - CycleTimeMs</c>. Positive values indicate the task overran its
///     configured cycle (potential cycle exceedance); negative / zero values are healthy.
/// </param>
/// <param name="UpdatedAt">UTC instant the snapshot was captured.</param>
/// <remarks>
///     Each field is best-effort — the probe wraps individual symbol reads in try/catch so a
///     runtime that doesn't expose <c>_TaskInfo[1]</c> (older TwinCAT 2 builds) still produces a
///     partial snapshot with a non-null <see cref="AppName"/> + <see cref="OnlineChangeCnt"/>.
///     Missing reads fall back to the previous snapshot's value (or the type default for the
///     first probe tick).
/// </remarks>
public sealed record TwinCATDeviceDiagnostics(
    string? AppName,
    uint OnlineChangeCnt,
    double CycleTimeMs,
    double LastExecTimeMs,
    double JitterMs,
    DateTimeOffset UpdatedAt);