docs(plan): Slice 6 buy-arc contract — selection coupling root cause, 0x005F wire, retail's no-double-click truth

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/plans/2026-07-23-world-interaction-completion.md

@@ -631,3 +631,60 @@ commit). Slice gate (user, connected, ~3 min): approach a Holtburg
 vendor, use them, the authored panel opens on the browse tab with
 retail-correct items/icons/prices; category tabs filter; walking out of
 range closes the panel by itself; nothing is purchasable anywhere.
+
+## Slice 6 — vendor transactions, buy arc (contract authored 2026-08-08; user-pulled forward)
+
+**Research:** `docs/research/2026-08-08-slice6-vendor-transactions-research.md`.
+User direction: "I cant buy anything... Fix that first." Root cause of all
+four reported symptoms: `VendorUiController` never touches the shared
+`SelectionState`/`StackSplitQuantityState` owners every other panel uses.
+
+### Decisions
+
+1. **Shop items materialize into `ClientObjectTable`** while the session is
+   open (retail creates real CWeenieObjects from the vendor list — Slice 5
+   research §A.2) and are REMOVED on session close/replace/reset. The
+   implementer verifies retail's removal site (gmVendorUI::CloseVendor
+   family) and mirrors its lifecycle. This dissolves F7c's blocker:
+   `ExamineItemRequested` gets wired in this slice.
+2. **Vendor selection is the GLOBAL selection**: a new vendor change source
+   on the canonical `SelectionState`; row-click selects through it; the
+   status bar and the existing byte-faithful `StackSplitQuantityState`
+   slider follow automatically (the split-size mask helper from 5.4's F2
+   feeds the vendor-owned seeding exactly as gmToolbarUI does at
+   pc:198635-198790).
+3. **Buy = retail's Buy button**: immediate single-item purchase
+   (gmVendorUI::BuySingleItem, pc:201661) of the selected item with the
+   slider-chosen quantity for stacks. Outbound `0x005F`: vendorGuid,
+   count, per-item (i32 amount, u32 guid), TRAILING u32
+   alternateCurrencyId — the real client sends it (CM_Vendor::Event_Buy,
+   pc:689288) even though ACE's reader ignores it; we port the real
+   client. The request rides the EXISTING J5.2 one-request-at-a-time
+   reservation and completes on `UseDone` (0x01C7) — already the wired
+   completion signal; no second gate.
+4. **Reconciliation is the existing inbound machinery**: money property
+   updates, inventory CreateObject, and the ApproachVendor refresh
+   (VendorState.Refreshed) all flow through landed handlers — the slice
+   VERIFIES the loop end-to-end rather than adding an owner.
+5. **No double-click-to-buy**: retail has no such mechanism (confirmed
+   against the full named table). We match retail. If the user wants it
+   as a deliberate modernization it needs their explicit call + an AP row.
+6. **Deferred, still AP-161**: the Add button / Buying-tab staging list
+   and everything Sell (0x0060 — researched, next arc).
+
+### Ordered work (one implementer, bisectable commits)
+
+- **6.1** shop-item materialization + removal lifecycle + examine wiring.
+- **6.2** the selection coupling (source, row-click, split seeding) —
+  status bar + slider light up.
+- **6.3** the 0x005F builder (golden-byte tests incl. the trailing dword),
+  Buy-button wiring, gate/UseDone completion, and the verified
+  reconciliation round-trip. Register: AP-161 narrowed in the landing.
+
+### Gate (user, connected)
+
+Select a stacked item → it shows in the status bar with the slider; pick
+a quantity; Buy → coins drop by the displayed price, the stack lands in
+the pack, the shop refreshes; a single-item buy works; insufficient funds
+fails cleanly; the session still closes on walk-away/portal with the
+materialized items removed.