/// <summary>
///     HDLC address with upper/lower address components.
/// </summary>
/// <param name = "LogicalAddress">The logical device address (upper).</param>
/// <param name = "PhysicalAddress">The physical device address (lower). -1 means one-byte addressing.</param>
public readonly record struct HdlcAddress(int LogicalAddress, int PhysicalAddress = -1)
{
#region Properties
    /// <summary>Gets the encoded length of this address.</summary>
    public int EncodedLength => PhysicalAddress < 0 ? 1 : PhysicalAddress > 0x3F ? 4 : 2;

#endregion
#region Well-Known Addresses
    /// <summary>Management logical device.</summary>
    public static readonly HdlcAddress ManagementClient = new(1);
    /// <summary>Public client (no security).</summary>
    public static readonly HdlcAddress PublicClient = new(16);
    /// <summary>Default meter server address.</summary>
    public static readonly HdlcAddress MeterServer = new(1, 0);
#endregion
#region Methods
    /// <summary>Encodes this address for HDLC framing.</summary>
    public byte[] Encode()
    {
        if (PhysicalAddress < 0)
            // One-byte addressing: logical address only
            return[(byte)((LogicalAddress << 1) | 1)];
        if (PhysicalAddress <= 0x3F)
            // Two-byte addressing
            return[(byte)(LogicalAddress << 1), (byte)((PhysicalAddress << 1) | 1)];
        // Four-byte addressing
        return[(byte)(LogicalAddress << 1), (byte)((PhysicalAddress >> 7) & 0xFE), (byte)((PhysicalAddress << 1) & 0xFE), (byte)(((PhysicalAddress & 0x7F) << 1) | 1)];
    }

    /// <summary>Decodes an HDLC address from raw bytes.</summary>
    public static Result<HdlcAddress> Decode(ReadOnlySpan<byte> source)
    {
        if (source.Length < 1)
            return PsemError.Framing("Empty HDLC address");
        // Check if single-byte address (bit 0 set = last byte)
        if ((source[0] & 1) == 1)
            return new HdlcAddress(source[0] >> 1);
        if (source.Length < 2)
            return PsemError.Framing("Truncated HDLC address");
        var logical = source[0] >> 1;
        if ((source[1] & 1) == 1)
            return new HdlcAddress(logical, source[1] >> 1);
        if (source.Length < 4)
            return PsemError.Framing("Truncated 4-byte HDLC address");
        var physical = ((source[1] & 0xFE) << 6) | ((source[2] & 0xFE) >> 1);
        return new HdlcAddress(logical, physical);
    }

    /// <inheritdoc/>
    public override string ToString() => PhysicalAddress < 0 ? $"[{LogicalAddress}]" : $"[{LogicalAddress}/{PhysicalAddress}]";
#endregion
}