shrike/trading.py

Part of SHRIKE.

"""The scrap ledger, the drift depots, and the Broker barge.

Three things live here.

:class:`Economy` is the run's purse. It is the only place scrap is added,
spent or turned into Cores, so every conversion in the game passes one function
and shares one unit, Cores per 10 scrap. It listens for the sector's
``RESOURCE_COLLECTED`` and credits the scrap motes that reach the ship, which
is what makes flying through the confetti the income.

:class:`Depot` is the trading post: a hermit in a gutted freighter with a
docking bay, six items of stock plus a pity slot biased toward the build you
are actually flying, an oxygen canister and a fuel cell that are on the shelf
whatever the roll says, a reroll that doubles every time you use it, and a
standing offer to buy your scrap outright at
``balance.CONVERT_RATE_TRADING_POST``. That
offer is what anchors meta banking to places on the chart: away from a post the
only conversion is the Refinery, and the Refinery is loud.

The bay owns the docking, the shelf and the prices; the screen that shows them
is ``shrike.flow.DepotScene``, which drives :meth:`Depot.tick_interact` by hand
while it holds the run still so the bay keeps answering its own key. A shelf
stays put for the whole visit: :meth:`Depot.stock_for` marks a bought entry
``sold`` rather than dropping it, because a shelf that reshuffles between the
press and the release is a shelf nobody can read. Consumables restock inside
:data:`CONSUMABLE_PURCHASE_LIMITS`; a module or a weapon is a thing, and the bay
has one of it.

:class:`Broker` is the same barge for notorious ships only. Below
``balance.BROKER_NOTORIETY_THRESHOLD`` it will not open its bay, and above it
the stock is the eight tier-3 exclusives a quiet player never sees.

Modules themselves are ``shrike.modules``'s business. The shelf reads
``MODULE_CATALOGUE`` for a module's family, tier and price, and ``ModulePool``
for whether the world offers it at all, so the shop and the socket rack can
never disagree about what a thing is or what it costs. Weapons have no such
catalogue, so their price band lives here beside the consumables.

What a row promises
===================

Every priced row also carries a ``fit``: where this purchase would land on the
hull that is docked right now, read off the live racks rather than guessed.
That is what turns "AUTOCANNON, 43 scrap" into "AUTOCANNON, 43 scrap, mounts
hardpoint 2" or, on a full rack, into an honest warning that it will stow. The
effect half of the line comes from the two modules that own the numbers,
``modules.effect_summary`` and ``weapons.weapon_summary``, so a rebalance moves
the shelf text with it and no sentence here can drift out of date.

The bay is also where a fit is changed, because it is the only place the run
stands still. :meth:`Depot.swap_weapon` performs one mount and announces what
came off; the run scene owns the stowage and moves the two ids itself, which is
what keeps a single list authoritative. The screen that drives it is
``shrike.flow.RefitScene``, a schematic of the hull with its mounts drawn where
they really sit; :meth:`Depot.swap_options` is the same offer as a flat list,
which is what a headless caller wants and what the dock screen used to print.
The sentences both of them speak live here, beside the shelf's, so the wording
of a fit is written once: :func:`item_summary` for what a thing does and
:func:`refit_preview` for what mounting it here would cost.
"""

from __future__ import annotations

import math
import random
from collections.abc import Callable
from dataclasses import dataclass

from simvx.core import Area3D, Input, Node, Node3D, Signal, SphereShape3D, Vec2

from . import balance
from .modules import (
    MODULE_CATALOGUE,
    SOCKET_RACK_GROUP,
    ModulePool,
    effect_summary,
    module_spec,
    price_band,
    socket_label,
)
from .power import SignalWiring
from .runtime import Groups, Layers, Services, SignalNames, to_plane
from .weapons import WEAPON_RACK_GROUP, weapon_summary

try:
    from . import artkit
except ImportError:  # pragma: no cover - artkit is optional for logic tests
    artkit = None

# ============================================================================
# Local constants
#
# balance.py owns prices, rates and thresholds. What follows is the shape of
# the shop and the reach of the docking bay, which are this module's own.
# ============================================================================

#: How close the ship must come before the bay will take it, in world units.
#:
#: The barge's own drum is five units across the beam, and the ship cruises at
#: about sixteen units a second, so the original eight left a three-unit shell
#: of hull clearance that a pilot at speed crossed in a fifth of a second. That
#: is not a docking bay, it is a coin toss, and it is why a marked depot read as
#: something the game would not let you touch. Fourteen gives the approach about
#: a second and a half of standing still in, which is what a bay is for.
DOCK_RADIUS = 14.0

#: Hold the interact button this long while docked to sell the hold. The
#: design's interact ladder is tap to dock, 1 s to patch, 3 s to sell or refine.
INTERACT_SELL_HOLD_S = 3.0

#: The bay's affordance lines. Every one names its key and its verb, and the
#: sell line names the price, because a hold is only worth selling if the pilot
#: can see what it is worth.
PROMPT_DOCK = "F: DOCK"
PROMPT_SELL = "HOLD F: SELL {scrap:.0f} SCRAP FOR {cores:.1f} CORES"
PROMPT_SELL_EMPTY = "DOCKED: nothing in the hold to sell"
PROMPT_DOCK_REFUSED = "BROKER BARGE: notoriety {threshold} to dock"

#: How many of one shelf entry a single visit will sell.
#:
#: A module or a weapon is a thing, and the bay has exactly one of it. A
#: consumable is a commodity and the bay will keep selling it while the hold
#: can pay, except where the design caps it: air is rationed at
#: ``balance.DEPOT_O2_CANISTERS_PER_VISIT`` so a full purse cannot simply buy
#: its way out of the life-support clock.
UNIQUE_PURCHASE_LIMIT = 1
#: What an uncapped consumable is capped at anyway, so no shelf is infinite.
CONSUMABLE_RESTOCK_LIMIT = balance.DEPOT_CONSUMABLE_RESTOCK_LIMIT
CONSUMABLE_PURCHASE_LIMITS: dict[str, int] = {
    "o2_canister": balance.DEPOT_O2_CANISTERS_PER_VISIT,
    "fuel_cell": balance.DEPOT_FUEL_CELLS_PER_VISIT,
}

#: The two supplies every bay carries whatever the dice say.
#:
#: Air and fuel are not stock, they are the two clocks a run is flown against,
#: and a shelf that rolled neither is a shop with no answer to either. The
#: blind gate found exactly that: a bay selling an autocannon, a dampener, an
#: RTG, a sentry, an ammo box and an emitter vane to a hull down to 61 oxygen
#: with one jump of fuel in the tank, and no screen anywhere in the game that
#: named where more of either comes from.
#:
#: So they are stocked *beside* the rolled shelf rather than inside it: a
#: reroll re-rolls the six and never touches these two, and the rolled
#: consumable slot draws from what is left, so the shelf can never spend a
#: slot offering air it was already offering. What a visit has already sold
#: still stands: the canister ration is spent once it is spent.
GUARANTEED_CONSUMABLES: tuple[str, ...] = ("o2_canister", "fuel_cell")
#: The slot mark a standing supply carries, beside ``stock`` and ``pity``.
SUPPLY_SLOT = "supply"

#: How often the pity slot really honours the build it is reading. Below 1.0
#: on purpose: an archetype has to stay findable without being guaranteed.
PITY_BIAS_STRENGTH = 0.75

#: Extra weight the Refinery carries in the pity slot. The conversion bet only
#: stays live if most runs are offered the module that makes it.
REFINERY_PITY_WEIGHT = 3.0

#: Tiers a depot may stock per act, read off the wreck drop table so the shop
#: and the world agree about when tier 3 exists at all.
ACT_TIER_BANDS = {act: drops.module_tiers_in_wrecks for act, drops in balance.ACT_DROPS.items()}

#: Spacing between one depot's seeds and the next reroll's, so two depots one
#: apart never share a shelf.
_REROLL_STRIDE = 1_000_003


# ============================================================================
# Stock catalogue
# ============================================================================


@dataclass(frozen=True)
class StockItem:
    """One thing on a depot's shelf."""

    id: str
    kind: str  # "weapon" | "module" | "consumable"
    family: str
    tier: int
    price: int
    slot: str = "stock"  # "stock" | "pity"
    broker_exclusive: bool = False
    pool_sibling: str = ""

    def as_dict(self) -> dict:
        """The plain-dict form the depot hands out."""
        return {
            "id": self.id,
            "kind": self.kind,
            "family": self.family,
            "tier": self.tier,
            "price": self.price,
            "slot": self.slot,
            "broker_exclusive": self.broker_exclusive,
            "pool_sibling": self.pool_sibling,
        }


#: Consumables, priced by the design rather than by a tier band.
CONSUMABLES: dict[str, tuple[str, int]] = {
    "ammo_box": ("ammo", balance.AMMO_BOX_PRICE_SCRAP),
    "o2_canister": ("life_support", balance.DEPOT_O2_CANISTER_PRICE_SCRAP),
    "fuel_cell": ("fuel", balance.DEPOT_FUEL_PRICE_SCRAP),
    "breach_patch": ("repair", balance.BREACH_PATCH_SCRAP),
}

#: Which price band each weapon is sold in. ``balance.WEAPONS`` fixes what a
#: weapon does and which economy it feeds; what a trader charges for one is the
#: shop's business, and follows the module price curve by tier.
WEAPON_TIERS: dict[str, int] = {
    "pulse_blaster": 1,
    "mining_laser": 1,
    "autocannon": 1,
    "scatter_coil": 2,
    "arc_beam": 2,
    "flak_cannon": 2,
    "rail_lance": 2,
    "grav_hook": 2,
    "missile_rack": 3,
    "nova_mortar": 3,
}


#: What one of each consumable actually does, as the delta it applies. A
#: consumable is bought for a number, so the shelf quotes the number: "+40 O2
#: now" is an offer where "air in the tank" is a mood.
CONSUMABLE_EFFECTS: dict[str, str] = {
    "ammo_box": "one full box of rounds now",
    "o2_canister": (
        f"+{balance.DEPOT_O2_CANISTER_AMOUNT:.0f} O2 now, "
        f"{balance.DEPOT_O2_CANISTER_AMOUNT / balance.O2_DRAIN_PER_S:.0f} s of air on a sound hull"
    ),
    "fuel_cell": f"+{balance.DEPOT_FUEL_AMOUNT:.0f} fuel now",
    "breach_patch": "seals one open breach now",
}

#: What each shelf category is called on the dock screen.
CATEGORY_LABELS: dict[str, str] = {"weapon": "weapon", "module": "module", "consumable": "supply"}
#: What a standing supply's category says instead. The phrase is the promise:
#: a pilot who rerolls a shelf hunting for air has to be able to read, before
#: they spend the scrap, that these two rows are not what a reroll changes.
CATEGORY_ALWAYS_STOCKED = "supply, always stocked"

#: Where a purchase would land, said before the scrap is spent. The shelf is
#: the last place a fit can still be planned, so a weapon that will not mount
#: says so on the row rather than in the toast that follows the payment.
FIT_MOUNTS = "mounts hardpoint {hardpoint}"
FIT_STOWS = "STOWS: hardpoints full (swap at dock)"
FIT_INSTALLS = "{socket} socket"
FIT_NO_SOCKET = "NO FREE {size} SOCKET"
FIT_FEEDS = "feeds the {name}, {rounds} rounds"
FIT_NO_FEED = "NO BALLISTIC WEAPON TO FEED"
FIT_SEALS = "{breaches} open now"
FIT_NO_BREACH = "NO OPEN BREACH TO SEAL"


#: Headings of the fit panel's three blocks.
FIT_HEADING_WEAPONS = "WEAPONS"
FIT_HEADING_MODULES = "MODULES"
FIT_HEADING_STOWED = "STOWED"

#: A refit offer as one line: what goes on, where, and what comes off.
SWAP_ROW = "MOUNT {name} ON HARDPOINT {hardpoint}, {displaced} COMES OFF"
SWAP_ROW_FREE = "MOUNT {name} ON HARDPOINT {hardpoint}, which is empty"

#: What the refit panel says. Every line is the same sentence at a different
#: stage of one decision: what a mount is carrying, what putting this on it
#: would do, and why it will not go on at all. A refusal is written the same
#: way as an offer on purpose: the panel prints the answer *before* the commit,
#: so "will not fit" has to read as a description of the hull rather than as an
#: error the player has already earned.
REFIT_SLOT_EMPTY = "EMPTY"
REFIT_PREVIEW_MOUNT = "{name} ON {slot}: {summary}, REPLACES {displaced}"
REFIT_PREVIEW_MOUNT_BARE = "{name} ON {slot}: {summary}, THE MOUNT IS BARE"
REFIT_PREVIEW_PICK_MOUNT = "{name}: {summary}. PICK A MOUNT FOR IT"
REFIT_PREVIEW_SLOT_FULL = "{slot} CARRIES {occupant}: {summary}"
REFIT_PREVIEW_SLOT_BARE = "{slot} IS BARE. PICK SOMETHING OUT OF THE LOCKER"
REFIT_REFUSE_GUN_IN_SOCKET = "{name} IS A GUN: IT NEEDS A HARDPOINT, NOT THE {slot}"
REFIT_REFUSE_MODULE_ON_HARDPOINT = "{name} IS A MODULE: IT NEEDS A SOCKET, NOT {slot}"
REFIT_REFUSE_TOO_LARGE = "{name} NEEDS A {size} SOCKET; {slot} IS {socket_size}"
REFIT_REFUSE_TURRETS_FULL = "{name} WOULD BE TURRET {count}: A HULL CARRIES {maximum}"


def item_name(item_id: str) -> str:
    """A shelf entry's id as a display name: ``pulse_blaster`` to ``PULSE BLASTER``."""
    return str(item_id).replace("_", " ").upper()


def category_label(item: dict) -> str:
    """The one-word category the dock screen files *item* under."""
    kind = str(item.get("kind", ""))
    label = CATEGORY_LABELS.get(kind, kind or "item")
    if item.get("slot") == "pity":
        return f"{label}, for your build"
    if item.get("slot") == SUPPLY_SLOT:
        return CATEGORY_ALWAYS_STOCKED
    return label


def effect_line(item: dict) -> str:
    """One line saying what *item* does, for the shelf that is selling it.

    Every line is mechanical. A weapon leads with where it would land, because
    a gun that is going to stow is a different purchase from one that is going
    to shoot, and then quotes its DPS, its feed and its trigger. A module leads
    with the numbers it actually applies and ends with the mount it takes. A
    consumable leads with its delta.

    The mount half comes off ``item["fit"]``, which :meth:`Depot.priced` folds
    in from the live hull. Without a hull the line still describes the thing,
    it simply cannot promise it a socket. A consumable the hull has no use for
    prints the refusal alone: "+40 O2 now" beside "no tank to fill" is two
    halves of a sentence arguing with each other.
    """
    item_id = str(item.get("id", ""))
    kind = str(item.get("kind", ""))
    fit = str(item.get("fit", ""))
    blocked = bool(item.get("fit_blocked", False))
    if kind == "weapon":
        if item_id not in balance.WEAPONS:
            return ""
        return ", ".join(part for part in (fit, weapon_summary(item_id)) if part)
    if kind == "module":
        if item_id not in MODULE_CATALOGUE:
            return ""
        return ", ".join(part for part in (effect_summary(item_id), fit or socket_label(item_id)) if part)
    if blocked:
        return fit
    return ", ".join(part for part in (CONSUMABLE_EFFECTS.get(item_id, ""), fit) if part)


def item_summary(item_id: str) -> str:
    """What a thing in the locker does, gun or module, in one line.

    The two catalogues answer the question in their own words and neither
    knows about the other, so the refit panel would otherwise have to branch on
    the kind at every place it prints a name. Empty for an id in neither, which
    is what a stale save or a hand-built test row hands in.
    """
    item_id = str(item_id)
    if item_id in balance.WEAPONS:
        return weapon_summary(item_id)
    if item_id in MODULE_CATALOGUE:
        return effect_summary(item_id)
    return ""


def refit_preview(item_id: str, slot_label: str, occupant: str = "") -> str:
    """What mounting *item_id* on *slot_label* would do, before it is committed.

    The panel prints this while the mount is only being *looked* at, which is
    the whole point of it: a refit that names the gun coming off before the
    press is a decision, and the same sentence after the press is a receipt.
    *occupant* is the id already on the mount, empty for a bare one.
    """
    name = item_name(item_id)
    summary = item_summary(item_id)
    if occupant:
        return REFIT_PREVIEW_MOUNT.format(name=name, slot=slot_label, summary=summary, displaced=item_name(occupant))
    return REFIT_PREVIEW_MOUNT_BARE.format(name=name, slot=slot_label, summary=summary)


def fit_panel_lines(
    rack=None,
    sockets=None,
    stowed: tuple[str, ...] | list[str] = (),
    stowed_modules: tuple[str, ...] | list[str] = (),
) -> list[str]:
    """The current fit as a screen prints it: hardpoints, sockets, stowage.

    The dock screen's FIT panel. Composed here rather than in either rack
    because a fit is the two of them together, and a pilot deciding what to buy
    reads them as one list. Either rack may be absent, which is what a test
    harness or a half-built run hands in; the block it owns is simply left out.

    The stowage is one block, guns and modules together, because it is one
    locker: a module pulled out of a socket at the refit panel is waiting for a
    mount in exactly the way a gun with no free hardpoint is.
    """
    lines: list[str] = []
    if rack is not None:
        lines.append(FIT_HEADING_WEAPONS)
        lines.extend(rack.fit_lines())
    if sockets is not None:
        lines.append(FIT_HEADING_MODULES)
        lines.extend(sockets.fit_lines())
    locker = [*stowed, *stowed_modules]
    if locker:
        lines.append(FIT_HEADING_STOWED)
        lines.extend(f"{item_name(item_id)}, {item_summary(item_id)}" for item_id in locker)
    return lines


def _weapon_price(weapon_id: str, rng: random.Random) -> int:
    low, high = price_band(WEAPON_TIERS.get(weapon_id, 1))
    return int(rng.randint(low, high))


def _weapon_family(weapon_id: str) -> str:
    spec = balance.WEAPONS.get(weapon_id)
    return spec.family if spec is not None else "energy"


def _module_item(module_id: str, *, slot: str = "stock") -> StockItem:
    """One catalogue module as a shelf entry, priced by ``shrike.modules``."""
    spec = module_spec(module_id)
    return StockItem(
        id=module_id,
        kind="module",
        family=str(spec["family"]),
        tier=int(spec["tier"]),
        price=int(spec["price"]),
        slot=slot,
        broker_exclusive=bool(spec["broker_exclusive"]),
        pool_sibling=str(spec["pool_sibling"] or ""),
    )


# ============================================================================
# Economy
# ============================================================================


class Economy(Node):
    """The run's scrap and the Cores it becomes. Singleton ``Services.ECONOMY``.

    Scrap arrives from the sector's ``RESOURCE_COLLECTED``, from bounties and
    from anything else that calls :meth:`add_scrap`. It leaves through
    :meth:`spend_scrap` (purchases, patches, the Lure fee) or through
    :meth:`convert`, which is the only door onto the meta currency and takes
    its rate from the caller: ``balance.CONVERT_RATE_TRADING_POST`` at a depot,
    ``CONVERT_RATE_REFINERY`` aboard, ``CONVERT_RATE_EXTRACTION`` at the Gate,
    ``CONVERT_RATE_DEATH`` when the run ends badly.
    """

    scrap_changed = Signal(float)
    cores_banked = Signal(float, float)

    def __init__(self, *, scrap: float = 0.0, **kwargs):
        super().__init__(**kwargs)
        self.scrap = max(0.0, float(scrap))
        self.cores_banked_this_run = 0.0
        #: Every scrap ever credited this run, for the death ledger's income line.
        self.scrap_earned_this_run = 0.0
        self._wiring = SignalWiring(self)
        self._wiring.want(SignalNames.RESOURCE_COLLECTED, self._on_resource_collected)

    def on_ready(self):
        self._wiring.sweep()

    def on_update(self, dt: float):
        self._wiring.poll(dt)

    def add_scrap(self, amount: float, source: str = "") -> None:
        """Credit *amount* of scrap. *source* is for the ledger, not the maths."""
        del source
        amount = float(amount)
        if amount <= 0.0:
            return
        self.scrap += amount
        self.scrap_earned_this_run += amount
        self.scrap_changed(self.scrap)

    def spend_scrap(self, amount: float) -> bool:
        """Atomic spend. False and no deduction when the hold is short."""
        amount = float(amount)
        if amount < 0.0 or amount > self.scrap + 1e-9:
            return False
        self.scrap = max(0.0, self.scrap - amount)
        self.scrap_changed(self.scrap)
        return True

    def convert(self, scrap: float, rate: float) -> float:
        """Turn carried scrap into Cores at *rate* Cores per 10 scrap.

        Converts at most what is carried, so a caller may pass more than the
        hold holds and still get an honest answer. Returns the Cores banked.
        """
        scrap = min(max(0.0, float(scrap)), self.scrap)
        if scrap <= 0.0:
            return 0.0
        cores = balance.cores_from_scrap(scrap, float(rate))
        self.scrap -= scrap
        self.cores_banked_this_run += cores
        self.scrap_changed(self.scrap)
        self.cores_banked(cores, float(rate))
        return cores

    def _on_resource_collected(self, kind: str, amount: float) -> None:
        if kind == "scrap":
            self.add_scrap(amount, "sector")


# ============================================================================
# Depots
# ============================================================================


class Depot(Node3D):
    """A drift depot: a docking bay, a shelf of stock and a standing scrap offer.

    Docking is proximity plus intent. The bay is an ``Area3D`` sensor on
    ``Layers.INTERACT`` watching for the ship, and a tap of ``interact`` inside
    it docks; holding the same button for :data:`INTERACT_SELL_HOLD_S` while
    docked sells the whole hold at the post's rate. Flying out undocks.

    Stock is deterministic from ``seed`` and the reroll count, so a route
    replayed on the same seed offers the same shelf; :meth:`stock_for` layers
    the pity slot on top of it from the build profile the run hands in, and
    puts :data:`GUARANTEED_CONSUMABLES` in front of the whole roll, so air and
    fuel are always for sale somewhere the pilot can find them.
    """

    docked = Signal(str)
    undocked = Signal()
    #: ``(item_id, price)`` once payment has cleared. Module-local by design:
    #: the run scene connects at mount and delivers the goods, so the depot
    #: never has to know what a socket or a hardpoint is.
    item_purchased = Signal(str, float)
    #: ``(mounted_id, displaced_id, hardpoint)`` after a swap at the bay. The
    #: run scene owns the stowage, so it listens for this and moves the two ids
    #: between its locker and the hull.
    weapon_swapped = Signal(str, str, int)

    def __init__(
        self,
        *,
        depot_id: str = "depot",
        seed: int = 0,
        act: int = 1,
        dock_radius: float = DOCK_RADIUS,
        pool: ModulePool | None = None,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.depot_id = str(depot_id)
        self.seed = int(seed)
        self.act = max(1, min(balance.CHART_ACTS, int(act)))
        self.dock_radius = float(dock_radius)

        self.is_docked = False
        self.in_range = False
        self.rerolls = 0
        #: Ids this visit will not sell again, either because the bay had one
        #: of them or because the ration is spent.
        self.sold_out: set[str] = set()
        #: How many of each id this visit has sold, which is what the shelf
        #: shows and what :data:`CONSUMABLE_PURCHASE_LIMITS` is measured against.
        self.purchases: dict[str, int] = {}
        #: The world pool this shop stocks from; a purchase here widens it for
        #: good, and the meta profile is what carries that between runs.
        self.pool = pool if pool is not None else ModulePool()
        #: Sibling modules a purchase here has just unlocked, for the run to bank.
        self.pool_unlocks: list[str] = []
        #: Asked before payment, with the item dict. Returning False refuses
        #: the sale and nothing is spent; the run scene installs one that
        #: checks the hull can actually take the item, so a full socket rack
        #: costs a toast rather than scrap.
        self.purchase_gate: Callable[[dict], bool] | None = None

        self._interact_hold = 0.0
        self._sold_this_press = False
        #: True while a press that has already been answered elsewhere is still
        #: down. Undocking releases the bay on the same button the dock screen
        #: commits with, and without this the release that closed the bay would
        #: open it again on the very next frame.
        self._ignore_release = False
        self._stock_cache: tuple[object, list[dict]] | None = None

    # -- scene ------------------------------------------------------------

    def on_enter_tree(self):
        super().on_enter_tree()
        self.add_to_group(Groups.DEPOTS)

    def on_ready(self):
        if artkit is not None:
            self.add_child(artkit.build_depot(self.seed))
        self.add_child(
            Area3D(
                name="DockSensor",
                shape=SphereShape3D(radius=self.dock_radius),
                collision_layer=Layers.INTERACT,
                collision_mask=Layers.MASK_INTERACT_SENSOR,
            )
        )

    @property
    def plane_position(self) -> Vec2:
        return to_plane(self.world_position)

    def _ship(self):
        tree = self.tree
        return tree.get_first_in_group(Groups.SHIP) if tree is not None else None

    def on_update(self, dt: float):
        ship = self._ship()
        if ship is None:
            self.in_range = False
            if self.is_docked:
                self.undock()
            return

        here = self.plane_position
        there = to_plane(ship.world_position)
        distance = math.hypot(float(here.x) - float(there.x), float(here.y) - float(there.y))
        self.in_range = distance <= self.dock_radius

        if self.is_docked and not self.in_range:
            self.undock()

        self.tick_interact(dt)

    def tick_interact(self, dt: float, *, taps_toggle_bay: bool = True) -> None:
        """Read one frame of the bay's interact ladder.

        Resolved on release so one button can both tap and hold: a tap toggles
        the bay, :data:`INTERACT_SELL_HOLD_S` of hold sells the hold at the
        post's rate.

        Called from :meth:`on_update` in the ordinary case, and directly by the
        dock screen while that screen holds the run still: a paused depot would
        stop answering the button the world spent the whole run teaching. The
        screen passes ``taps_toggle_bay=False`` because while it is up a tap is
        its own confirm and the screen owns the way out, but the sell rung stays
        live, so holding the key still empties the hold exactly as it does in
        open space.
        """
        if Input.is_action_just_pressed("interact"):
            self._interact_hold = 0.0
            self._sold_this_press = False
            self._ignore_release = False
        if Input.is_action_pressed("interact"):
            self._interact_hold += dt
            if self.is_docked and not self._sold_this_press and self._interact_hold >= INTERACT_SELL_HOLD_S:
                self._sold_this_press = True
                self.sell_hold()
        elif Input.is_action_just_released("interact"):
            tapped = not self._sold_this_press and self._interact_hold < INTERACT_SELL_HOLD_S
            if tapped and taps_toggle_bay and not self._ignore_release:
                if self.is_docked:
                    self.undock()
                elif self.in_range:
                    self.dock()
            self._interact_hold = 0.0
            self._sold_this_press = False
            self._ignore_release = False

    def interact_hold_fraction(self) -> float:
        """Progress of the sell hold, 0 to 1, for the HUD's radial fill."""
        if not self.is_docked or self._sold_this_press:
            return 0.0
        return min(1.0, self._interact_hold / INTERACT_SELL_HOLD_S)

    def affordance(self) -> str:
        """The verb line for the bay's current state, empty when out of range.

        Docked, the line quotes the hold and what the post would pay for it.
        In range but not docked, it names the key. A barge that will not open
        its bay says why, rather than answering a press with silence.
        """
        if self.is_docked:
            economy = self._economy()
            scrap = float(getattr(economy, "scrap", 0.0)) if economy is not None else 0.0
            if scrap <= 0.0:
                return PROMPT_SELL_EMPTY
            cores = balance.cores_from_scrap(scrap, balance.CONVERT_RATE_TRADING_POST)
            return PROMPT_SELL.format(scrap=scrap, cores=cores)
        if not self.in_range:
            return ""
        if not self.can_dock():
            return PROMPT_DOCK_REFUSED.format(threshold=balance.BROKER_NOTORIETY_THRESHOLD)
        return PROMPT_DOCK

    # -- docking -----------------------------------------------------------

    def can_dock(self) -> bool:
        """Whether this bay will take the ship at all. Always true for a post."""
        return True

    def dock(self) -> bool:
        """Open the bay. False when the ship is out of range or refused."""
        if self.is_docked or not self.in_range or not self.can_dock():
            return False
        self.is_docked = True
        self.docked(self.depot_id)
        return True

    def undock(self) -> None:
        """Close the bay and let the run continue."""
        if not self.is_docked:
            return
        self.is_docked = False
        self._ignore_release = True
        self.undocked()

    # -- stock -------------------------------------------------------------

    def stock_for(self, build_profile: dict) -> list[dict]:
        """This visit's shelf: the standing supplies, six items, and the pity slot.

        The supplies are :data:`GUARANTEED_CONSUMABLES`, air and fuel, which
        every bay carries and no reroll can take away. Six is
        ``balance.DEPOT_STOCK_WEAPONS`` weapons, ``DEPOT_STOCK_MODULES``
        modules and ``DEPOT_STOCK_CONSUMABLES`` consumable drawn from what the
        supplies leave; the pity slot is drawn from whatever families the
        profile is already flying, so an archetype stays findable without ever
        being promised. The result is stable for a given profile and reroll
        count.

        A bought entry stays on the shelf carrying ``sold``, rather than
        vanishing and letting the rest of the shelf reshuffle under a pilot who
        is still reading it. Only a reroll changes what is on offer.
        """
        profile = dict(build_profile or {})
        signature = (self.rerolls, _profile_signature(profile))
        if self._stock_cache is not None and self._stock_cache[0] == signature:
            return [self.priced(item) for item in self._stock_cache[1]]

        # Seeded from integers only: a shelf must roll the same way in every
        # process, and Python's string hashing is salted per run.
        rng = random.Random(self.seed * _REROLL_STRIDE + self.rerolls)
        items = self._roll_stock(rng, profile)
        self._stock_cache = (signature, [dict(item) for item in items])
        return [self.priced(item) for item in items]

    def priced(self, item: dict) -> dict:
        """One shelf entry with this visit's live state folded in.

        Beside what the visit has sold, the entry carries ``fit``: where this
        purchase would land on the hull that is docked right now. It is read
        off the live racks rather than guessed, so the row cannot promise a
        hardpoint the delivery will not give it.
        """
        entry = dict(item)
        item_id = str(entry.get("id", ""))
        entry["sold"] = item_id in self.sold_out
        entry["bought"] = int(self.purchases.get(item_id, 0))
        entry["fit"], entry["fit_blocked"] = self.fit_for(entry)
        return entry

    # -- what a purchase would do to the hull ------------------------------

    def weapon_rack(self):
        """The docked ship's weapon rack, or None when no hull is in the tree."""
        tree = self.tree
        racks = tree.group(WEAPON_RACK_GROUP) if tree is not None else []
        return racks[0] if racks else None

    def socket_rack(self):
        """The docked ship's socket rack, or None when no hull is in the tree."""
        tree = self.tree
        racks = tree.group(SOCKET_RACK_GROUP) if tree is not None else []
        return racks[0] if racks else None

    def fit_for(self, item: dict) -> tuple[str, bool]:
        """Where buying *item* would land it, and whether it would land at all.

        The text is what the shelf prints; the flag is True when the hull has
        nowhere to put the thing, which is the same answer the run scene's
        purchase gate gives after the press. Saying it on the row is what turns
        a refused purchase from a surprise into a decision.

        Empty and False when there is no hull to ask, which is the honest
        answer: a shelf rolled outside a run knows what a thing is and not
        where it would go.
        """
        item_id = str(item.get("id", ""))
        kind = str(item.get("kind", ""))
        if kind == "weapon":
            return self._weapon_fit()
        if kind == "module":
            return self._module_fit(item_id)
        return self._consumable_fit(item_id)

    def _weapon_fit(self) -> tuple[str, bool]:
        rack = self.weapon_rack()
        if rack is None:
            return "", False
        hardpoint = rack.free_hardpoint()
        # A full rack is not a refusal: the weapon is bought and stowed, and
        # the bay is where it is swapped onto the hull.
        if hardpoint is None:
            return FIT_STOWS, False
        return FIT_MOUNTS.format(hardpoint=hardpoint + 1), False

    def _module_fit(self, module_id: str) -> tuple[str, bool]:
        sockets = self.socket_rack()
        if sockets is None or module_id not in MODULE_CATALOGUE:
            return "", False
        socket = sockets.socket_for(module_id)
        if socket is None:
            return FIT_NO_SOCKET.format(size=str(module_spec(module_id)["socket_size"]).upper()), True
        return FIT_INSTALLS.format(socket=socket.label), False

    def _consumable_fit(self, item_id: str) -> tuple[str, bool]:
        if item_id == "ammo_box":
            rack = self.weapon_rack()
            if rack is None:
                return "", False
            eater = rack.ammo_eater()
            if eater is None:
                return FIT_NO_FEED, True
            rounds = int(balance.WEAPONS[eater].rounds_per_box or 0)
            return FIT_FEEDS.format(name=item_name(eater), rounds=rounds), False
        if item_id == "breach_patch":
            ship = self._ship()
            if ship is None:
                return "", False
            breaches = int(getattr(ship, "open_breaches", 0) or 0)
            if breaches <= 0:
                return FIT_NO_BREACH, True
            return FIT_SEALS.format(breaches=breaches), False
        return "", False

    def _roll_stock(self, rng: random.Random, profile: dict) -> list[dict]:
        weapons = self._weapon_pool(profile)
        modules = self._module_pool(profile)
        # The two clocks first, and outside the roll: see GUARANTEED_CONSUMABLES.
        # First in the list as well as always in it, because the shelf is read
        # from the top and a bay is docked at when something is running out.
        items: list[StockItem] = [self._supply(consumable_id) for consumable_id in GUARANTEED_CONSUMABLES]

        for weapon_id in _sample(rng, weapons, balance.DEPOT_STOCK_WEAPONS):
            items.append(
                StockItem(
                    weapon_id,
                    "weapon",
                    _weapon_family(weapon_id),
                    WEAPON_TIERS.get(weapon_id, 1),
                    _weapon_price(weapon_id, rng),
                )
            )
        for module_id in _sample(rng, modules, balance.DEPOT_STOCK_MODULES):
            items.append(_module_item(module_id))
        rolled = [consumable_id for consumable_id in CONSUMABLES if consumable_id not in GUARANTEED_CONSUMABLES]
        for consumable_id in _sample(rng, rolled, balance.DEPOT_STOCK_CONSUMABLES):
            family, price = CONSUMABLES[consumable_id]
            items.append(StockItem(consumable_id, "consumable", family, 1, price))

        for _ in range(balance.DEPOT_PITY_SLOTS):
            pity = self._roll_pity(rng, profile, modules, {item.id for item in items})
            if pity is not None:
                items.append(pity)
        return [item.as_dict() for item in items]

    def _supply(self, consumable_id: str) -> StockItem:
        """One standing supply row, priced by the design rather than by a roll."""
        family, price = CONSUMABLES[consumable_id]
        return StockItem(consumable_id, "consumable", family, 1, price, slot=SUPPLY_SLOT)

    def _roll_pity(
        self,
        rng: random.Random,
        profile: dict,
        modules: list[str],
        taken: set[str],
    ) -> StockItem | None:
        """One slot that reads the build. Biased, never guaranteed."""
        weights = _profile_weights(profile)
        candidates = [module_id for module_id in modules if module_id not in taken] or list(modules)
        if not candidates:
            return None

        def weight_of(module_id: str) -> float:
            family = module_spec(module_id)["family"]
            weight = weights.get(family, 0.0)
            if family == "refinery":
                weight += REFINERY_PITY_WEIGHT
            return weight

        matching = [module_id for module_id in candidates if weight_of(module_id) > 0.0]
        if matching and rng.random() < PITY_BIAS_STRENGTH:
            chosen = _weighted_choice(rng, matching, [weight_of(module_id) for module_id in matching])
        else:
            chosen = rng.choice(candidates)
        return _module_item(chosen, slot="pity")

    def _tier_band(self, profile: dict) -> tuple[int, int]:
        act = int(profile.get("act", self.act))
        return ACT_TIER_BANDS[max(1, min(balance.CHART_ACTS, act))]

    def _weapon_pool(self, profile: dict) -> list[str]:
        low, high = self._tier_band(profile)
        owned = set(profile.get("weapons", ()))
        pool = [wid for wid, tier in WEAPON_TIERS.items() if low <= tier <= high and wid not in owned]
        return pool or [wid for wid in WEAPON_TIERS if wid not in owned] or list(WEAPON_TIERS)

    def pool_for(self, profile: dict) -> ModulePool:
        """The world pool this visit stocks from, widened by what is unlocked."""
        expansions = set(self.pool.expansions)
        expansions |= {str(module_id) for module_id in profile.get("pool_unlocks", ())}
        expansions |= {str(module_id) for module_id in profile.get(ModulePool.PROFILE_KEY, ())}
        return ModulePool(expansions)

    def _module_pool(self, profile: dict) -> list[str]:
        low, high = self._tier_band(profile)
        owned = set(profile.get("modules", ()))
        available = self.pool_for(profile).available()
        pool = [
            module_id
            for module_id in available
            if low <= module_spec(module_id)["tier"] <= high
            and module_id not in owned
            and module_id not in self.sold_out
        ]
        return pool or available

    def reroll_price(self) -> int:
        """What the next reroll costs: 10 scrap, doubling every time."""
        return int(balance.DEPOT_REROLL_BASE_SCRAP * balance.DEPOT_REROLL_PRICE_MULT**self.rerolls)

    def reroll(self) -> bool:
        """Buy a fresh shelf. False when the hold cannot cover the price."""
        economy = self._economy()
        price = self.reroll_price()
        if economy is None or not economy.spend_scrap(price):
            return False
        self.rerolls += 1
        self._stock_cache = None
        return True

    # -- trading -----------------------------------------------------------

    def purchase_limit(self, item: dict) -> int:
        """How many of *item* this visit will sell in total."""
        if str(item.get("kind", "")) != "consumable":
            return UNIQUE_PURCHASE_LIMIT
        return CONSUMABLE_PURCHASE_LIMITS.get(str(item.get("id", "")), CONSUMABLE_RESTOCK_LIMIT)

    def buy(self, item: dict) -> bool:
        """Buy one stocked *item*.

        False, and no payment, when the bay is closed, the item is gone, the
        :attr:`purchase_gate` refuses it, or the hold cannot cover the price.
        """
        item_id = str(item.get("id", ""))
        economy = self._economy()
        if not self.is_docked or economy is None or item_id in self.sold_out:
            return False
        if self.purchase_gate is not None and not self.purchase_gate(dict(item)):
            return False
        price = float(item.get("price", 0.0))
        if not economy.spend_scrap(price):
            return False
        sold = self.purchases.get(item_id, 0) + 1
        self.purchases[item_id] = sold
        if sold >= self.purchase_limit(item):
            self.sold_out.add(item_id)
        if item.get("kind") == "module":
            sibling = self.pool.record_purchase(item_id)
            if sibling is not None:
                self.pool_unlocks.append(sibling)
        self.item_purchased(item_id, price)
        return True

    # -- refitting ---------------------------------------------------------

    def swap_options(self, stowed: tuple[str, ...] | list[str]) -> list[dict]:
        """Every stowed weapon against every hardpoint it could take.

        The flat form of the offer the refit panel draws on the hull: each
        entry carries the id going on, the hardpoint it goes on, the id coming
        off and a line naming all three, so a caller with no screen (a test, a
        headless probe) can enumerate the refits a visit is offering.

        Empty when nothing is stowed, which is the ordinary case.
        """
        rack = self.weapon_rack()
        if rack is None:
            return []
        options: list[dict] = []
        for weapon_id in stowed:
            if weapon_id not in balance.WEAPONS:
                continue
            for hardpoint, fitted in enumerate(rack.hardpoints):
                displaced = fitted.weapon_id if fitted is not None else ""
                template = SWAP_ROW if displaced else SWAP_ROW_FREE
                options.append(
                    {
                        "weapon_id": weapon_id,
                        "hardpoint": hardpoint,
                        "displaced": displaced,
                        "label": template.format(
                            name=item_name(weapon_id),
                            hardpoint=hardpoint + 1,
                            displaced=item_name(displaced),
                        ),
                    }
                )
        return options

    def swap_weapon(self, weapon_id: str, hardpoint: int) -> str | None:
        """Mount a stowed weapon and hand back the id it displaced.

        The empty string when the hardpoint was bare, and None when the swap
        could not happen at all: no bay open, no hull, or a hardpoint that does
        not exist. The caller owns the stowage and moves both ids itself, which
        is what keeps one list authoritative.
        """
        rack = self.weapon_rack()
        if not self.is_docked or rack is None or weapon_id not in balance.WEAPONS:
            return None
        if not 0 <= hardpoint < len(rack.hardpoints):
            return None
        displaced = rack.swap_in(weapon_id, hardpoint)
        # The shelf needs no invalidation: the rolled stock is cached, but
        # `priced` re-reads the hull on every shelf read, so the next refresh
        # already names the hardpoint this swap has just freed or filled.
        self.weapon_swapped(weapon_id, displaced, hardpoint)
        return displaced

    def sell_quote(self) -> tuple[float, float, float]:
        """What the hold is, what the post would pay for it, and at what rate."""
        economy = self._economy()
        scrap = float(getattr(economy, "scrap", 0.0)) if economy is not None else 0.0
        rate = balance.CONVERT_RATE_TRADING_POST
        return scrap, balance.cores_from_scrap(scrap, rate), rate

    def sell_hold(self) -> float:
        """Sell the whole hold at the post's rate. Returns Cores banked."""
        economy = self._economy()
        if economy is None or not self.is_docked:
            return 0.0
        return economy.convert(economy.scrap, balance.CONVERT_RATE_TRADING_POST)

    def _economy(self) -> Economy | None:
        tree = self.tree
        return tree.singletons.get(Services.ECONOMY) if tree is not None else None

    def _notoriety(self) -> int:
        tree = self.tree
        tally = tree.singletons.get(Services.NOTORIETY) if tree is not None else None
        return int(getattr(tally, "value", 0)) if tally is not None else 0


class Broker(Depot):
    """The black-market barge: notoriety only, and the eight best modules.

    It will not open its bay below ``balance.BROKER_NOTORIETY_THRESHOLD``, and
    what it sells is the tier-3 stock no quiet run ever sees. That gate is the
    payoff gradient that keeps loud play worth its price.
    """

    def __init__(self, *, depot_id: str = "broker", **kwargs):
        super().__init__(depot_id=depot_id, **kwargs)

    def can_dock(self) -> bool:
        tree = self.tree
        tally = tree.singletons.get(Services.NOTORIETY) if tree is not None else None
        if tally is not None and hasattr(tally, "broker_unlocked"):
            return bool(tally.broker_unlocked())
        return self._notoriety() >= balance.BROKER_NOTORIETY_THRESHOLD

    def exclusives(self) -> list[str]:
        """The tier-3 modules only this barge stocks."""
        return [module_id for module_id, spec in MODULE_CATALOGUE.items() if spec["broker_exclusive"]]

    def stock_for(self, build_profile: dict) -> list[dict]:
        """All eight exclusives, priced. No pity slot: it is all top shelf."""
        del build_profile
        return [self.priced(_module_item(module_id).as_dict()) for module_id in self.exclusives()]


# ============================================================================
# Helpers
# ============================================================================


def _profile_signature(profile: dict) -> tuple:
    """A hashable read of the parts of a build profile the shelf depends on."""
    return (
        int(profile.get("act", 0)),
        tuple(sorted(str(x) for x in profile.get("weapons", ()))),
        tuple(sorted(str(x) for x in profile.get("modules", ()))),
        tuple(sorted(str(x) for x in profile.get("pool_unlocks", ()))),
        tuple(sorted(str(x) for x in profile.get(ModulePool.PROFILE_KEY, ()))),
        tuple(sorted((str(k), float(v)) for k, v in dict(profile.get("families", {})).items())),
    )


def _profile_weights(profile: dict) -> dict[str, float]:
    """Family weights for the pity slot, from whatever the profile carries.

    ``families`` wins where it is given; otherwise the weights are read off
    what the ship is already flying, which is the same question asked the other
    way round.
    """
    weights = {str(k): float(v) for k, v in dict(profile.get("families", {})).items()}
    for module_id in profile.get("modules", ()):
        spec = MODULE_CATALOGUE.get(str(module_id))
        if spec is not None:
            family = str(spec["family"])
            weights[family] = weights.get(family, 0.0) + 1.0
    for weapon_id in profile.get("weapons", ()):
        family = _weapon_family(str(weapon_id))
        weights[family] = weights.get(family, 0.0) + 1.0
        if family == "ballistic":
            weights["turret"] = weights.get("turret", 0.0) + 0.5
    return weights


def _sample(rng: random.Random, pool: list, count: int) -> list:
    """*count* distinct picks from *pool*, or the whole pool when it is short."""
    if count >= len(pool):
        return list(pool)
    return rng.sample(pool, count)


def _weighted_choice(rng: random.Random, items: list, weights: list[float]):
    total = sum(weights)
    if total <= 0.0:
        return rng.choice(items)
    roll = rng.random() * total
    for item, weight in zip(items, weights, strict=True):
        roll -= weight
        if roll <= 0.0:
            return item
    return items[-1]