Program.cs

// =============================================================================
//  OSDP SC2 ACU Benchmark
//
//  A command-line Access Control Unit (ACU) that measures the response rate and
//  latency of a Peripheral Device (PD) implementation of OSDP Secure Channel v2
//  across two phases:
//
//    1. Asymmetric pairing        - the post-quantum osdp_PAIR/osdp_PAIRR exchange
//                                    that derives the 32-byte SCBK out of band.
//    2. SC2 messaging init        - the symmetric SC2 handshake (CHLNG / CCRYPT /
//                                    SCRYPT) that brings the secure channel up,
//                                    repeated with the derived key.
//
//  Results are printed to the console and written to a Markdown report.
//
//  Usage:
//    OsdpSc2Benchmark --port COM5 [options]
//
//  Options:
//    --port <name>           Serial port of the RS-485 bus (required, e.g. COM5)
//    --baud <rate>           Baud rate                          (default 38400)
//    --address <0-127>       PD address                         (default 0)
//    --mode <both|pairing|sc2>  Which phase(s) to run           (default both)
//    --pair-iterations <n>   Pairing trials                     (default 1; needs a
//                            manual PD reset between trials if raised)
//    --sc2-iterations <n>    SC2 handshake trials               (default 5). Each session
//                            also issues osdp_ID, osdp_CAP and osdp_KEYSET and times the
//                            reply interval for each.
//    --pair-timeout <sec>    Per-pairing timeout                (default 30)
//    --sc2-timeout <sec>     Per-SC2-handshake timeout          (default 15)
//    --scbk <hex>            Pre-shared 32-byte SCBK (64 hex chars). If given, the
//                            SC2 phase uses it instead of deriving one by pairing.
//    --output <path>         Markdown report path        (default benchmark-report.md)
//    --help                  Show this help.
//
//  The PD under test is expected to trust the OSDP.Net demo CA for pairing
//  (CertificateAuthority.Demo()), matching the OSDP.Net console demonstration.
// =============================================================================

using System.Diagnostics;
using System.Text;
using OSDP.Net;
using OSDP.Net.Connections;
using OSDP.Net.Messages;
using OSDP.Net.Messages.SecureChannel;
using OSDP.Net.Model.CommandData;
using OSDP.Net.Model.ReplyData;
using OSDP.Net.Pairing;

if (args.Contains("--self-test"))
{
    // Validates the timing arithmetic without a PD. Exits before touching a serial port.
    Console.WriteLine(PairingProfiler.SelfTest());

    // Fragment sizing is the other piece of arithmetic that a bad answer would only reveal on
    // hardware, where retrying costs a manual PD reset.
    Console.WriteLine("Fragment size derivation (packet size -> fragment payload):");
    var fragmentCases = new (ushort Packet, int Expected)[]
    {
        (BenchmarkConfig.MaxPacketSize, BenchmarkConfig.MaxPacketSize - 8 - BenchmarkConfig.PairingFragmentHeaderSize),
        (256, 256 - 8 - BenchmarkConfig.PairingFragmentHeaderSize),
        (128, 128 - 8 - BenchmarkConfig.PairingFragmentHeaderSize),
    };
    var fragmentFailures = new List<string>();
    foreach (var (packet, expected) in fragmentCases)
    {
        ushort actual = BenchmarkConfig.MaxFragmentForPacket(packet);
        Console.WriteLine($"  {packet,5} B packet -> {actual,5} B fragment");
        if (actual != expected) fragmentFailures.Add($"{packet} B: expected {expected}, got {actual}");
    }
    Console.WriteLine(fragmentFailures.Count == 0
        ? "SELF-TEST PASSED: fragment sizing matches header + code + CRC + fragment header."
        : "SELF-TEST FAILED:\n  - " + string.Join("\n  - ", fragmentFailures));
    return 0;
}

var config = BenchmarkConfig.Parse(args);
if (config is null)
{
    return 1; // Parse already printed usage / the error.
}

var runner = new BenchmarkRunner(config);
try
{
    return await runner.RunAsync();
}
catch (Exception ex)
{
    Console.Error.WriteLine();
    Console.Error.WriteLine($"FATAL: {ex.GetType().Name}: {ex.Message}");
    Console.Error.WriteLine(ex.StackTrace);
    return 2;
}

// =============================================================================
//  Configuration
// =============================================================================

/// <summary>Parsed command-line options driving the benchmark run.</summary>
internal sealed class BenchmarkConfig
{
    public string Port { get; private set; }
    public int Baud { get; private set; } = 38400;
    public byte Address { get; private set; } = 0;
    public RunMode Mode { get; private set; } = RunMode.Both;
    // Pairing is a one-shot operation in practice: a PD that has paired holds an established
    // secure channel and NAKs the cleartext osdp_PAIR that a second trial would need
    // (CommunicationSecurityNotMet). Repeating it requires a manual PD reset between trials, so
    // the default is a single trial. Raise this only if you are resetting the PD by hand.
    public int PairIterations { get; private set; } = 1;

    // Maximum pairing fragment size, in payload bytes. Null means "derive it from the PD's reported
    // receive buffer capability", which is the default: the ACU queries osdp_ID and osdp_CAP before
    // pairing and sizes fragments to what the device says it can take.
    public ushort? FragmentSizeOverride { get; private set; }

    /// <summary>Fragment size used when the PD does not report a usable receive buffer size.</summary>
    public const ushort DefaultFragmentSize = 1024;

    /// <summary>
    /// Bytes the multipart fragment header adds inside the message payload: TotalSize, Offset and
    /// FragmentSize, two bytes each under <see cref="MessageDataFragmentFieldSize.TwoBytes"/>, which
    /// is what the pairing exchange uses. <see cref="Message.CalculateMaximumMessageSize"/> accounts
    /// for the OSDP framing around the payload but not for this header inside it.
    /// </summary>
    public const int PairingFragmentHeaderSize = 6;

    /// <summary>Largest total OSDP packet the protocol allows.</summary>
    public const ushort MaxPacketSize = 1440;

    /// <summary>
    /// Converts a total packet size into the largest pairing fragment payload that fits inside it.
    /// The PD's receive buffer capability describes the whole packet, so the framing has to come off
    /// before the number means anything. Pairing rides cleartext, hence <c>isEncrypted: false</c>.
    /// </summary>
    public static ushort MaxFragmentForPacket(ushort totalPacketSize)
    {
        ushort payload = Message.CalculateMaximumMessageSize(totalPacketSize, isEncrypted: false);
        return (ushort)Math.Max(payload - PairingFragmentHeaderSize, 0);
    }

    // Size advertised to the PD via osdp_ACURXSIZE so it knows how large a reply packet the ACU can
    // accept. This is the only lever over PD -> ACU fragment size: --fragment-size governs only the
    // ACU's outbound fragments, which is why message 2 did not shrink when it was raised. 0 skips
    // the command entirely.
    public ushort AcuReceiveSize { get; private set; } = MaxPacketSize;

    /// <summary>
    /// Upper bound on a derived fragment size. Derived from <see cref="MaxPacketSize"/> rather than
    /// chosen: the ceiling is on the whole packet, so the payload ceiling is that minus framing.
    /// </summary>
    public static ushort MaxFragmentSize => MaxFragmentForPacket(MaxPacketSize);
    public int Sc2Iterations { get; private set; } = 5;
    public TimeSpan PairTimeout { get; private set; } = TimeSpan.FromSeconds(30);
    public TimeSpan Sc2Timeout { get; private set; } = TimeSpan.FromSeconds(15);
    public byte[] PresharedScbk { get; private set; } // null unless --scbk supplied
    public string OutputPath { get; private set; } = "benchmark-report.md";

    /// <summary>How long to wait for the PD to answer cleartext polls before a pairing attempt.</summary>
    public TimeSpan OnlineWait { get; } = TimeSpan.FromSeconds(5);

    /// <summary>Settle time between trials so the bus returns to a known state.</summary>
    public TimeSpan InterTrialDelay { get; } = TimeSpan.FromMilliseconds(750);

    public enum RunMode { Both, Pairing, Sc2 }

    public bool RunPairing => Mode is RunMode.Both or RunMode.Pairing;
    public bool RunSc2 => Mode is RunMode.Both or RunMode.Sc2;

    public static BenchmarkConfig Parse(string[] args)
    {
        var c = new BenchmarkConfig();

        try
        {
            for (int i = 0; i < args.Length; i++)
            {
                string a = args[i];
                string Next(string name)
                {
                    if (i + 1 >= args.Length)
                        throw new ArgumentException($"Option {name} requires a value.");
                    return args[++i];
                }

                switch (a)
                {
                    case "--help" or "-h" or "/?":
                        PrintUsage();
                        return null;
                    case "--port": c.Port = Next(a); break;
                    case "--baud": c.Baud = int.Parse(Next(a)); break;
                    case "--address": c.Address = ParseAddress(Next(a)); break;
                    case "--mode": c.Mode = ParseMode(Next(a)); break;
                    case "--pair-iterations": c.PairIterations = int.Parse(Next(a)); break;
                    case "--fragment-size": c.FragmentSizeOverride = ushort.Parse(Next(a)); break;
                    case "--acu-receive-size": c.AcuReceiveSize = ushort.Parse(Next(a)); break;
                    case "--sc2-iterations": c.Sc2Iterations = int.Parse(Next(a)); break;
                    case "--pair-timeout": c.PairTimeout = TimeSpan.FromSeconds(double.Parse(Next(a))); break;
                    case "--sc2-timeout": c.Sc2Timeout = TimeSpan.FromSeconds(double.Parse(Next(a))); break;
                    case "--scbk": c.PresharedScbk = ParseHexKey(Next(a)); break;
                    case "--output": c.OutputPath = Next(a); break;
                    default:
                        throw new ArgumentException($"Unknown option: {a}");
                }
            }

            if (string.IsNullOrWhiteSpace(c.Port))
                throw new ArgumentException("--port is required (e.g. --port COM5).");

            if (c.Mode == RunMode.Sc2 && c.PresharedScbk is null)
            {
                // sc2-only has nothing to derive a key from; it needs one supplied.
                throw new ArgumentException(
                    "--mode sc2 requires --scbk <hex> (no pairing phase runs to derive a key).");
            }
        }
        catch (Exception ex)
        {
            Console.Error.WriteLine($"Argument error: {ex.Message}");
            Console.Error.WriteLine("Run with --help for usage.");
            return null;
        }

        return c;
    }

    private static byte ParseAddress(string s)
    {
        byte addr = byte.Parse(s);
        if (addr > 127) throw new ArgumentException("--address must be between 0 and 127.");
        return addr;
    }

    private static RunMode ParseMode(string s) => s.ToLowerInvariant() switch
    {
        "both" => RunMode.Both,
        "pairing" or "pair" => RunMode.Pairing,
        "sc2" => RunMode.Sc2,
        _ => throw new ArgumentException($"--mode must be both|pairing|sc2 (got '{s}').")
    };

    private static byte[] ParseHexKey(string hex)
    {
        hex = hex.Replace("-", "").Replace(" ", "").Trim();
        if (hex.Length != 64)
            throw new ArgumentException("--scbk must be 32 bytes (64 hex characters).");
        var key = new byte[32];
        for (int i = 0; i < 32; i++)
            key[i] = Convert.ToByte(hex.Substring(i * 2, 2), 16);
        return key;
    }

    public static void PrintUsage()
    {
        Console.WriteLine(
            """
            OSDP SC2 ACU Benchmark - measures PD response rate for pairing and SC2 init.

            Usage:
              OsdpSc2Benchmark --port COM5 [options]

            Options:
              --port <name>              Serial port (required, e.g. COM5, /dev/ttyUSB0)
              --baud <rate>              Baud rate                    (default 38400)
              --address <0-127>          PD address                   (default 0)
              --mode <both|pairing|sc2>  Which phase(s) to run        (default both)
              --pair-iterations <n>      Pairing trials               (default 1; >1 needs
                                         a manual PD reset per trial)
              --fragment-size <n>        Pairing fragment payload bytes. Default is derived
                                         from the PD's reported receive buffer (whole-packet)
                                         minus framing, capped at OSDP's 1440-byte packet.
                                         Governs ACU -> PD fragments only.
              --acu-receive-size <n>     Packet size advertised to the PD via osdp_ACURXSIZE
                                         (default 1440, 0 to skip). The only lever over
                                         PD -> ACU fragment size.
              --sc2-iterations <n>       SC2 handshake trials         (default 5)
              --pair-timeout <sec>       Per-pairing timeout          (default 30)
              --sc2-timeout <sec>        Per-SC2-handshake timeout    (default 15)
              --scbk <hex>               Pre-shared 32-byte SCBK (64 hex). If set, the
                                         SC2 phase uses it instead of pairing to derive one.
              --output <path>            Markdown report path  (default benchmark-report.md)
              --self-test                Verify the timing profiler's arithmetic against a
                                         synthetic exchange and exit. No PD or serial port
                                         needed.
              --help                     Show this help.
            """);
    }
}

// =============================================================================
//  Trial results and statistics
// =============================================================================

/// <summary>Outcome of a single benchmark trial.</summary>
internal sealed record TrialResult(
    int Index,
    bool Success,
    double ElapsedMs,
    string Detail,
    string FailureCategory,
    PairingProfile Profile = null,
    IReadOnlyList<CommandTiming> Commands = null);

/// <summary>Round-trip time for one OSDP command issued after the channel was up.</summary>
internal sealed record CommandTiming(string Name, double Ms, bool Success, string Detail);

/// <summary>
/// What the PD reported about itself, plus the fragment size derived from it.
/// </summary>
internal sealed class DeviceQuery
{
    public string Identity { get; init; }
    public IReadOnlyList<string> Capabilities { get; init; }
    public IReadOnlyList<CommandTiming> Timings { get; init; }

    /// <summary>Total OSDP packet the PD can receive, per capability 10. Null if not reported.</summary>
    public int? ReceiveBufferSize { get; init; }

    /// <summary>Largest reassembled multipart message, per capability 11. Null if not reported.</summary>
    public int? LargestCombinedMessageSize { get; init; }

    public bool Succeeded { get; init; }
}

/// <summary>One measured span within a pairing exchange.</summary>
internal sealed record PairingSegment(string Name, double Ms, string Attribution, int Fragments);

/// <summary>
/// A stage-by-stage timing breakdown of a single pairing exchange, derived from the
/// <see cref="PairingProgress"/> reports emitted by <c>ControlPanel.PairDevice</c>.
/// </summary>
internal sealed class PairingProfile
{
    public IReadOnlyList<PairingSegment> Segments { get; init; }
    public double TotalMs { get; init; }

    /// <summary>True when a message produced a single progress callback, so its wire time
    /// could not be separated from the adjacent turnaround.</summary>
    public bool HasCollapsedSpans { get; init; }
}

/// <summary>
/// Captures pairing progress reports with timestamps so the exchange can be profiled.
/// </summary>
/// <remarks>
/// This deliberately implements <see cref="IProgress{T}"/> by hand instead of using
/// <see cref="Progress{T}"/>. <see cref="Progress{T}"/> marshals its callback through the captured
/// synchronization context (or the thread pool, in a console app), so the timestamp would include
/// scheduling delay — precisely the sub-millisecond-to-millisecond quantity being measured here.
/// Reporting inline on the calling thread keeps the samples faithful to the protocol events.
/// </remarks>
internal sealed class PairingProfiler : IProgress<PairingProgress>
{
    private readonly record struct Sample(double AtMs, PairingStage Stage);

    private readonly List<Sample> _samples = new();
    private readonly object _gate = new();
    private readonly Stopwatch _sw = Stopwatch.StartNew();

    /// <summary>The most recently reported stage, used to attribute failures.</summary>
    public PairingStage LastStage { get; private set; } = PairingStage.SendingRequest;

    public void Report(PairingProgress value)
    {
        double at = _sw.Elapsed.TotalMilliseconds;
        lock (_gate)
        {
            _samples.Add(new Sample(at, value.Stage));
            LastStage = value.Stage;
        }
    }

    /// <summary>
    /// Derives the per-operation breakdown. Returns null if the exchange did not run to completion.
    /// </summary>
    public PairingProfile BuildProfile()
    {
        Sample[] samples;
        lock (_gate) samples = _samples.ToArray();
        return DeriveProfile(samples);
    }

    /// <summary>
    /// Exercises <see cref="DeriveProfile"/> against a synthetic exchange so the segment arithmetic
    /// can be checked without hardware. Pairing needs a manual PD reset to retry, so the math is
    /// worth validating before spending a real attempt on it.
    /// </summary>
    public static string SelfTest()
    {
        var sb = new StringBuilder();

        // A synthetic exchange chosen so every span is checkable by hand, including the
        // first-fragment correction each group receives.
        //
        //   scope    : marker at 5                                        -> 5
        //   msg1     : 3 callbacks at 145/195/245, perFragment 50
        //              build    = (145-5) - 50                            -> 90
        //              wire     = (245-145) + 50                          -> 150
        //   msg2     : 2 callbacks at 445/505, perFragment 60
        //              turnaround = (445-245) - 60                        -> 140
        //              wire       = (505-445) + 60                        -> 120
        //   msg3     : 2 callbacks at 605/645, perFragment 40
        //              verify   = (605-505) - 40                          -> 60
        //              wire     = (645-605) + 40                          -> 80
        //   result   : 1 callback at 745, no gap to measure, correction 0
        //              turnaround = (745-645) - 0                         -> 100
        //              wire       = 0                                     -> 0
        //   finalize : 755 - 745                                          -> 10
        //   total    : 755
        var samples = new[]
        {
            new Sample(5, PairingStage.SendingRequest),      // marker, after scope acquisition
            new Sample(145, PairingStage.SendingRequest),    // msg1 fragment 1
            new Sample(195, PairingStage.SendingRequest),
            new Sample(245, PairingStage.SendingRequest),    // msg1 fragment 3
            new Sample(445, PairingStage.AwaitingResponse),
            new Sample(505, PairingStage.AwaitingResponse),
            new Sample(605, PairingStage.SendingConfirmation),
            new Sample(645, PairingStage.SendingConfirmation),
            new Sample(745, PairingStage.AwaitingResult),
            new Sample(755, PairingStage.Completed),
        };

        var p = DeriveProfile(samples);
        if (p is null)
        {
            return "SELF-TEST FAILED: DeriveProfile returned null for a completed exchange.";
        }

        sb.AppendLine("Profiler self-test (synthetic exchange, no hardware):");
        foreach (var seg in p.Segments)
        {
            sb.AppendLine($"  {seg.Ms,8:0.0} ms  {seg.Name} [{seg.Attribution}]");
        }
        sb.AppendLine($"  {p.TotalMs,8:0.0} ms  total exchange");
        sb.AppendLine();

        // Expected values follow directly from the synthetic timestamps above.
        var expected = new (string Name, double Ms)[]
        {
            ("Acquire bus command scope", 5),
            ("Build message 1 (ML-KEM keygen + ML-DSA sign)", 90),
            ("Message 1 on the wire (ACU -> PD)", 150),
            ("PD turnaround before message 2", 140),
            ("Message 2 on the wire (PD -> ACU)", 120),
            ("Verify PD credential + derive key (ProcessMessage2)", 60),
            ("Message 3 on the wire (ACU -> PD)", 80),
            ("PD turnaround before result", 100),
            ("Result message on the wire (PD -> ACU)", 0),
            ("Confirm key (ProcessResult)", 10),
        };

        var failures = new List<string>();
        foreach (var (name, ms) in expected)
        {
            var seg = p.Segments.FirstOrDefault(s => s.Name == name);
            if (seg is null) { failures.Add($"missing segment '{name}'"); continue; }
            if (Math.Abs(seg.Ms - ms) > 0.001) failures.Add($"'{name}': expected {ms} ms, got {seg.Ms}");
        }
        if (Math.Abs(p.TotalMs - 755) > 0.001) failures.Add($"total: expected 755 ms, got {p.TotalMs}");
        if (!p.HasCollapsedSpans) failures.Add("expected HasCollapsedSpans for the single-fragment messages");

        // Segments must account for the whole exchange with no gap or double-count.
        double sum = p.Segments.Sum(s => s.Ms);
        if (Math.Abs(sum - p.TotalMs) > 0.001) failures.Add($"segments sum to {sum} ms but total is {p.TotalMs} ms");

        sb.AppendLine(failures.Count == 0
            ? "SELF-TEST PASSED: all segments and the total reconcile."
            : "SELF-TEST FAILED:\n  - " + string.Join("\n  - ", failures));
        return sb.ToString();
    }

    private static PairingProfile DeriveProfile(Sample[] samples)
    {
        if (samples.Length < 2 || samples[^1].Stage != PairingStage.Completed)
        {
            return null; // Incomplete exchange - a partial profile would be misleading.
        }

        // Group by stage and take the extremes by timestamp rather than by list position, so the
        // result holds even if a fragment callback arrives from another thread out of order.
        //
        // The origin is the stopwatch zero (PairDevice entry), NOT the first sample: the gap before
        // the first report is real work (acquiring the bus command scope) and must not be discarded.
        const double t0 = 0.0;
        double tEnd = samples.Max(s => s.AtMs);

        // The earliest SendingRequest sample is the SendingRequest(0.0) marker emitted before
        // CreateMessage1; the remaining SendingRequest samples are per-fragment send callbacks.
        double tMarker = samples.Where(s => s.Stage == PairingStage.SendingRequest).Min(s => s.AtMs);

        Sample[] Group(PairingStage stage, bool skipMarker = false) => samples
            .Where(s => s.Stage == stage && !(skipMarker && s.AtMs == tMarker))
            .ToArray();

        var sendReq = Group(PairingStage.SendingRequest, skipMarker: true);
        var awaitResp = Group(PairingStage.AwaitingResponse);
        var sendConf = Group(PairingStage.SendingConfirmation);
        var awaitRes = Group(PairingStage.AwaitingResult);

        double? First(Sample[] g) => g.Length == 0 ? null : g.Min(s => s.AtMs);
        double? Last(Sample[] g) => g.Length == 0 ? null : g.Max(s => s.AtMs);

        // Per-fragment cost, from the gaps between consecutive fragment callbacks.
        double? PerFragment(Sample[] g) =>
            g.Length >= 2 ? (g.Max(s => s.AtMs) - g.Min(s => s.AtMs)) / (g.Length - 1) : null;

        var segments = new List<PairingSegment>();

        void Add(string name, double ms, string attribution, int fragments = 0) =>
            segments.Add(new PairingSegment(name, ms, attribution, fragments));

        /// Splits the span [boundary, last-of-group] into the compute that preceded the message and
        /// the message's own time on the wire.
        ///
        /// Both the send and receive progress callbacks fire *after* a fragment's round trip
        /// completes (ControlPanel.ExchangePairingMessage invokes onSendProgress after awaiting
        /// SendCommand). So the first callback of a group arrives one whole fragment late, and a
        /// naive boundary would bill that fragment to the preceding compute step. At 128-byte
        /// fragments that error is small; at 1024 it is ~270 ms and badly distorts the split.
        /// The measured per-fragment mean is moved back to the wire to correct it.
        void AddSplit(string computeName, string computeAttribution, string wireName,
            double? boundary, Sample[] group)
        {
            if (boundary is null || group.Length == 0) return;

            double first = First(group).Value;
            double last = Last(group).Value;
            double available = Math.Max(first - boundary.Value, 0);
            double correction = Math.Min(PerFragment(group) ?? 0, available);

            Add(computeName, available - correction, computeAttribution);
            Add(wireName, (last - first) + correction, "Serial link", group.Length);
        }

        Add("Acquire bus command scope", tMarker - t0, "ACU / bus");
        AddSplit("Build message 1 (ML-KEM keygen + ML-DSA sign)", "ACU crypto",
            "Message 1 on the wire (ACU -> PD)", tMarker, sendReq);
        AddSplit("PD turnaround before message 2", "PD crypto + poll wait",
            "Message 2 on the wire (PD -> ACU)", Last(sendReq), awaitResp);
        AddSplit("Verify PD credential + derive key (ProcessMessage2)", "ACU crypto",
            "Message 3 on the wire (ACU -> PD)", Last(awaitResp), sendConf);
        AddSplit("PD turnaround before result", "PD crypto + poll wait",
            "Result message on the wire (PD -> ACU)", Last(sendConf), awaitRes);

        double? lastResultSample = Last(awaitRes) ?? Last(sendConf);
        if (lastResultSample is not null)
        {
            Add("Confirm key (ProcessResult)", tEnd - lastResultSample.Value, "ACU crypto");
        }

        // A single-fragment group gives no gap to measure, so its wire time cannot be separated
        // from the preceding step and stays folded into it.
        bool collapsed = new[] { sendReq, awaitResp, sendConf, awaitRes }.Any(g => g.Length == 1);

        return new PairingProfile
        {
            Segments = segments,
            TotalMs = tEnd - t0,
            HasCollapsedSpans = collapsed,
        };
    }
}

/// <summary>Aggregate latency statistics over the successful trials of a phase.</summary>
internal sealed class TrialStats
{
    public int Total { get; init; }
    public int Successes { get; init; }
    public int Failures => Total - Successes;
    public double SuccessRate => Total == 0 ? 0 : 100.0 * Successes / Total;
    public double MinMs { get; init; }
    public double MaxMs { get; init; }
    public double MeanMs { get; init; }
    public double MedianMs { get; init; }
    public double P95Ms { get; init; }

    public static TrialStats From(IReadOnlyList<TrialResult> trials)
    {
        var latencies = trials.Where(t => t.Success).Select(t => t.ElapsedMs).OrderBy(x => x).ToArray();
        if (latencies.Length == 0)
        {
            return new TrialStats { Total = trials.Count, Successes = 0 };
        }

        double Percentile(double p)
        {
            // Nearest-rank percentile on the ascending-sorted latencies.
            int rank = (int)Math.Ceiling(p / 100.0 * latencies.Length);
            rank = Math.Clamp(rank, 1, latencies.Length);
            return latencies[rank - 1];
        }

        double median = latencies.Length % 2 == 1
            ? latencies[latencies.Length / 2]
            : (latencies[latencies.Length / 2 - 1] + latencies[latencies.Length / 2]) / 2.0;

        return new TrialStats
        {
            Total = trials.Count,
            Successes = latencies.Length,
            MinMs = latencies[0],
            MaxMs = latencies[^1],
            MeanMs = latencies.Average(),
            MedianMs = median,
            P95Ms = Percentile(95),
        };
    }
}

// =============================================================================
//  Benchmark runner
// =============================================================================

internal sealed class BenchmarkRunner
{
    private readonly BenchmarkConfig _config;
    private readonly ControlPanel _panel = new();
    private Guid _connectionId;

    // Demo trust: the PD under test is expected to trust the same demo CA.
    private readonly CertificateAuthority _ca = CertificateAuthority.Demo();
    private PairingConfiguration _acuPairingConfig;

    // Live connection-status snapshot maintained from ConnectionStatusChanged.
    private volatile bool _isConnected;
    private volatile bool _isSecure;
    private TaskCompletionSource<bool> _secureEstablished;

    // Every pairing attempt made, phase-1 trials and SCBK-derivation fallbacks alike. Drives the
    // timing profile; the response-rate statistics use only the numbered phase-1 trials.
    private readonly List<TrialResult> _allPairingAttempts = new();

    // Result of the pre-pairing osdp_ID / osdp_CAP interrogation, and the fragment size it implied.
    private DeviceQuery _discovery;
    private ushort _fragmentSize = BenchmarkConfig.DefaultFragmentSize;
    private string _fragmentRationale = "not yet resolved";

    public BenchmarkRunner(BenchmarkConfig config) => _config = config;

    public async Task<int> RunAsync()
    {
        _acuPairingConfig = new PairingConfiguration(
            PairingCredentials.Generate(new DeviceIdentity("Z-bit Systems", "ACU-Benchmark", "BENCH-0001"), _ca),
            PairingTrustAnchor.FromCa(_ca));

        PrintHeader();

        _panel.ConnectionStatusChanged += OnConnectionStatusChanged;
        _connectionId = _panel.StartConnection(new SerialPortOsdpConnection(_config.Port, _config.Baud));

        var pairingTrials = new List<TrialResult>();
        var sc2Trials = new List<TrialResult>();
        byte[] scbk = _config.PresharedScbk;

        try
        {
            // ---- Phase 0: interrogate the PD before sizing anything -------------
            // osdp_ID and osdp_CAP go out in cleartext on an unpaired PD. The reported receive
            // buffer size is what sets the pairing fragment size, so this has to happen before
            // pairing, not after.
            Console.WriteLine("\n== Phase 0: PD interrogation (cleartext) ==");
            ResetToCleartext();
            bool online = await WaitForOnlineAsync(_config.OnlineWait);
            if (!online)
            {
                Console.WriteLine("  PD not answering cleartext polls yet; querying anyway.");
            }

            _discovery = await QueryDeviceAsync(advertiseReceiveSize: true);
            PrintCommandTimings(_discovery.Timings, "  ");
            if (_discovery.Identity is not null)
            {
                Console.WriteLine($"  identity: {_discovery.Identity}");
            }
            foreach (var line in _discovery.Capabilities)
            {
                Console.WriteLine($"  cap: {line}");
            }

            (_fragmentSize, _fragmentRationale) = ResolveFragmentSize(_discovery);
            Console.WriteLine($"  fragment size: {_fragmentSize} bytes ({_fragmentRationale})");

            // ---- Phase 1: pairing response rate --------------------------------
            if (_config.RunPairing)
            {
                Console.WriteLine($"\n== Phase 1: Asymmetric pairing ({_config.PairIterations} trials) ==");
                for (int i = 1; i <= _config.PairIterations; i++)
                {
                    var (trial, derivedScbk) = await RunPairingTrialAsync(i);
                    pairingTrials.Add(trial);
                    scbk ??= derivedScbk; // keep the first key we manage to derive
                    ReportTrial(trial);
                    PrintProfile(trial.Profile);
                    await Task.Delay(_config.InterTrialDelay);
                }
            }

            // ---- Phase 2: SC2 messaging initialization -------------------------
            if (_config.RunSc2)
            {
                if (scbk is null)
                {
                    // Pairing produced no key (or wasn't run) and none was supplied; derive one now.
                    Console.WriteLine("\nNo SCBK yet; running a one-off pairing to derive a key for the SC2 phase...");
                    scbk = await DeriveScbkForSc2Async();
                }

                if (scbk is null)
                {
                    Console.WriteLine("Could not obtain an SCBK; skipping the SC2 initialization phase.");
                }
                else
                {
                    Console.WriteLine($"\n== Phase 2: SC2 messaging initialization ({_config.Sc2Iterations} trials) ==");
                    for (int i = 1; i <= _config.Sc2Iterations; i++)
                    {
                        var trial = await RunSc2InitTrialAsync(i, scbk);
                        sc2Trials.Add(trial);
                        ReportTrial(trial);
                        PrintCommandTimings(trial.Commands);
                        await Task.Delay(_config.InterTrialDelay);
                    }
                }
            }
        }
        finally
        {
            _panel.ConnectionStatusChanged -= OnConnectionStatusChanged;
            try { _panel.RemoveDevice(_connectionId, _config.Address); } catch { /* ignore */ }
            try { await _panel.StopConnection(_connectionId); } catch { /* ignore */ }
            try { await _panel.Shutdown(); } catch { /* ignore */ }
        }

        // ---- Report ------------------------------------------------------------
        var pairingStats = TrialStats.From(pairingTrials);
        var sc2Stats = TrialStats.From(sc2Trials);

        PrintSummary("Pairing", pairingStats, pairingTrials, _config.RunPairing);
        PrintSummary("SC2 init", sc2Stats, sc2Trials, _config.RunSc2 && sc2Trials.Count > 0);

        var report = ReportWriter.Build(_config, scbk, pairingTrials, pairingStats, sc2Trials, sc2Stats,
            _allPairingAttempts, _discovery, _fragmentSize, _fragmentRationale);
        await File.WriteAllTextAsync(_config.OutputPath, report);
        Console.WriteLine($"\nMarkdown report written to: {Path.GetFullPath(_config.OutputPath)}");

        return 0;
    }

    // ---- Pairing trial -----------------------------------------------------

    /// <summary>
    /// Runs one pairing attempt and records it in <see cref="_allPairingAttempts"/>.
    /// </summary>
    /// <remarks>
    /// Every attempt is recorded, including the fallback attempts made by
    /// <see cref="DeriveScbkForSc2Async"/>. Those are not numbered phase-1 trials and must stay out
    /// of the response-rate statistics, but a pairing that completed there is still a real exchange
    /// and its timing profile is exactly what the report is for. Dropping it produced a report that
    /// claimed no pairing completed while the PD had in fact paired.
    /// </remarks>
    private async Task<(TrialResult trial, byte[] scbk)> RunPairingTrialAsync(int index)
    {
        var outcome = await RunPairingTrialCoreAsync(index);
        _allPairingAttempts.Add(outcome.trial);
        return outcome;
    }

    private async Task<(TrialResult trial, byte[] scbk)> RunPairingTrialCoreAsync(int index)
    {
        // Fresh cleartext session for each pairing attempt.
        ResetToCleartext();
        bool onlineAtStart = await WaitForOnlineAsync(_config.OnlineWait);

        var profiler = new PairingProfiler();

        var sw = Stopwatch.StartNew();
        try
        {
            using var cts = new CancellationTokenSource(_config.PairTimeout + TimeSpan.FromSeconds(5));
            PairingResult result = await _panel.PairDevice(
                _connectionId, _config.Address, _acuPairingConfig,
                maximumFragmentSize: _fragmentSize,
                timeout: _config.PairTimeout, progress: profiler, cancellationToken: cts.Token);
            sw.Stop();

            string detail = $"paired with {result.PeerIdentity}";
            return (new TrialResult(index, true, sw.Elapsed.TotalMilliseconds, detail, null,
                profiler.BuildProfile()), result.Scbk);
        }
        catch (PairingException ex)
        {
            sw.Stop();
            string detail = $"stage={profiler.LastStage}, status={ex.Status}: {ex.Message}";
            return (new TrialResult(index, false, sw.Elapsed.TotalMilliseconds, detail, ex.Status.ToString()), null);
        }
        catch (TimeoutException)
        {
            sw.Stop();
            string cat = onlineAtStart ? "Timeout" : "Timeout (PD offline in cleartext)";
            // Report the actual elapsed time, not the configured budget — the underlying call can
            // give up earlier than --pair-timeout.
            string detail = $"stage={profiler.LastStage}: timed out after {sw.Elapsed.TotalSeconds:0.0}s " +
                            $"(budget {_config.PairTimeout.TotalSeconds:0}s)" +
                            (onlineAtStart ? "" : " (PD did not answer cleartext polls before the attempt)");
            return (new TrialResult(index, false, sw.Elapsed.TotalMilliseconds, detail, cat), null);
        }
        catch (Exception ex)
        {
            sw.Stop();
            return (new TrialResult(index, false, sw.Elapsed.TotalMilliseconds,
                $"stage={profiler.LastStage}: {ex.GetType().Name}: {ex.Message}", ex.GetType().Name), null);
        }
    }

    /// <summary>
    /// Issues osdp_ID and osdp_CAP and times each reply. Used twice: once in cleartext before
    /// pairing (to size the pairing fragments from what the PD says it can receive), and again on
    /// each established SC2 session.
    /// </summary>
    private async Task<DeviceQuery> QueryDeviceAsync(byte[] keysetKey = null,
        bool advertiseReceiveSize = false)
    {
        var timings = new List<CommandTiming>();
        string identity = null;
        var capabilityLines = new List<string>();
        int? receiveBuffer = null;
        int? largestCombined = null;
        bool allOk = true;

        // --- osdp_ID -------------------------------------------------------------
        var sw = Stopwatch.StartNew();
        try
        {
            var id = await _panel.IdReport(_connectionId, _config.Address);
            sw.Stop();
            identity = $"vendor {BitConverter.ToString(id.VendorCode.Take(3).ToArray())}, " +
                       $"model {id.ModelNumber}, version {id.Version}, S/N {id.SerialNumber}, " +
                       $"firmware {id.FirmwareMajor}.{id.FirmwareMinor}.{id.FirmwareBuild}";
            timings.Add(new CommandTiming("osdp_ID (ID Report)", sw.Elapsed.TotalMilliseconds, true, identity));
        }
        catch (Exception ex)
        {
            sw.Stop();
            allOk = false;
            timings.Add(new CommandTiming("osdp_ID (ID Report)", sw.Elapsed.TotalMilliseconds, false,
                $"{ex.GetType().Name}: {ex.Message}"));
        }

        // --- osdp_CAP ------------------------------------------------------------
        sw = Stopwatch.StartNew();
        try
        {
            var caps = await _panel.DeviceCapabilities(_connectionId, _config.Address);
            sw.Stop();
            foreach (var cap in caps.Capabilities)
            {
                // Capabilities 10 and 11 encode a 16-bit size across the two capability bytes,
                // little-endian, rather than a compliance/count pair.
                int size = cap.Compliance | (cap.NumberOf << 8);
                switch (cap.Function)
                {
                    case CapabilityFunction.ReceiveBufferSize:
                        receiveBuffer = size;
                        capabilityLines.Add($"ReceiveBufferSize = {size} bytes (whole packet)");
                        break;
                    case CapabilityFunction.LargestCombinedMessageSize:
                        largestCombined = size;
                        capabilityLines.Add($"LargestCombinedMessageSize = {size} bytes");
                        break;
                    default:
                        capabilityLines.Add($"{cap.Function} = compliance {cap.Compliance}, numberOf {cap.NumberOf}");
                        break;
                }
            }
            timings.Add(new CommandTiming("osdp_CAP (PD Capabilities)", sw.Elapsed.TotalMilliseconds, true,
                $"{capabilityLines.Count} capabilities"));
        }
        catch (Exception ex)
        {
            sw.Stop();
            allOk = false;
            timings.Add(new CommandTiming("osdp_CAP (PD Capabilities)", sw.Elapsed.TotalMilliseconds, false,
                $"{ex.GetType().Name}: {ex.Message}"));
        }

        // --- osdp_ACURXSIZE ------------------------------------------------------
        // Tells the PD how large a reply packet the ACU can accept, which is the only control the
        // ACU has over PD -> ACU fragmentation. Sent during the cleartext interrogation so it is in
        // effect for the pairing exchange, where message 2 is the dominant cost.
        if (advertiseReceiveSize && _config.AcuReceiveSize > 0)
        {
            sw = Stopwatch.StartNew();
            try
            {
                bool ok = await _panel.ACUReceiveSize(_connectionId, _config.Address, _config.AcuReceiveSize);
                sw.Stop();
                if (!ok) allOk = false;
                timings.Add(new CommandTiming("osdp_ACURXSIZE (advertise ACU receive size)",
                    sw.Elapsed.TotalMilliseconds, ok,
                    ok ? $"{_config.AcuReceiveSize} bytes" : "PD did not ACK"));
            }
            catch (Exception ex)
            {
                sw.Stop();
                allOk = false;
                timings.Add(new CommandTiming("osdp_ACURXSIZE (advertise ACU receive size)",
                    sw.Elapsed.TotalMilliseconds, false, $"{ex.GetType().Name}: {ex.Message}"));
            }
        }

        // --- osdp_KEYSET ---------------------------------------------------------
        // Only meaningful on a secured session. The SAME key is re-installed deliberately: writing a
        // fresh random key would leave the PD holding a key this run has not recorded, and recovering
        // from that needs a manual PD reset. This still exercises the real KEYSET path and its reply.
        if (keysetKey is not null)
        {
            sw = Stopwatch.StartNew();
            try
            {
                var keyType = keysetKey.Length == 32
                    ? KeyType.SecureChannelBaseKeyAes256
                    : KeyType.SecureChannelBaseKey;
                bool ok = await _panel.EncryptionKeySet(_connectionId, _config.Address,
                    new EncryptionKeyConfiguration(keyType, keysetKey));
                sw.Stop();
                if (!ok) allOk = false;
                timings.Add(new CommandTiming("osdp_KEYSET (re-install same SCBK)",
                    sw.Elapsed.TotalMilliseconds, ok, ok ? $"{keyType}, {keysetKey.Length} bytes" : "PD returned false"));
            }
            catch (Exception ex)
            {
                sw.Stop();
                allOk = false;
                timings.Add(new CommandTiming("osdp_KEYSET (re-install same SCBK)",
                    sw.Elapsed.TotalMilliseconds, false, $"{ex.GetType().Name}: {ex.Message}"));
            }
        }

        return new DeviceQuery
        {
            Identity = identity,
            Capabilities = capabilityLines,
            Timings = timings,
            ReceiveBufferSize = receiveBuffer,
            LargestCombinedMessageSize = largestCombined,
            Succeeded = allOk,
        };
    }

    /// <summary>
    /// Chooses the pairing fragment size from what the PD reported, honouring an explicit override.
    /// </summary>
    private (ushort Size, string Rationale) ResolveFragmentSize(DeviceQuery query)
    {
        if (_config.FragmentSizeOverride is { } forced)
        {
            return (forced, $"forced by --fragment-size {forced}");
        }

        if (query?.ReceiveBufferSize is { } buffer && buffer > 64)
        {
            ushort usable = BenchmarkConfig.MaxFragmentForPacket((ushort)Math.Min(buffer, ushort.MaxValue));
            if (usable >= 64)
            {
                ushort size = Math.Min(usable, BenchmarkConfig.MaxFragmentSize);
                string rationale = size < usable
                    ? $"PD receive buffer {buffer} B packet -> {usable} B payload " +
                      $"(Message.CalculateMaximumMessageSize less the {BenchmarkConfig.PairingFragmentHeaderSize} B " +
                      $"fragment header), capped at {BenchmarkConfig.MaxFragmentSize} B"
                    : $"PD receive buffer {buffer} B packet -> {usable} B payload " +
                      $"(Message.CalculateMaximumMessageSize less the {BenchmarkConfig.PairingFragmentHeaderSize} B " +
                      $"fragment header)";
                return (size, rationale);
            }
        }

        return (BenchmarkConfig.DefaultFragmentSize,
            query?.ReceiveBufferSize is null
                ? "PD did not report a receive buffer size; using the default"
                : $"PD reported an unusably small receive buffer ({query.ReceiveBufferSize} B); using the default");
    }

    private static void PrintCommandTimings(IReadOnlyList<CommandTiming> timings, string indent = "         ")
    {
        if (timings is null) return;
        foreach (var t in timings)
        {
            Console.WriteLine($"{indent}{(t.Success ? "  " : "! ")}{t.Ms,8:0.0} ms  {t.Name}" +
                              (t.Success ? "" : $"  <- {t.Detail}"));
        }
    }

    private static void PrintProfile(PairingProfile profile)
    {
        if (profile is null) return;

        Console.WriteLine("         timing profile:");
        foreach (var seg in profile.Segments)
        {
            double pct = profile.TotalMs <= 0 ? 0 : 100.0 * seg.Ms / profile.TotalMs;
            Console.WriteLine($"           {seg.Ms,8:0.0} ms  {pct,5:0.0}%  {seg.Name}");
        }
        Console.WriteLine($"           {profile.TotalMs,8:0.0} ms  100.0%  total exchange");
    }

    private async Task<byte[]> DeriveScbkForSc2Async()
    {
        // Try a few times to establish a key so the SC2 phase has something to work with.
        for (int attempt = 1; attempt <= 3; attempt++)
        {
            var (trial, scbk) = await RunPairingTrialAsync(-attempt);
            if (trial.Success && scbk is not null)
            {
                Console.WriteLine($"  derived SCBK on attempt {attempt} ({trial.ElapsedMs:0.0} ms).");
                PrintProfile(trial.Profile);
                return scbk;
            }
            Console.WriteLine($"  attempt {attempt} failed: {trial.Detail}");
            await Task.Delay(_config.InterTrialDelay);
        }
        return null;
    }

    // ---- SC2 initialization trial ------------------------------------------

    private async Task<TrialResult> RunSc2InitTrialAsync(int index, byte[] scbk)
    {
        // Start from a clean slate: removing the device and re-adding it below builds a fresh
        // device proxy (sequence numbers and secure-channel state reset), so each trial forces a
        // new CHLNG / CCRYPT / SCRYPT handshake. Do not call ResetDevice here — it throws once the
        // device has been removed, and it would only re-add the device with its previous settings.
        _panel.RemoveDevice(_connectionId, _config.Address);
        _isConnected = false;
        _isSecure = false;

        var established = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
        _secureEstablished = established;

        var sw = Stopwatch.StartNew();
        _panel.AddDevice(_connectionId, _config.Address, useCrc: true, useSecureChannel: true,
            secureChannelKey: scbk, secureChannelVersion: SecureChannelVersion.V2,
            skipConnectBackoff: TimeSpan.FromSeconds(3));

        var completed = await Task.WhenAny(established.Task, Task.Delay(_config.Sc2Timeout));
        sw.Stop();
        _secureEstablished = null;

        TrialResult result;
        if (completed == established.Task)
        {
            // Channel is up; exercise the commands an ACU actually issues on a fresh session and
            // time each reply. KEYSET re-installs the same SCBK - see QueryDeviceAsync.
            var query = await QueryDeviceAsync(keysetKey: scbk);
            result = new TrialResult(index, true, sw.Elapsed.TotalMilliseconds, "secure channel established",
                null, null, query.Timings);
        }
        else
        {
            string cat = _isConnected ? "Timeout (connected, not secure)" : "Timeout (never connected)";
            string detail = _isConnected
                ? $"connected but secure channel not established within {_config.Sc2Timeout.TotalSeconds:0}s"
                : $"device never came online within {_config.Sc2Timeout.TotalSeconds:0}s";
            result = new TrialResult(index, false, sw.Elapsed.TotalMilliseconds, detail, cat);
        }

        _panel.RemoveDevice(_connectionId, _config.Address);
        return result;
    }

    // ---- Bus helpers -------------------------------------------------------

    private void ResetToCleartext()
    {
        // See RunSc2InitTrialAsync: remove + re-add is what resets the proxy state. ResetDevice
        // would throw here, since the device is already gone.
        _panel.RemoveDevice(_connectionId, _config.Address);
        _isConnected = false;
        _isSecure = false;
        // Cleartext device so the pairing (which rides cleartext osdp_PAIR) can proceed.
        //
        // skipConnectBackoff matters here: without it the freshly re-added device sits out the
        // offline back-off before the bus polls it, so it is not online within OnlineWait and the
        // first pairing attempt fails with "PD did not answer cleartext polls". The SC2 phase
        // always passed this; the pairing phase did not, which is why trial #1 reliably failed and
        // the next attempt succeeded. secureChannelVersion is irrelevant with useSecureChannel:false
        // but the overload that accepts skipConnectBackoff requires it.
        _panel.AddDevice(_connectionId, _config.Address, useCrc: true, useSecureChannel: false,
            secureChannelKey: null, secureChannelVersion: SecureChannelVersion.V2,
            skipConnectBackoff: TimeSpan.FromSeconds(3));
    }

    private async Task<bool> WaitForOnlineAsync(TimeSpan window)
    {
        var deadline = DateTime.UtcNow + window;
        while (DateTime.UtcNow < deadline)
        {
            if (_panel.IsOnline(_connectionId, _config.Address)) return true;
            await Task.Delay(100);
        }
        return _panel.IsOnline(_connectionId, _config.Address);
    }

    private void OnConnectionStatusChanged(object sender, ControlPanel.ConnectionStatusEventArgs e)
    {
        if (e.Address != _config.Address) return;
        _isConnected = e.IsConnected;
        _isSecure = e.IsSecureChannelEstablished;
        if (e.IsConnected && e.IsSecureChannelEstablished)
        {
            _secureEstablished?.TrySetResult(true);
        }
    }

    // ---- Console output ----------------------------------------------------

    private void PrintHeader()
    {
        Console.WriteLine("OSDP SC2 ACU Benchmark");
        Console.WriteLine($"  Port {_config.Port} @ {_config.Baud} baud, PD address {_config.Address}");
        Console.WriteLine($"  Mode: {_config.Mode}");
    }

    private static void ReportTrial(TrialResult t)
    {
        string tag = t.Success ? "OK  " : "FAIL";
        string label = t.Index < 0 ? "warmup" : t.Index.ToString().PadLeft(3);
        Console.WriteLine($"  [{tag}] #{label}  {t.ElapsedMs,8:0.0} ms  {t.Detail}");
    }

    private static void PrintSummary(string phase, TrialStats s, IReadOnlyList<TrialResult> trials, bool ran)
    {
        if (!ran) return;
        Console.WriteLine($"\n{phase} summary:");
        Console.WriteLine($"  success rate : {s.Successes}/{s.Total} ({s.SuccessRate:0.0}%)");
        if (s.Successes > 0)
        {
            Console.WriteLine($"  latency (ms) : min {s.MinMs:0.0} | median {s.MedianMs:0.0} | " +
                              $"mean {s.MeanMs:0.0} | p95 {s.P95Ms:0.0} | max {s.MaxMs:0.0}");
        }
    }
}

// =============================================================================
//  Markdown report
// =============================================================================

internal static class ReportWriter
{
    /// <summary>
    /// Reports what the PD said about itself in cleartext before pairing, and how that set the
    /// pairing fragment size.
    /// </summary>
    private static void AppendDiscovery(StringBuilder sb, DeviceQuery discovery, ushort fragmentSize,
        string fragmentRationale)
    {
        sb.AppendLine("## PD Interrogation (pre-pairing, cleartext)");
        sb.AppendLine();

        if (discovery is null)
        {
            sb.AppendLine("The PD was not interrogated.");
            sb.AppendLine();
            return;
        }

        sb.AppendLine($"Identity: {discovery.Identity ?? "_not reported_"}");
        sb.AppendLine();

        sb.AppendLine("| Command | Reply interval (ms) | Result |");
        sb.AppendLine("|---|---:|---|");
        foreach (var t in discovery.Timings)
        {
            sb.AppendLine($"| `{t.Name}` | {t.Ms:0.0} | {(t.Success ? "OK" : "FAILED - " + t.Detail)} |");
        }
        sb.AppendLine();

        if (discovery.Capabilities.Count > 0)
        {
            sb.AppendLine("Reported capabilities:");
            sb.AppendLine();
            foreach (var line in discovery.Capabilities)
            {
                sb.AppendLine($"- {line}");
            }
            sb.AppendLine();
        }

        sb.AppendLine("### Fragment size derivation");
        sb.AppendLine();
        sb.AppendLine($"- Chosen pairing fragment size: **{fragmentSize} bytes** ({fragmentRationale}).");
        sb.AppendLine($"- `ReceiveBufferSize` describes the **whole OSDP packet**, not the payload. The " +
                      $"framing is removed by `Message.CalculateMaximumMessageSize` (header, message code, " +
                      $"CRC, and the security block and authentication tag when secured), then a further " +
                      $"{BenchmarkConfig.PairingFragmentHeaderSize} bytes for the multipart fragment header " +
                      $"carried inside the payload.");
        sb.AppendLine($"- Ceiling is the OSDP maximum packet of {BenchmarkConfig.MaxPacketSize} bytes, " +
                      $"giving a payload ceiling of {BenchmarkConfig.MaxFragmentSize} bytes.");
        if (discovery.LargestCombinedMessageSize is { } combined)
        {
            sb.AppendLine($"- `LargestCombinedMessageSize` is {combined} bytes, which bounds the whole " +
                          $"reassembled pairing message rather than any single fragment.");
        }
        sb.AppendLine();
    }

    /// <summary>
    /// Reports the reply interval for the commands issued on each established SC2 session.
    /// </summary>
    private static void AppendCommandIntervals(StringBuilder sb, IReadOnlyList<TrialResult> sc2)
    {
        var withCommands = sc2.Where(t => t.Commands is { Count: > 0 }).ToArray();

        sb.AppendLine("## Command Reply Intervals (per SC2 session)");
        sb.AppendLine();

        if (withCommands.Length == 0)
        {
            sb.AppendLine("No commands were issued on an established session.");
            sb.AppendLine();
            return;
        }

        // Per-command aggregate across sessions.
        var names = withCommands.SelectMany(t => t.Commands).Select(c => c.Name).Distinct().ToArray();

        sb.AppendLine("Aggregate across sessions:");
        sb.AppendLine();
        sb.AppendLine("| Command | n | OK | Median (ms) | Mean (ms) | Min (ms) | Max (ms) |");
        sb.AppendLine("|---|---:|---:|---:|---:|---:|---:|");
        foreach (var name in names)
        {
            var samples = withCommands
                .SelectMany(t => t.Commands)
                .Where(c => c.Name == name)
                .ToArray();
            var ok = samples.Where(c => c.Success).Select(c => c.Ms).OrderBy(x => x).ToArray();
            if (ok.Length == 0)
            {
                sb.AppendLine($"| `{name}` | {samples.Length} | 0 | - | - | - | - |");
                continue;
            }
            double median = ok.Length % 2 == 1
                ? ok[ok.Length / 2]
                : (ok[ok.Length / 2 - 1] + ok[ok.Length / 2]) / 2.0;
            sb.AppendLine($"| `{name}` | {samples.Length} | {ok.Length} | {median:0.0} | {ok.Average():0.0} | " +
                          $"{ok[0]:0.0} | {ok[^1]:0.0} |");
        }
        sb.AppendLine();

        sb.AppendLine("Per session:");
        sb.AppendLine();
        sb.Append("| Session |");
        foreach (var name in names) sb.Append($" {name} (ms) |");
        sb.AppendLine();
        sb.Append("|---:|");
        foreach (var _ in names) sb.Append("---:|");
        sb.AppendLine();
        foreach (var trial in withCommands)
        {
            sb.Append($"| {trial.Index} |");
            foreach (var name in names)
            {
                var c = trial.Commands.FirstOrDefault(x => x.Name == name);
                sb.Append(c is null ? " - |" : c.Success ? $" {c.Ms:0.0} |" : " FAIL |");
            }
            sb.AppendLine();
        }
        sb.AppendLine();

        sb.AppendLine("These intervals are ACU-side round trips: command queued to reply parsed. They " +
                      "include the bus polling interval, so they are an upper bound on the PD's own " +
                      "processing time rather than a measurement of it.");
        sb.AppendLine();
    }

    /// <summary>
    /// Emits the per-operation timing breakdown for each pairing that ran to completion. This is
    /// the section that answers "where does the time go when pairing an embedded PD".
    /// </summary>
    private static void AppendPairingProfiles(StringBuilder sb, BenchmarkConfig config,
        IReadOnlyList<TrialResult> pairing)
    {
        var profiled = pairing.Where(t => t.Profile is not null).ToArray();

        sb.AppendLine("## Pairing Timing Profile");
        sb.AppendLine();

        if (profiled.Length == 0)
        {
            sb.AppendLine("No pairing exchange ran to completion, so no timing breakdown is available.");
            sb.AppendLine();
            return;
        }

        // Theoretical byte time, useful for separating link cost from compute cost.
        double bitsPerByte = 10.0; // 8N1: start + 8 data + stop
        double msPerByte = 1000.0 * bitsPerByte / config.Baud;

        sb.AppendLine($"Wire timings below are bounded by the link itself: at {config.Baud} baud (8N1) a " +
                      $"single byte costs about {msPerByte:0.000} ms, so a 128-byte fragment costs " +
                      $"about {128 * msPerByte:0.0} ms on the wire before any PD processing.");
        sb.AppendLine();

        foreach (var trial in profiled)
        {
            var p = trial.Profile;

            // Negative indices are SCBK-derivation fallback attempts, not numbered phase-1 trials.
            string label = trial.Index < 0
                ? $"SCBK-derivation attempt {-trial.Index}"
                : $"Pairing trial #{trial.Index}";
            sb.AppendLine($"### {label} - {p.TotalMs:0.0} ms total");
            sb.AppendLine();

            sb.AppendLine("| Operation | Attributed to | Fragments | Duration (ms) | % of total |");
            sb.AppendLine("|---|---|---:|---:|---:|");
            foreach (var seg in p.Segments)
            {
                string frags = seg.Fragments > 0 ? seg.Fragments.ToString() : "-";
                double pct = p.TotalMs <= 0 ? 0 : 100.0 * seg.Ms / p.TotalMs;
                sb.AppendLine($"| {seg.Name} | {seg.Attribution} | {frags} | {seg.Ms:0.0} | {pct:0.0}% |");
            }
            sb.AppendLine($"| **Total exchange** | | | **{p.TotalMs:0.0}** | **100.0%** |");
            sb.AppendLine();

            // Roll the segments up by what they stress, so the headline question is answerable.
            var byAttribution = p.Segments
                .GroupBy(s => s.Attribution)
                .Select(g => (Attribution: g.Key, Ms: g.Sum(s => s.Ms)))
                .OrderByDescending(x => x.Ms)
                .ToArray();

            sb.AppendLine("Rolled up by cost centre:");
            sb.AppendLine();
            sb.AppendLine("| Cost centre | Duration (ms) | % of total |");
            sb.AppendLine("|---|---:|---:|");
            foreach (var (attribution, ms) in byAttribution)
            {
                double pct = p.TotalMs <= 0 ? 0 : 100.0 * ms / p.TotalMs;
                sb.AppendLine($"| {attribution} | {ms:0.0} | {pct:0.0}% |");
            }
            sb.AppendLine();

            if (p.HasCollapsedSpans)
            {
                sb.AppendLine("> At least one message produced a single progress callback, so its wire " +
                              "time could not be separated from the adjacent turnaround and is folded " +
                              "into it. Lower `--fragment-size` to resolve those spans.");
                sb.AppendLine();
            }
        }

        sb.AppendLine("### How to read these numbers");
        sb.AppendLine();
        sb.AppendLine("- **ACU crypto** spans are measured on this machine, not on the PD. They are a " +
                      "floor for the ACU side and say nothing about the embedded device.");
        sb.AppendLine("- **PD turnaround** is the interval between the ACU finishing a request and the " +
                      "first fragment of the reply arriving. It contains the PD's own ML-KEM / ML-DSA " +
                      "work *plus* the ACU's polling interval, because the reply is only observed on " +
                      "the next poll. Treat it as an upper bound on PD compute, not a measurement of it.");
        sb.AppendLine("- **Serial link** spans scale with baud rate and fragment count. Compare them " +
                      "against the theoretical byte time above to see whether the link or the device " +
                      "is the constraint.");
        sb.AppendLine("- Timestamps are taken synchronously on the reporting thread, so they exclude " +
                      "thread-pool scheduling delay.");
        sb.AppendLine();
    }

    public static string Build(
        BenchmarkConfig config,
        byte[] scbk,
        IReadOnlyList<TrialResult> pairing, TrialStats pairingStats,
        IReadOnlyList<TrialResult> sc2, TrialStats sc2Stats,
        IReadOnlyList<TrialResult> pairingAttempts,
        DeviceQuery discovery, ushort fragmentSize, string fragmentRationale)
    {
        var sb = new StringBuilder();
        var now = DateTimeOffset.Now;

        sb.AppendLine("# OSDP SC2 ACU Benchmark Report");
        sb.AppendLine();
        sb.AppendLine($"Generated: {now:yyyy-MM-dd HH:mm:ss zzz}");
        sb.AppendLine();

        // ---- Configuration ----
        sb.AppendLine("## Configuration");
        sb.AppendLine();
        sb.AppendLine("| Setting | Value |");
        sb.AppendLine("|---|---|");
        sb.AppendLine($"| Serial port | `{config.Port}` |");
        sb.AppendLine($"| Baud rate | {config.Baud} |");
        sb.AppendLine($"| PD address | {config.Address} |");
        sb.AppendLine($"| Mode | {config.Mode} |");
        sb.AppendLine($"| Pairing trials | {config.PairIterations} |");
        sb.AppendLine($"| Pairing fragment size (ACU -> PD) | {fragmentSize} bytes ({fragmentRationale}) |");
        sb.AppendLine($"| Advertised ACU receive size | {(config.AcuReceiveSize > 0 ? $"{config.AcuReceiveSize} bytes (osdp_ACURXSIZE)" : "not sent")} |");
        sb.AppendLine($"| SC2 trials | {config.Sc2Iterations} |");
        sb.AppendLine($"| Pairing timeout | {config.PairTimeout.TotalSeconds:0} s |");
        sb.AppendLine($"| SC2 timeout | {config.Sc2Timeout.TotalSeconds:0} s |");
        sb.AppendLine($"| SC2 key source | {(config.PresharedScbk is not null ? "pre-shared (--scbk)" : "derived by pairing")} |");
        sb.AppendLine($"| Trust anchor | OSDP.Net demo CA |");
        sb.AppendLine($"| .NET runtime | {Environment.Version} |");
        sb.AppendLine($"| OS | {Environment.OSVersion} |");
        sb.AppendLine();

        // ---- Headline ----
        sb.AppendLine("## Response Rate Summary");
        sb.AppendLine();
        sb.AppendLine("| Phase | Success rate | Median | Mean | p95 | Min | Max |");
        sb.AppendLine("|---|---|---|---|---|---|---|");
        if (config.RunPairing)
            sb.AppendLine(SummaryRow("Asymmetric pairing", pairingStats));
        if (config.RunSc2 && sc2.Count > 0)
            sb.AppendLine(SummaryRow("SC2 messaging init", sc2Stats));
        sb.AppendLine();

        // ---- Pairing detail ----
        if (config.RunPairing)
        {
            AppendPhaseSection(sb, "Phase 1 - Asymmetric Pairing", pairing, pairingStats,
                "Each trial runs the full osdp_PAIR / osdp_PAIRR exchange (ML-KEM-768 + ML-DSA-44) " +
                "over cleartext, deriving a fresh 32-byte SCBK. The PD is returned to a cleartext " +
                "session between trials.");
        }

        // ---- PD interrogation ----
        AppendDiscovery(sb, discovery, fragmentSize, fragmentRationale);

        // ---- Pairing timing profile ----
        if (config.RunPairing)
        {
            AppendPairingProfiles(sb, config, pairingAttempts);
        }

        // ---- Per-session command reply intervals ----
        if (config.RunSc2 && sc2.Count > 0)
        {
            AppendCommandIntervals(sb, sc2);
        }

        // ---- SC2 detail ----
        if (config.RunSc2 && sc2.Count > 0)
        {
            AppendPhaseSection(sb, "Phase 2 - SC2 Messaging Initialization", sc2, sc2Stats,
                "Each trial removes the device, resets its message sequence, then re-adds it under " +
                "Secure Channel v2 with the derived SCBK and measures the time to a fully established " +
                "secure channel (CHLNG / CCRYPT / SCRYPT handshake).");
        }

        // ---- Notes ----
        sb.AppendLine("## Notes & Caveats");
        sb.AppendLine();
        sb.AppendLine("- \"Response rate\" is the fraction of trials that completed successfully (a derived key for pairing; an established secure channel for SC2 init).");
        sb.AppendLine("- Latency is wall-clock time for the phase, measured on the ACU. At lower baud rates the large pairing messages (~5-8 KB) dominate pairing latency.");
        sb.AppendLine("- Pairing between trials depends on the PD accepting re-pairing (`RePairingPolicy.Allow`). A PD that stays in secure mode after a prior pairing may not answer cleartext polls, which shows up as a timeout.");
        sb.AppendLine("- The SC2 phase reuses a single SCBK; it isolates the symmetric handshake from the (heavier) pairing exchange.");
        sb.AppendLine("- `osdp_KEYSET` re-installs the **same** SCBK rather than rotating to a fresh key. That keeps the session usable for the next cycle; a real key rotation would leave the PD holding a key this run has not recorded.");
        sb.AppendLine("- **Treat these figures as a best case.** When the PD is the PDConsole simulator running on a PC, its crypto and reply latency are the fastest this will plausibly go. Embedded PD hardware will be slower on every PD-side span - the post-quantum pairing operations especially - while the serial-link spans should carry over largely unchanged.");
        sb.AppendLine();

        return sb.ToString();
    }

    private static string SummaryRow(string name, TrialStats s)
    {
        if (s.Successes == 0)
            return $"| {name} | {s.Successes}/{s.Total} ({s.SuccessRate:0.0}%) | - | - | - | - | - |";
        return $"| {name} | {s.Successes}/{s.Total} ({s.SuccessRate:0.0}%) | {s.MedianMs:0.0} ms | " +
               $"{s.MeanMs:0.0} ms | {s.P95Ms:0.0} ms | {s.MinMs:0.0} ms | {s.MaxMs:0.0} ms |";
    }

    private static void AppendPhaseSection(StringBuilder sb, string title,
        IReadOnlyList<TrialResult> trials, TrialStats stats, string description)
    {
        sb.AppendLine($"## {title}");
        sb.AppendLine();
        sb.AppendLine(description);
        sb.AppendLine();

        sb.AppendLine("| Metric | Value |");
        sb.AppendLine("|---|---|");
        sb.AppendLine($"| Trials | {stats.Total} |");
        sb.AppendLine($"| Successes | {stats.Successes} |");
        sb.AppendLine($"| Failures | {stats.Failures} |");
        sb.AppendLine($"| Success rate | {stats.SuccessRate:0.0}% |");
        if (stats.Successes > 0)
        {
            sb.AppendLine($"| Min latency | {stats.MinMs:0.0} ms |");
            sb.AppendLine($"| Median latency | {stats.MedianMs:0.0} ms |");
            sb.AppendLine($"| Mean latency | {stats.MeanMs:0.0} ms |");
            sb.AppendLine($"| p95 latency | {stats.P95Ms:0.0} ms |");
            sb.AppendLine($"| Max latency | {stats.MaxMs:0.0} ms |");
        }
        sb.AppendLine();

        // Failure breakdown
        var failures = trials.Where(t => !t.Success).ToList();
        if (failures.Count > 0)
        {
            sb.AppendLine("### Failure breakdown");
            sb.AppendLine();
            sb.AppendLine("| Category | Count |");
            sb.AppendLine("|---|---|");
            foreach (var g in failures.GroupBy(f => f.FailureCategory ?? "Unknown")
                                      .OrderByDescending(g => g.Count()))
            {
                sb.AppendLine($"| {g.Key} | {g.Count()} |");
            }
            sb.AppendLine();
        }

        // Per-trial log
        sb.AppendLine("### Per-trial results");
        sb.AppendLine();
        sb.AppendLine("| # | Result | Latency (ms) | Detail |");
        sb.AppendLine("|---|---|---|---|");
        foreach (var t in trials)
        {
            string idx = t.Index < 0 ? "warmup" : t.Index.ToString();
            string res = t.Success ? "OK" : "FAIL";
            string detail = (t.Detail ?? "").Replace("|", "\\|");
            sb.AppendLine($"| {idx} | {res} | {t.ElapsedMs:0.0} | {detail} |");
        }
        sb.AppendLine();
    }
}