test: cover merchant min-level restrictions

Author: MikelCalvo

docs/qa/manual-client-checklist.md

@@ -324,6 +324,16 @@ Expected result:
 - selected-character anti-flagged or transfer-guarded equipment fails closed: no item refresh, no quickslot change, no point change, no carried/equipment mutation, and no persistence change
 - equipment whose template-authored `equip_effect` point delta would overflow the bootstrap signed 32-bit point value also fails closed before item, quickslot, point, or persistence mutation
 
+### 4.5.9 Merchant buy/sell template restrictions (`SHOP BUY` / `SHOP SELL2`)
+
+- [ ] Open a known bootstrap merchant window with a disposable QA character
+- [ ] Attempt to buy a catalog item whose authored template requires a higher `min_level` than the selected character has
+- [ ] Attempt to sell a carried item whose authored template requires a higher `min_level` than the selected character has
+
+Expected result:
+- both packet paths fail with the current merchant invalid-position companion and no inventory, item quickslot, gold, or persisted account mutation is visible
+- adjacent allowed merchant buy/sell cases still use the template-authored price/sell-credit behavior
+
 ---
 
 ## 5. Single-client movement

internal/minimal/shared_world_test.go

@@ -20198,6 +20198,46 @@ func TestGameSessionFlowShopBuyAndSellRejectSelectedCharacterAntiFlagTemplatesWi
 	assertMerchantStateUnchanged(t, sellRuntime, sellAccounts, sellLogin, sellBuyer, "anti-flag packet shop sell2")
 }
 
+func TestGameSessionFlowShopBuyAndSellRejectMinLevelTemplatesWithoutMutation(t *testing.T) {
+	buyBuyer := merchantBuyerCharacter("MerchantBuyerPacketMinLevel", 0x0104012a, 0x0205012a, 125, []inventory.ItemInstance{{ID: 77, Vnum: 27001, Count: 3, Slot: 5}})
+	buyBuyer.Level = 9
+	buyRuntime, buyAccounts, buyFlow, buyActorID, buyLogin := setupMerchantBuySession(t, "merchant-min-level-buy", 0x2a2a2a2a, buyBuyer)
+	defer closeSessionFlow(t, buyFlow)
+	buyRuntime.itemTemplates[27001] = itemcatalog.Template{Vnum: 27001, Name: "Restricted Potion", Stackable: true, MaxCount: 200, ShopBuyPrice: 5, MinLevel: 10}
+
+	interactWithMerchantForBuy(t, buyFlow, buyActorID)
+	buyOut, err := buyFlow.HandleClientFrame(decodeSingleFrame(t, shopproto.EncodeClientBuy(shopproto.ClientBuyPacket{CatalogSlot: 0})))
+	if err != nil {
+		t.Fatalf("unexpected min-level packet shop buy error: %v", err)
+	}
+	if len(buyOut) != 1 {
+		t.Fatalf("expected min-level packet shop buy to emit 1 invalid-pos frame, got %d", len(buyOut))
+	}
+	if err := shopproto.DecodeServerInvalidPos(decodeSingleFrame(t, buyOut[0])); err != nil {
+		t.Fatalf("decode min-level packet shop buy invalid-pos frame: %v", err)
+	}
+	assertMerchantStateUnchanged(t, buyRuntime, buyAccounts, buyLogin, buyBuyer, "min-level packet shop buy")
+
+	sellBuyer := merchantBuyerCharacter("MerchantSellerPacketMinLevel", 0x0104012b, 0x0205012b, 125, []inventory.ItemInstance{{ID: 77, Vnum: 27001, Count: 3, Slot: 5}})
+	sellBuyer.Level = 9
+	sellRuntime, sellAccounts, sellFlow, sellActorID, sellLogin := setupMerchantBuySession(t, "merchant-min-level-sell", 0x2b2b2b2b, sellBuyer)
+	defer closeSessionFlow(t, sellFlow)
+	sellRuntime.itemTemplates[27001] = itemcatalog.Template{Vnum: 27001, Name: "Restricted Potion", Stackable: true, MaxCount: 200, ShopBuyPrice: 5, MinLevel: 10}
+
+	interactWithMerchantForBuy(t, sellFlow, sellActorID)
+	sellOut, err := sellFlow.HandleClientFrame(decodeSingleFrame(t, shopproto.EncodeClientSell2(shopproto.ClientSell2Packet{Slot: 5, Count: 2})))
+	if err != nil {
+		t.Fatalf("unexpected min-level packet shop sell2 error: %v", err)
+	}
+	if len(sellOut) != 1 {
+		t.Fatalf("expected min-level packet shop sell2 to emit 1 invalid-pos frame, got %d", len(sellOut))
+	}
+	if err := shopproto.DecodeServerInvalidPos(decodeSingleFrame(t, sellOut[0])); err != nil {
+		t.Fatalf("decode min-level packet shop sell2 invalid-pos frame: %v", err)
+	}
+	assertMerchantStateUnchanged(t, sellRuntime, sellAccounts, sellLogin, sellBuyer, "min-level packet shop sell2")
+}
+
 func assertMerchantStateUnchanged(t *testing.T, runtime *gameRuntime, accounts accountstore.Store, login string, want loginticket.Character, context string) {
 	t.Helper()
 	currencySnapshot, ok := runtime.CurrencySnapshot(want.Name)

internal/player/runtime_inventory_test.go

@@ -743,6 +743,11 @@ func TestMerchantTemplateMutationsRejectSelectedCharacterAntiFlagTemplates(t *te
 			character: loginticket.Character{RaceNum: 1},
 			template:  itemcatalog.Template{Vnum: 27001, Name: "Restricted Potion", Stackable: true, MaxCount: 200, AntiFemale: true},
 		},
+		{
+			name:      "minimum level",
+			character: loginticket.Character{Level: 9},
+			template:  itemcatalog.Template{Vnum: 27001, Name: "Restricted Potion", Stackable: true, MaxCount: 200, MinLevel: 10},
+		},
 	}
 
 	for _, tc := range cases {

spec/protocol/npc-shop-transaction-bootstrap.md

@@ -134,7 +134,7 @@ When a gated `BUY` request arrives, the runtime must validate all of the followi
 - the entry `count` is greater than zero
 - the selected character has at least that much gold available
 - the selected character has a valid carried-inventory placement for that template/count under `item-stack-bootstrap.md`, including `anti_stack` templates skipping existing-stack merge/fan-out paths
-- the resolved template does not carry a selected-character job/sex restriction (`anti_warrior`, `anti_assassin`, `anti_sura`, `anti_shaman`, `anti_male`, or `anti_female`)
+- the resolved template does not carry a selected-character job/sex/level restriction (`anti_warrior`, `anti_assassin`, `anti_sura`, `anti_shaman`, `anti_male`, `anti_female`, or `min_level` above the selected character's level)
 - persistence/writeback can succeed before the new live state is committed
 
 The first buy contract intentionally remains single-entry and immediate:
@@ -190,7 +190,7 @@ The first buy path must fail closed when any of these are true:
 - the catalog/template resolution fails
 - the player has insufficient gold
 - no valid carried inventory placement exists
-- the resolved template carries a selected-character job/sex restriction (`anti_warrior`, `anti_assassin`, `anti_sura`, `anti_shaman`, `anti_male`, or `anti_female`)
+- the resolved template carries a selected-character job/sex/level restriction (`anti_warrior`, `anti_assassin`, `anti_sura`, `anti_shaman`, `anti_male`, `anti_female`, or `min_level` above the selected character's level)
 - persistence/writeback fails
 
 The first sell/sell2 path must fail closed when any of these are true:
@@ -202,7 +202,7 @@ The first sell/sell2 path must fail closed when any of these are true:
 - the requested carried cell has duplicate live item occupancy
 - the carried item is marked runtime-locked
 - the template is marked `anti_sell`
-- the resolved template carries a selected-character job/sex restriction (`anti_warrior`, `anti_assassin`, `anti_sura`, `anti_shaman`, `anti_male`, or `anti_female`)
+- the resolved template carries a selected-character job/sex/level restriction (`anti_warrior`, `anti_assassin`, `anti_sura`, `anti_shaman`, `anti_male`, `anti_female`, or `min_level` above the selected character's level)
 - the template has no sell price
 - persistence/writeback fails
 
@@ -346,8 +346,9 @@ The first live sell-back contract remains intentionally narrow:
 - ordinary sell credit derives from loaded item-template `shop_buy_price` as `floor((shop_buy_price * sold_count) / 5)` minus `floor(3% tax)`
 - templates flagged `sell_count_per_gold` follow the legacy count-per-gold branch first: use `floor(sold_count / shop_buy_price)` when `shop_buy_price > 0`, or `sold_count` when it is zero, then apply the same `/5` and 3% tax floor; if the resulting credit is zero, the bootstrap runtime fails closed
 - templates flagged `anti_sell` fail closed before credit calculation, return bare self-only `GC::SHOP INVALID_POS` on the packet sell path while a merchant window is active, and leave live plus persisted inventory/currency unchanged
-- the player mutation boundary also exposes a template-backed sell helper that rejects `anti_sell` templates, template/item-`vnum` mismatches, invalid template metadata, invalid counts, locked carried items, equipped carried items, and zero-credit pricing before mutating live inventory or gold
+- the player mutation boundary also exposes a template-backed sell helper that rejects `anti_sell` templates, template/item-`vnum` mismatches, invalid template metadata, invalid counts, locked carried items, equipped carried items, selected-character job/sex/level restrictions, and zero-credit pricing before mutating live inventory or gold
 - successful template-backed sell uses the same template-derived `MerchantSellCredit` calculation as the packet/runtime sell path, then delegates to the existing credit mutation so whole-stack and partial-stack state results stay aligned
+- selected-character `min_level` restrictions are checked through the same template-use guard as job/sex anti-flags; packet `SHOP BUY`, packet `SHOP SELL` / `SELL2`, and the template-backed player-runtime sell helper all fail closed before inventory, quickslot, gold, or persistence mutation when the selected character is below the authored minimum level
 - the updated selected-character snapshot is persisted before the live shared-world registration is refreshed
 - if persistence/writeback fails, the runtime rolls the selected character's live gold and carried inventory back to the pre-sell snapshot, emits no success frames, and leaves the persisted account snapshot unchanged
 - whole-stack success emits self-only `ITEM_DEL(slot)`, then zero or more self-only `QUICKSLOT_DEL(position)` frames for item quickslots that referenced the removed carried slot, then self-only `PLAYER_POINT_CHANGE(type = POINT_GOLD, amount = credited_elk, value = new_gold)`