feat(net): PacketHeader + PacketHeaderFlags + Hash32 checksum (Phase 4.2)

Adds the 20-byte AC UDP packet header struct + pack/unpack + its
checksum helper, and the Hash32 primitive the checksum uses.

Hash32 (Cryptography/Hash32.cs):
  - Seeds accumulator with length << 16
  - Sums input as little-endian uint32s word-aligned
  - Folds any trailing 1-3 bytes via descending shift (24 → 16 → 8)
  - Hand-computed golden values for 4-byte, 5-byte, and each 1/2/3
    tail-byte case — no oracle needed, algorithm is simple enough to
    verify by tracing

PacketHeader (Packets/PacketHeader.cs):
  - Pack/Unpack: Sequence, Flags, Checksum, Id, Time, DataSize, Iteration
    (20 bytes, little-endian on the wire)
  - CalculateHeaderHash32: substitutes the 0xBADD70DD sentinel for the
    Checksum field before hashing (matches AC retail + ACE convention —
    without it the checksum would chicken-and-egg on itself). Uses a
    local struct copy so the real Checksum isn't mutated on the caller.
  - HasFlag for bitmask queries

PacketHeaderFlags (Packets/PacketHeaderFlags.cs):
  - Full flag enum from ACE reference: Retransmission, EncryptedChecksum,
    BlobFragments, ServerSwitch, ConnectRequest/Response, LoginRequest,
    AckSequence, TimeSync, Disconnect, NetError, EchoRequest/Response,
    Flow, and friends

Tests (15 new, 20 total in net project, 97 across both projects):
  Hash32 (7):
    - Empty returns 0
    - 4-byte known value (hand-computed from bit layout)
    - 5-byte value with one tail byte
    - 1/2/3 tail-byte boundary cases (verifies 24/16/8 shift ordering)
    - Determinism
  PacketHeader (8):
    - Pack/Unpack round-trip preserving all 7 fields
    - Pack writes little-endian wire format in byte order
    - HasFlag single and multi-bit
    - CalculateHeaderHash32 invariance under Checksum field changes
      (the critical property — verifies the BADD sentinel substitution)
    - CalculateHeaderHash32 doesn't mutate
    - CalculateHeaderHash32 determinism
    - Unpack/Pack size-check throw

User confirmed an ACE server is running on localhost for the future
Phase 4.6 live integration step. Credentials will be read from env
vars at runtime, never committed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/AcDream.Core.Net/Cryptography/Hash32.cs

@@ -0,0 +1,41 @@
+using System.Buffers.Binary;
+
+namespace AcDream.Core.Net.Cryptography;
+
+/// <summary>
+/// Simple 32-bit checksum used by the AC packet header. The algorithm is:
+/// <list type="bullet">
+///   <item>Seed the accumulator with <c>length &lt;&lt; 16</c>.</item>
+///   <item>Sum the input as little-endian uint32s, four bytes at a time.</item>
+///   <item>Fold any tail bytes (length not divisible by 4) into the top of
+///         the accumulator with a descending left-shift per byte (24, 16, 8, 0).</item>
+/// </list>
+/// Reimplemented from reading ACE's AGPL reference
+/// (<c>references/ACE/Source/ACE.Common/Cryptography/Hash32.cs</c>). See
+/// <c>NOTICE.md</c> for the attribution policy.
+/// </summary>
+public static class Hash32
+{
+    public static uint Calculate(ReadOnlySpan<byte> data)
+    {
+        int length = data.Length;
+        uint checksum = (uint)length << 16;
+
+        int wordAligned = length & ~3;
+        for (int i = 0; i < wordAligned; i += 4)
+        {
+            checksum += BinaryPrimitives.ReadUInt32LittleEndian(data.Slice(i));
+        }
+
+        // Tail bytes (0, 1, 2, or 3 bytes) with descending shift: first tail
+        // byte goes into bits 24..31, second into 16..23, third into 8..15.
+        int shift = 24;
+        for (int j = wordAligned; j < length; j++)
+        {
+            checksum += (uint)data[j] << shift;
+            shift -= 8;
+        }
+
+        return checksum;
+    }
+}

src/AcDream.Core.Net/Packets/PacketHeader.cs

@@ -0,0 +1,99 @@
+using System.Buffers.Binary;
+using AcDream.Core.Net.Cryptography;
+
+namespace AcDream.Core.Net.Packets;
+
+/// <summary>
+/// The fixed 20-byte header that prefixes every AC UDP packet. Fields are
+/// little-endian on the wire.
+///
+/// <para>
+/// Layout (byte offsets):
+/// <code>
+///    0  Sequence   uint32   Packet sequence number (client- or server-side monotonic)
+///    4  Flags      uint32   PacketHeaderFlags bitmask
+///    8  Checksum   uint32   Header+body checksum (XOR'd with ISAAC keystream when the
+///                           EncryptedChecksum flag is set)
+///   12  Id         uint16   Session/connection id
+///   14  Time       uint16   Server time echo (used for latency tracking)
+///   16  Size       uint16   Body length in bytes (excludes this 20-byte header)
+///   18  Iteration  uint16   Retransmit iteration counter
+/// </code>
+/// </para>
+///
+/// Reimplemented from ACE's AGPL reference; see <c>NOTICE.md</c>.
+/// </summary>
+public struct PacketHeader
+{
+    public const int Size = 20;
+
+    /// <summary>
+    /// Placeholder checksum value that every header uses while its own Hash32
+    /// checksum is being calculated. The real checksum replaces this sentinel
+    /// before transmit. Matches AC's retail + ACE's convention byte-for-byte.
+    /// </summary>
+    public const uint ChecksumPlaceholder = 0xBADD70DDu;
+
+    public uint Sequence;
+    public PacketHeaderFlags Flags;
+    public uint Checksum;
+    public ushort Id;
+    public ushort Time;
+    public ushort DataSize;
+    public ushort Iteration;
+
+    /// <summary>True if the header's Flags field has any of the bits in <paramref name="flags"/>.</summary>
+    public readonly bool HasFlag(PacketHeaderFlags flags) => (Flags & flags) != 0;
+
+    /// <summary>Write this header into the first 20 bytes of <paramref name="destination"/>.</summary>
+    public readonly void Pack(Span<byte> destination)
+    {
+        if (destination.Length < Size)
+            throw new ArgumentException($"destination must be at least {Size} bytes", nameof(destination));
+
+        BinaryPrimitives.WriteUInt32LittleEndian(destination.Slice(0),  Sequence);
+        BinaryPrimitives.WriteUInt32LittleEndian(destination.Slice(4),  (uint)Flags);
+        BinaryPrimitives.WriteUInt32LittleEndian(destination.Slice(8),  Checksum);
+        BinaryPrimitives.WriteUInt16LittleEndian(destination.Slice(12), Id);
+        BinaryPrimitives.WriteUInt16LittleEndian(destination.Slice(14), Time);
+        BinaryPrimitives.WriteUInt16LittleEndian(destination.Slice(16), DataSize);
+        BinaryPrimitives.WriteUInt16LittleEndian(destination.Slice(18), Iteration);
+    }
+
+    /// <summary>Read a header from the first 20 bytes of <paramref name="source"/>.</summary>
+    public static PacketHeader Unpack(ReadOnlySpan<byte> source)
+    {
+        if (source.Length < Size)
+            throw new ArgumentException($"source must be at least {Size} bytes", nameof(source));
+
+        return new PacketHeader
+        {
+            Sequence  =                     BinaryPrimitives.ReadUInt32LittleEndian(source.Slice(0)),
+            Flags     = (PacketHeaderFlags)BinaryPrimitives.ReadUInt32LittleEndian(source.Slice(4)),
+            Checksum  =                     BinaryPrimitives.ReadUInt32LittleEndian(source.Slice(8)),
+            Id        =                     BinaryPrimitives.ReadUInt16LittleEndian(source.Slice(12)),
+            Time      =                     BinaryPrimitives.ReadUInt16LittleEndian(source.Slice(14)),
+            DataSize  =                     BinaryPrimitives.ReadUInt16LittleEndian(source.Slice(16)),
+            Iteration =                     BinaryPrimitives.ReadUInt16LittleEndian(source.Slice(18)),
+        };
+    }
+
+    /// <summary>
+    /// Compute the Hash32 of this header with the Checksum field replaced by
+    /// <see cref="ChecksumPlaceholder"/>. Used by both the transmit path (to
+    /// fill in the real checksum before sending) and the receive path (to
+    /// verify a packet's checksum matches the one we'd compute).
+    ///
+    /// Returned value is the header's contribution to the overall packet
+    /// checksum; the full packet checksum also folds in body fragments.
+    /// </summary>
+    public readonly uint CalculateHeaderHash32()
+    {
+        Span<byte> buffer = stackalloc byte[Size];
+        // Save and restore Checksum via a local copy rather than mutating this.
+        var saved = this;
+        saved.Checksum = ChecksumPlaceholder;
+        saved.Pack(buffer);
+        return Hash32.Calculate(buffer);
+    }
+}

src/AcDream.Core.Net/Packets/PacketHeaderFlags.cs

@@ -0,0 +1,35 @@
+namespace AcDream.Core.Net.Packets;
+
+/// <summary>
+/// Flags field in a 20-byte <see cref="PacketHeader"/>. Each flag gates the
+/// presence of an optional body section or signals a handshake/control
+/// operation. Reimplemented from ACE's AGPL reference; values are
+/// wire-format facts about AC's retail protocol.
+/// </summary>
+[Flags]
+public enum PacketHeaderFlags : uint
+{
+    None               = 0x00000000,
+    Retransmission     = 0x00000001,
+    EncryptedChecksum  = 0x00000002,
+    BlobFragments      = 0x00000004,
+    ServerSwitch       = 0x00000100,
+    LogonServerAddr    = 0x00000200,
+    EmptyHeader1       = 0x00000400,
+    Referral           = 0x00000800,
+    RequestRetransmit  = 0x00001000,
+    RejectRetransmit   = 0x00002000,
+    AckSequence        = 0x00004000,
+    Disconnect         = 0x00008000,
+    LoginRequest       = 0x00010000,
+    WorldLoginRequest  = 0x00020000,
+    ConnectRequest     = 0x00040000,
+    ConnectResponse    = 0x00080000,
+    NetError           = 0x00100000,
+    NetErrorDisconnect = 0x00200000,
+    CICMDCommand       = 0x00400000,
+    TimeSync           = 0x01000000,
+    EchoRequest        = 0x02000000,
+    EchoResponse       = 0x04000000,
+    Flow               = 0x08000000,
+}