feat(vendor): Slice 6 buy arc — shop items are real objects, vendor selection is THE selection, and Buy works (0x005F)

Three ordered pieces in one landing (the shared controller/composition
files carry all three; the internal order was 6.1 -> 6.2 -> 6.3):

6.1 VendorShopItemMaterializer diff-merges the shop list into the live
ClientObjectTable on VendorState transitions (so client-local close and
session teardown retire the entries too) and never claims a guid it did
not add — ACE's UniqueItemsForSale can re-list a guid a player once
held (AP-163 files the collision-skip; no retail counterpart traced).
Right-click examine on shop items now routes through the ordinary
appraisal path — the 5.4 F7c blocker dissolves with the table entries.

6.2 SelectionChangeSource.Vendor: row clicks, auto-select, and examine
all flow through the canonical SelectionState; the status bar and the
existing byte-faithful StackSplitQuantityState slider light up
unmodified. VendorSplitPolicy is the single 0xDC41CB0 mask owner; the
slider VALUE seeds to 1 for exempt items while maxSplitSize keeps the
stack (the splitSize/maxSplitSize distinction, research §B.3).
Selection clears at retail's actual site — VendorItemsUI::RemoveFromShop
(pc:202848), not a CloseVendor-level clear that does not exist.

6.3 BuildBuy (0x005F): vendorGuid, count, (i32 amount, u32 guid) pairs,
and the trailing alternateCurrencyId the REAL client sends
(CM_Vendor::Event_Buy pc:689288) though ACE's reader ignores it.
TryBuy rides the EXISTING J5.2 one-request-at-a-time reservation and
completes on UseDone; the Buy button disables while a request is in
flight. The reconciliation round-trip (money property update, inventory
CreateObject, ApproachVendor refresh -> panel rebuild) is proven by a
synthetic-inbound test against existing machinery — no new owner.

Register: AP-161 narrowed (selection + examine residuals close;
staging/Sell remain; double-click-to-buy confirmed ABSENT from retail
with negative evidence cited — we match retail). AP-162 files the
conscious no-client-side-affordability-precheck deferral.

Clean-room complete solution: 11,368 passed / 4 skipped / 0 failed.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

src/AcDream.Core.Net/Messages/VendorRequests.cs

@@ -0,0 +1,110 @@
+using System;
+using System.Buffers.Binary;
+using System.Collections.Generic;
+
+namespace AcDream.Core.Net.Messages;
+
+/// <summary>
+/// Outbound vendor GameActions. Slice 6.3: Buy (<c>0x005F</c>) only — Sell
+/// (<c>0x0060</c>) is research-only scope (Slice 6 research doc §A.3), not
+/// implemented here.
+///
+/// <para>
+/// Wire layout, confirmed FOUR ways with zero disagreement (research doc
+/// §A.1: ACE's reader, Chorizite's generated reader/writer, holtburger's
+/// independent client, and the retail decompiled sender —
+/// <c>CM_Vendor::Event_Buy</c>, <c>pc:689288</c>, <c>0x006AA0F0</c>):
+/// <code>
+///   u32   0xF7B1              // GameAction envelope
+///   u32   gameActionSequence
+///   u32   0x005F               // Buy opcode
+///   u32   vendorGuid
+///   u32   itemCount
+///     per item:
+///     i32   amount             // quantity to buy (plain positive int32,
+///                               // NOT ItemProfile's packed sign-extended
+///                               // supply-count field)
+///     u32   objectGuid          // the SHOP ITEM's guid
+///   u32   alternateCurrencyId  // TRAILING — 0 for a pyreal vendor
+/// </code>
+/// </para>
+///
+/// <para>
+/// <b>The trailing <c>alternateCurrencyId</c> field — a deliberate,
+/// evidence-backed divergence from ACE.</b> Retail's client
+/// (<c>CM_Vendor::Event_Buy</c>) writes this field on EVERY Buy, after the
+/// packed item list, every time (<c>pc:689335-689336</c>). ACE's current
+/// server-side reader has the matching line PRESENT but COMMENTED OUT
+/// (<c>GameActionBuyItems.cs:32</c>,
+/// <c>//var altCurrencyWcid = message.Payload.ReadUInt32();</c>) — it simply
+/// never reads the trailing bytes. holtburger, a real client written and
+/// tested against ACE's actual accepted wire shape, omits the field
+/// entirely and round-trips fine against ACE. Both are correct for what
+/// they target: ACE demonstrably does not NEED this field today. We port
+/// the field anyway because retail — the top oracle per this project's
+/// CLAUDE.md — sends it unconditionally, it costs one <c>u32</c>, and it
+/// costs ACE nothing to ignore (forward-compatible with any future ACE
+/// build that un-comments its read). Do not "fix" this by dropping the
+/// field without re-reading
+/// <c>docs/research/2026-08-08-slice6-vendor-transactions-research.md</c>
+/// §A.1 first — that document's "Resolution of the ACE/holtburger vs.
+/// retail disagreement" section is the full reasoning trail.
+/// </para>
+/// </summary>
+public static class VendorRequests
+{
+    public const uint GameActionEnvelope = 0xF7B1u;
+    public const uint BuyOpcode = 0x005Fu;
+
+    /// <summary>
+    /// Build a Buy GameAction for <paramref name="items"/> — retail's
+    /// <c>CM_Vendor::Event_Buy(vendorGuid, &amp;list, currencyId)</c>. Slice
+    /// 6.3's Buy button always passes a ONE-entry list (retail
+    /// <c>BuySingleItem</c>, <c>pc:201661</c>, has no staging-list
+    /// dependency — see the Slice 6 research doc §B.1); the list shape is
+    /// kept general because that is literally the wire message's own shape
+    /// (a future "Buy All" staged-purchase path would reuse this builder
+    /// unchanged, not because Slice 6.3 needs it today).
+    /// </summary>
+    public static byte[] BuildBuy(
+        uint gameActionSequence,
+        uint vendorGuid,
+        IReadOnlyList<(int Amount, uint ItemGuid)> items,
+        uint alternateCurrencyId)
+    {
+        ArgumentNullException.ThrowIfNull(items);
+
+        int itemCount = items.Count;
+        byte[] body = new byte[24 + (itemCount * 8)];
+        BinaryPrimitives.WriteUInt32LittleEndian(body,            GameActionEnvelope);
+        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(4),  gameActionSequence);
+        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(8),  BuyOpcode);
+        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(12), vendorGuid);
+        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(16), (uint)itemCount);
+
+        int offset = 20;
+        for (int i = 0; i < itemCount; i++)
+        {
+            (int amount, uint itemGuid) = items[i];
+            BinaryPrimitives.WriteInt32LittleEndian(body.AsSpan(offset), amount);
+            BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(offset + 4), itemGuid);
+            offset += 8;
+        }
+
+        BinaryPrimitives.WriteUInt32LittleEndian(body.AsSpan(offset), alternateCurrencyId);
+        return body;
+    }
+
+    /// <summary>Convenience overload for the single-item Buy Slice 6.3 sends.</summary>
+    public static byte[] BuildBuy(
+        uint gameActionSequence,
+        uint vendorGuid,
+        int amount,
+        uint itemGuid,
+        uint alternateCurrencyId)
+        => BuildBuy(
+            gameActionSequence,
+            vendorGuid,
+            new[] { (amount, itemGuid) },
+            alternateCurrencyId);
+}