feat!(lua.endpoints): support buy-and-use for shop consumables

[S1M0N38]

The buy endpoint cannot perform the game's "Buy and Use" action for shop consumables — buying and immediately using a consumable without needing a free consumable slot. Verified against vendors/lovely/dump/ and confirmed empirically.

Bug

src/lua/endpoints/buy.lua has no use parameter. When consumable slots are full, buy {"card": N} always fails the check_for_buy_space gate (buy.lua:149) with "consumable slots are full".

The game exposes a separate "Buy and Use" button for shop consumables. buy_from_shop (functions/button_callbacks.lua:2437) skips check_for_buy_space when e.config.id == 'buy_and_use', then calls G.FUNCS.use_card(e, true) (button_callbacks.lua:2503). This buys the consumable and uses it in one step, so no slot is ever occupied. Gated by can_buy_and_use (button_callbacks.lua:79).

Empirical: consumables full (2/2), shop has c_venus → buy {"card": 1} returns "consumable slots are full". The in-game "Buy and Use" button would succeed (Venus needs no targets).

The current workaround (buy → use) is not equivalent: it requires a free slot to hold the consumable between the two calls, which buy_and_use avoids entirely.

Fix

Add an optional use boolean to the buy schema. When set with a consumable card, set the mock button's config.id = 'buy_and_use' before calling buy_from_shop, and pass through any target cards to the underlying use_card. Mirror the use endpoint's target-validation logic for consumables that require hand selection.

PoC test

def test_buy_and_use_consumable_when_full(self, client):
    """Buy+use a shop consumable even when consumable slots are full."""
    gamestate = load_fixture(client, "buy",
        "state-SHOP--consumables.count-2--shop.cards[0].key-c_venus")
    assert gamestate["consumables"]["count"] == 2
    assert gamestate["consumables"]["limit"] == 2
    assert gamestate["shop"]["cards"][0]["key"] == "c_venus"
    # Game's buy_and_use skips the slot check. balatrobot currently blocks.
    response = api(client, "buy", {"card": 0, "use": True})
    after = assert_gamestate_response(response)
    # Venus levels up a hand; consumable count unchanged (used, not stored)
    assert after["consumables"]["count"] == 2

Fixture note: needs a no-target consumable (e.g. c_venus, c_pluto) in the shop. Same add-to-shop fixture gap as the Negative-edition issue.

Sibling of #202–#206.

[S1M0N38]

Refined approach (supersedes the original use flag proposal)

After a design pass against vendors/lovely/dump/, the original "Fix" (use boolean on buy, pass-through target cards, mirror use's target validation) is rejected. Replacing it:

New endpoint: buy_and_use

A dedicated endpoint, consistent with the API's two-cluster organization (action endpoints = one player button each; add/set = meta/setup). "Buy and Use" is a distinct shop button from "Buy" with distinct guards (check_for_buy_space runs for one, not the other), so it gets its own endpoint rather than a flag on buy.

Key decisions

1. No cards (targets) param.
During SHOP, can_use_consumeable (card.lua:1763) only returns true for consumables that take no hand targets — the max_highlighted branch (card.lua:1807) is gated behind SELECTING_HAND/pack states, not SHOP. So a target param would be dead code for vanilla. If a modded consumable ever needs it, adding cards later is additive and non-breaking.

2. Pre-flight gate = the game's visibility gate, exactly.
Mirror G.FUNCS.can_buy_and_use (button_callbacks.lua:79): affordable AND card:can_use_consumeable(). Split along the codebase's existing error vocabulary:

• affordability → BAD_REQUEST (mirrors buy.lua:125)
• can_use_consumeable false → NOT_ALLOWED (mirrors use.lua:177)

3. Do NOT pre-call check_use(). The Ankh-noop is a SUCCESS, not an error.
check_use (card.lua:1829) blocks only Ankh at full jokers. But Ankh's can_use_consumeable returns true at full jokers (needs ≥1 joker + card_limit > 1), so the "Buy and Use" button is visible in vanilla — clicking it deducts money, then use_card's internal check_use bails (money spent, no joker). This is reachable in vanilla (a modded joker keying off buying_card SMODS context fires during buy_from_shop, before use_card bails).

We replicate this faithfully: buy_and_use on Ankh-at-full returns success with the honest gamestate. Pre-calling check_use ourselves would make us stricter than the game and destroy this edge.

Contrast: Judgement / The Soul / Wraith at full jokers return false from can_use_consumeable (card.lua:1800) → button invisible → our gate rejects with NOT_ALLOWED. They never reach the noop path.

4. Minimal inline mock button (not the definition-alias from buy.lua).

G.FUNCS.buy_from_shop({
  config = { id = 'buy_and_use', ref_table = G.shop_jokers.cards[pos] }
})

buy_from_shop reads only e.config.ref_table (→ c1) and e.config.id (3 dispatch sites: button_callbacks.lua:2437,2462,2505). The inline table is ephemeral — no mutation of the live UI button, which the definition-alias approach would corrupt. This follows the programmatic mock-call idiom the game uses 7× (tag.lua:216 etc.) and that use.lua:217 already uses.

5. Completion detection — 4-term union predicate.
buy.lua's detector keys on dest_count increased, but buy_and_use never emplaces → would hang. use.lua's fires prematurely (state already SHOP during the buy phase). Union of both phases' terminal conditions:

shop_decreased ∧ money_deducted ∧ G.STATE == SHOP ∧ not G.CONTROLLER.locks.use

Race-free for both the normal case (waits through PLAY_TAROT) and the Ankh-noop (fires immediately since state never left SHOP).

Params

schema = { card = { type = "integer", required = true,
  description = "0-based index of a consumable in the shop to buy and use immediately" } }
requires_state = { G.STATES.SHOP }

Registration

• new src/lua/endpoints/buy_and_use.lua
• balatrobot.lua manifest (Shop endpoints block)
• src/lua/utils/openrpc.json method block (mirrors buy, shop tag, BadRequest + NotAllowed errors)

Implementation

Going in via TDD (vertical slices: state gate → param → range → affordability → can_use_consumeable gate → success → slots-full → Ankh-noop). One open risk: fixtures for the success cases need a no-target consumable in the shop, which add can't place (it emplaces in inventory) — so those fixtures require a brute-forced deterministic seed, same pattern as seed-NEG003A / seed-S001250 in test_buy.py.

No ADR (faithful game-mirroring, not a hard-to-reverse trade-off) and no CONTEXT.md change (composes existing glossary terms).