shrike/meta.py

Part of SHRIKE.

"""Fleet Doctrine, the milestone bounties, the hull trophies and the Hunt Ranks.

Everything that outlives a run and changes how the next one behaves lives here.
Four systems share one idea: a run is configured by a *bag of effects* resolved
once at launch, and every source of permanent progression contributes to that
same bag.

Fleet Doctrine
==============

Sixty nodes in five branches of twelve, radiating from a start hub and bought
with Cores: seven minors at ``balance.DOCTRINE_COST_MINOR``, four notables at
``balance.DOCTRINE_COST_NOTABLE``, one keystone at
``balance.DOCTRINE_COST_KEYSTONE``, which is ``balance.DOCTRINE_FULL_TREE_CORES``
for the lot. Respec is free and total: :meth:`MetaProfile.respec` refunds every
Core ever spent and empties the tree, because the tree is a loadout language
rather than a commitment. At most
``balance.DOCTRINE_MAX_ACTIVE_KEYSTONES`` keystones may be active in any one
run, so owning all five is a choice widened, never a build stacked.

**The design law is enforced in code**: at most one third of the nodes may be
numeric. Exactly twenty are, four per branch, all of them cheap minors. The
other forty change a verb: the foam patches while you move, the panels retract
instantly, the spool cannot be interrupted below quarter hull, heralds drop
fuel, the chart shows one more destination. :func:`_validate_tree` fails at
import if a later edit tips that ratio, so the law cannot rot quietly.

The effect engine
=================

A node's effect is either

``numeric``
    a contribution to a named key in :data:`NUMERIC_EFFECTS`, folded with that
    key's operator (product, sum, maximum or minimum) over every source.
``rule``
    a named behaviour change carrying its own parameters. It is either in the
    bag or it is not, and the module that owns the behaviour asks.

:meth:`MetaProfile.modifiers` folds the owned doctrine, the active keystones,
the current Hunt Rank and the selected hull into one :class:`Modifiers`, which
is a plain ``dict`` with query helpers on top. Every numeric key is always
present at its identity, so a consumer never has to guess a default; rule ids
are present only when active. Both lookups validate against the registries, so
a misspelled key is an immediate error rather than a silently ignored upgrade.

Milestone bounties
==================

The first five runs each end on a visible bounty (``save.MILESTONE_CORES``),
paid once, flagged in the profile forever. They exist to make runs one to five
feel like they bank something even when they end badly.

Hulls
=====

Four hulls, three of them feat-gated trophies rather than purchases: the Barge
for extracting with a hold full of scrap, the Dart for leaving a Shrike arrival
untouched, the Hive for extracting at Hunt Rank 2. Each rearranges the socket
count and layout; the layouts themselves belong to ``modules.py`` and are
reached through :func:`hull_socket_layout`, so there is one description of a
hull's geometry rather than two that can disagree.

Hunt Ranks
==========

One ascension tier per Roost kill. Ranks 1 to 4 ship, and each adds exactly one
legible modifier plus ``balance.HUNT_RANK_CORE_INCOME_BONUS`` to Core income.
Nothing gains flat hit points: the ranks remix the hunter, because the hunter is
the difficulty organ.
"""

from __future__ import annotations

import logging
from collections.abc import Iterable, Sequence
from dataclasses import dataclass, field

from simvx.core import Node, Signal

from . import balance, save
from .runtime import Services

log = logging.getLogger(__name__)

# ============================================================================
# Numbers this module owns
#
# balance.py prices the tree, the bounties, the hull feats and the Hunt Rank
# modifiers. What it does not fix, and what therefore lives here, is the
# strength of the individual doctrine nodes the design names without numbering,
# the depth term of the run score, and the two hull handling characters.
# ============================================================================

#: Doctrine minor strengths, one per numeric node. Small on purpose: a numeric
#: node is the cheap filler between the nodes that change a rule.
FIRE_RATE_STEP = 1.05
AMMO_BOX_ROUNDS_STEP = 1.20
RELOAD_SPEED_STEP = 1.25
BALLISTIC_DAMAGE_STEP = 1.06
SOLAR_WING_HP_STEP = 1.25
CAPACITOR_MAX_STEP = 20.0
GENERATOR_FUEL_BURN_STEP = 0.85
SHIELD_ABSORB_STEP = 1.15
MUFFLED_HULL_SIGNATURE_STEP = 0.92
SILENT_SPEED_STEP = 1.20
SIGNATURE_DECAY_STEP = 0.5
GENERATOR_SIGNATURE_STEP = 0.85
SCOOP_RADIUS_STEP = 1.35
DEPOT_PRICE_STEP = 0.90
REFINERY_RATE_STEP = 0.10
SHRIKE_DAMAGE_STEP = 1.10
SHRIKE_FIN_DAMAGE_STEP = 1.25
LOCKOUT_DURATION_STEP = 0.85
FLETCHING_DROP_STEP = 1.25

#: Rule parameters the design describes but does not number.
SPOOL_BRACING_HULL_FRACTION = 0.25
BROWNOUT_REFUNDS_PER_SECTOR = 1
LANTERN_READ_LEAD_S = 1.0
GHOST_WAKE_JUMPS_PER_SECTOR = 1
EXTRA_BEARING_DESTINATIONS = 1
COUNTER_LANTERN_CAPACITOR = 15.0
HERALD_FUEL_DROP = 10.0
FEEDING_TAX_MULTIPLIER = 2.0
CASING_RECLAIM_SCRAP_PER_KILL = 2.0

#: Run score: the design gives scrap, Cores and quills their weights in
#: balance.py and calls the last term "a sector-depth bonus" without a number.
SCORE_DEPTH_BONUS_PER_SECTOR = 25

#: Hull handling characters. The Barge is sluggish, the Dart slippery; the
#: Hive's drone slant is two extra auto-turrets over the shared cap.
BARGE_HANDLING_MULT = 0.85
DART_HANDLING_MULT = 1.15
HIVE_EXTRA_TURRETS = 2

#: Feat ids gating parts of the tree. Both are read off the profile.
FEAT_FIRST_EXTRACTION = "first_extraction"
FEAT_FIRST_QUILL = "first_quill"

#: How a locked feat reads on the doctrine screen, in the second person.
FEAT_PROSE: dict[str, str] = {
    FEAT_FIRST_EXTRACTION: "extract from a run",
    FEAT_FIRST_QUILL: "shear a quill from the Shrike",
}

#: The starter hull, unlocked from the first boot, shared with ``save.py``.
STARTER_HULL = save.STARTER_HULL

#: Cost per node kind, keyed by the kinds a :class:`DoctrineNode` may take.
NODE_COSTS: dict[str, int] = {
    "minor": balance.DOCTRINE_COST_MINOR,
    "notable": balance.DOCTRINE_COST_NOTABLE,
    "keystone": balance.DOCTRINE_COST_KEYSTONE,
}


# ============================================================================
# Effects: the two things a node may do
# ============================================================================


@dataclass(frozen=True)
class NumericEffect:
    """One numeric key in the effect bag, and how its contributions combine.

    ``identity`` is the value the key holds when nothing contributes, so a
    consumer reading the bag always gets a usable number. ``op`` is one of
    ``"mult"``, ``"add"``, ``"max"`` or ``"min"``.
    """

    key: str
    op: str
    identity: float
    note: str = ""


#: Every numeric key any source may write, with its fold operator. A key is
#: shared deliberately where two sources describe the same quantity: the Dart
#: hull, the Silent Running minor and Hunt Rank 1 all move
#: ``signature_fill_mult``, and the run reads one number.
NUMERIC_EFFECTS: dict[str, NumericEffect] = {
    # Gunnery
    "fire_rate_mult": NumericEffect("fire_rate_mult", "mult", 1.0, "shots per second, every weapon"),
    "ammo_box_rounds_mult": NumericEffect("ammo_box_rounds_mult", "mult", 1.0, "rounds in a bought box"),
    "reload_speed_mult": NumericEffect("reload_speed_mult", "mult", 1.0, "ballistic reload rate"),
    "ballistic_damage_mult": NumericEffect("ballistic_damage_mult", "mult", 1.0, "ballistic damage"),
    # Engineering
    "solar_wing_hp_mult": NumericEffect("solar_wing_hp_mult", "mult", 1.0, "panel hit points"),
    "capacitor_max_bonus": NumericEffect("capacitor_max_bonus", "add", 0.0, "added capacitor ceiling"),
    "generator_fuel_burn_mult": NumericEffect("generator_fuel_burn_mult", "mult", 1.0, "fuel per second running"),
    "shield_absorb_mult": NumericEffect("shield_absorb_mult", "mult", 1.0, "damage the arc eats"),
    # Silent Running
    "signature_fill_mult": NumericEffect("signature_fill_mult", "mult", 1.0, "signature gained per event"),
    "silent_speed_mult": NumericEffect("silent_speed_mult", "mult", 1.0, "top speed while silent"),
    "signature_decay_bonus": NumericEffect("signature_decay_bonus", "add", 0.0, "extra decay per second"),
    "generator_signature_mult": NumericEffect("generator_signature_mult", "mult", 1.0, "generator noise"),
    # Salvage
    "scoop_radius_mult": NumericEffect("scoop_radius_mult", "mult", 1.0, "tractor scoop reach"),
    "depot_price_mult": NumericEffect("depot_price_mult", "mult", 1.0, "what a depot charges"),
    "refinery_rate_bonus": NumericEffect("refinery_rate_bonus", "add", 0.0, "added Cores per 10 scrap refined"),
    "death_convert_rate": NumericEffect(
        "death_convert_rate", "max", balance.CONVERT_RATE_DEATH, "Cores per 10 scrap on death"
    ),
    # Predation
    "shrike_damage_mult": NumericEffect("shrike_damage_mult", "mult", 1.0, "your damage to the Shrike"),
    "shrike_fin_damage_mult": NumericEffect("shrike_fin_damage_mult", "mult", 1.0, "your damage to fins"),
    "lockout_duration_mult": NumericEffect("lockout_duration_mult", "mult", 1.0, "arrival lockout length"),
    "fletching_drop_mult": NumericEffect("fletching_drop_mult", "mult", 1.0, "herald Fletching drop odds"),
    # Hunt Ranks
    "depot_stock_items": NumericEffect("depot_stock_items", "min", float(balance.DEPOT_STOCK_ITEMS), "depot slots"),
    "breach_bleed_mult": NumericEffect("breach_bleed_mult", "mult", 1.0, "O2 lost per open breach"),
    "core_income_bonus": NumericEffect("core_income_bonus", "add", 0.0, "fraction added to banked Cores"),
    # Hulls
    "handling_mult": NumericEffect("handling_mult", "mult", 1.0, "responsiveness of the airframe"),
    "auto_turret_limit_bonus": NumericEffect("auto_turret_limit_bonus", "add", 0.0, "turrets over the shared cap"),
}

_FOLDS = {
    "mult": lambda current, value: current * value,
    "add": lambda current, value: current + value,
    "max": max,
    "min": min,
}


@dataclass(frozen=True)
class Effect:
    """One contribution to the effect bag.

    ``kind`` is ``"numeric"`` (``key`` names a :data:`NUMERIC_EFFECTS` entry and
    ``value`` is the contribution) or ``"rule"`` (``key`` is the rule id and
    ``params`` carries whatever the owning module needs to apply it).
    """

    kind: str
    key: str
    value: float = 0.0
    params: dict = field(default_factory=dict)


def _numeric(key: str, value: float) -> Effect:
    return Effect("numeric", key, value=value)


def _rule(rule_id: str, **params) -> Effect:
    return Effect("rule", rule_id, params=params)


class Modifiers(dict):
    """The resolved effect bag a run reads at launch.

    A plain ``dict`` of effect id to value, so it serialises and inspects like
    any other configuration, with typed access on top. Numeric keys are always
    present at their identity; rule ids appear only when the rule is active, and
    map to that rule's parameters. Both accessors reject an unknown id, so a
    consumer that mistypes a key finds out immediately instead of silently
    reading an identity forever.
    """

    def value(self, key: str) -> float:
        """The folded value of numeric *key*."""
        if key not in NUMERIC_EFFECTS:
            raise KeyError(f"unknown numeric effect {key!r}; expected one of {sorted(NUMERIC_EFFECTS)}")
        return float(self[key])

    def scale(self, key: str, base: float) -> float:
        """*base* scaled by numeric *key*, for the multiplicative keys."""
        return base * self.value(key)

    def bonus(self, key: str, base: float = 0.0) -> float:
        """*base* plus numeric *key*, for the additive keys."""
        return base + self.value(key)

    def enabled(self, rule: str) -> bool:
        """Whether rule *rule* is active this run."""
        if rule not in RULE_EFFECTS:
            raise KeyError(f"unknown rule {rule!r}; expected one of {sorted(RULE_EFFECTS)}")
        return rule in self

    def param(self, rule: str, name: str, default=None):
        """One parameter of an active rule, or *default* while it is inactive."""
        if not self.enabled(rule):
            return default
        return self[rule].get(name, default)

    def active_rules(self) -> frozenset[str]:
        """Every rule id currently in the bag."""
        return frozenset(key for key in self if key in RULE_EFFECTS)


def resolve(effects: Iterable[Effect]) -> Modifiers:
    """Fold *effects* into a complete :class:`Modifiers` bag."""
    bag = Modifiers({key: spec.identity for key, spec in NUMERIC_EFFECTS.items()})
    for effect in effects:
        if effect.kind == "numeric":
            spec = NUMERIC_EFFECTS[effect.key]
            bag[effect.key] = _FOLDS[spec.op](bag[effect.key], effect.value)
        elif effect.kind == "rule":
            merged = dict(bag.get(effect.key, {}))
            merged.update(effect.params)
            bag[effect.key] = merged
        else:
            raise ValueError(f"effect {effect.key!r} has unknown kind {effect.kind!r}")
    return bag


# ============================================================================
# The tree's shape
# ============================================================================

#: Node kind per slot, identical in every branch: 7 minors, 4 notables, and the
#: keystone last. Slot order is the order a branch's rows are written below.
_SLOT_KINDS = (
    "minor",
    "minor",
    "notable",
    "minor",
    "minor",
    "notable",
    "minor",
    "notable",
    "minor",
    "minor",
    "notable",
    "keystone",
)

#: Prerequisite slots, as indices into the same branch. Slot 0 hangs off the
#: start hub. The spine runs 0-1-2-3-5-8-10-11, which is the cheapest route to
#: a keystone; slots 4, 6, 7 and 9 are the wider shoulder a full branch buys.
_SLOT_REQUIRES: tuple[tuple[int, ...], ...] = (
    (),
    (0,),
    (1,),
    (2,),
    (2,),
    (3,),
    (4,),
    (6,),
    (5,),
    (7,),
    (8,),
    (10,),
)


@dataclass(frozen=True)
class BranchSpec:
    """One of the five branches radiating from the hub."""

    id: str
    title: str
    theme: str
    keystone: str
    feat: str | None = None


BRANCHES: dict[str, BranchSpec] = {
    "gunnery": BranchSpec("gunnery", "Gunnery", "fire rate and the ammunition economy", "dead_reckoning"),
    "engineering": BranchSpec(
        "engineering", "Engineering", "capacitor, panels and damage control", "overload_discharge"
    ),
    "silent_running": BranchSpec("silent_running", "Silent Running", "signature control", "cold_start"),
    "salvage": BranchSpec("salvage", "Salvage", "scoop, prices and conversion rates", "magpie_protocol"),
    "predation": BranchSpec(
        "predation", "Predation", "standing and fighting the hunter", "quillborn", feat=FEAT_FIRST_QUILL
    ),
}


@dataclass(frozen=True)
class DoctrineNode:
    """One purchasable node.

    ``requires`` names nodes in the same branch, all of which must be owned
    first. ``feat`` is an extra gate the profile has to satisfy, used for the
    Predation branch and for Deep Insertion.
    """

    id: str
    branch: str
    kind: str
    title: str
    description: str
    effect: Effect
    requires: tuple[str, ...] = ()
    feat: str | None = None

    @property
    def cost(self) -> int:
        """What the node costs in Cores, fixed by its kind."""
        return NODE_COSTS[self.kind]

    @property
    def numeric(self) -> bool:
        """Whether the node moves a number rather than changing a rule."""
        return self.effect.kind == "numeric"


# Branch rows, in slot order: (node id, title, effect, description). The kind,
# cost and prerequisites come from the shared slot tables above, so a branch
# reads as twelve statements of intent and cannot drift out of shape.

_GUNNERY_ROWS = (
    ("gunnery_steady_hands", "Steady Hands", _numeric("fire_rate_mult", FIRE_RATE_STEP), "Every weapon cycles faster."),
    (
        "gunnery_deep_magazines",
        "Deep Magazines",
        _numeric("ammo_box_rounds_mult", AMMO_BOX_ROUNDS_STEP),
        "An ammunition box carries more rounds for the same price.",
    ),
    (
        "gunnery_salvaged_barrels",
        "Salvaged Barrels",
        _rule("reload_while_moving"),
        "Reloading no longer roots the ship; you may thrust through it.",
    ),
    (
        "gunnery_hot_loading",
        "Hot Loading",
        _numeric("reload_speed_mult", RELOAD_SPEED_STEP),
        "Ballistic reloads finish sooner.",
    ),
    (
        "gunnery_tight_chokes",
        "Tight Chokes",
        _numeric("ballistic_damage_mult", BALLISTIC_DAMAGE_STEP),
        "Ballistic rounds hit a little harder.",
    ),
    (
        "gunnery_overpressure",
        "Overpressure",
        _rule("first_shot_after_reload_pierces"),
        "The first shot out of a fresh magazine punches through its target.",
    ),
    (
        "gunnery_casing_reclaim",
        "Casing Reclaim",
        _rule("ballistic_kills_shed_brass", scrap=CASING_RECLAIM_SCRAP_PER_KILL),
        "A kill made with ballistics sheds its brass as scrap.",
    ),
    (
        "gunnery_field_stripping",
        "Field Stripping",
        _rule("fabricator_prints_any_calibre"),
        "The Fabricator prints a box for any ballistic weapon you carry, not just the one it was cut for.",
    ),
    (
        "gunnery_tracer_discipline",
        "Tracer Discipline",
        _rule("hits_mark_targets"),
        "A hit marks its target, which stays legible through nebula muffling.",
    ),
    (
        "gunnery_shell_sorting",
        "Shell Sorting",
        _rule("shared_ammunition_pool"),
        "One ammunition pool feeds every ballistic calibre aboard.",
    ),
    (
        "gunnery_ammunition_sovereignty",
        "Ammunition Sovereignty",
        _rule("depots_always_stock_ammunition"),
        "Every depot stocks ammunition, whatever else its shelves rolled.",
    ),
    (
        "dead_reckoning",
        "Dead Reckoning",
        _rule("dead_reckoning", energy_weapons_disabled=True),
        "Ballistic shots pierce everything they hit. Energy weapons will not fire at all.",
    ),
)

_ENGINEERING_ROWS = (
    (
        "engineering_thicker_panels",
        "Thicker Panels",
        _numeric("solar_wing_hp_mult", SOLAR_WING_HP_STEP),
        "Solar panels take more punishment before they shear.",
    ),
    (
        "engineering_wider_bus",
        "Wider Bus",
        _numeric("capacitor_max_bonus", CAPACITOR_MAX_STEP),
        "The capacitor holds a larger charge.",
    ),
    (
        "engineering_hot_patch",
        "Hot Patch",
        _rule("patch_breach_while_moving"),
        "Breach foam sets while you fly; patching no longer roots the ship.",
    ),
    (
        "engineering_cold_windings",
        "Cold Windings",
        _numeric("generator_fuel_burn_mult", GENERATOR_FUEL_BURN_STEP),
        "The generator burns less fuel for the same output.",
    ),
    (
        "engineering_shield_conditioning",
        "Shield Conditioning",
        _numeric("shield_absorb_mult", SHIELD_ABSORB_STEP),
        "The arc absorbs more before it breaks.",
    ),
    (
        "engineering_spool_bracing",
        "Spool Bracing",
        _rule("spool_uninterruptible_at_low_hull", hull_fraction=SPOOL_BRACING_HULL_FRACTION),
        "Below a quarter hull the warp spool cannot be interrupted at all.",
    ),
    (
        "engineering_quick_retract",
        "Quick Retract",
        _rule("panels_retract_instantly"),
        "Solar panels snap shut instantly instead of folding.",
    ),
    (
        "engineering_arc_grounding",
        "Arc Grounding",
        _rule("shield_break_browns_capacitor"),
        "A broken arc dumps its charge into the bus rather than locking the emitter out.",
    ),
    (
        "engineering_brownout_reserve",
        "Brownout Reserve",
        _rule("refund_first_energy_denial", per_sector=BROWNOUT_REFUNDS_PER_SECTOR),
        "A reserve cell covers the first energy request a sector denies you.",
    ),
    (
        "engineering_redundant_feeds",
        "Redundant Feeds",
        _rule("destroyed_wings_keep_generating"),
        "A sheared panel keeps feeding the bus until the sector ends.",
    ),
    (
        "engineering_field_welding",
        "Field Welding",
        _rule("patch_restores_nearest_wing"),
        "Patching a breach also welds the nearest destroyed panel back on.",
    ),
    (
        "overload_discharge",
        "Overload Discharge",
        _rule("shield_break_emp_nova"),
        "A broken shield releases an EMP nova. Your worst moment becomes a tool.",
    ),
)

_SILENT_ROWS = (
    (
        "silent_muffled_hull",
        "Muffled Hull",
        _numeric("signature_fill_mult", MUFFLED_HULL_SIGNATURE_STEP),
        "Everything you do reads a little quieter.",
    ),
    (
        "silent_cold_thrusters",
        "Cold Thrusters",
        _numeric("silent_speed_mult", SILENT_SPEED_STEP),
        "Silent running costs you less speed.",
    ),
    (
        "silent_quiet_kills",
        "Quiet Kills",
        _rule("kills_are_silent_while_dark"),
        "A kill made under silent running adds no signature at all.",
    ),
    (
        "silent_deep_decay",
        "Deep Decay",
        _numeric("signature_decay_bonus", SIGNATURE_DECAY_STEP),
        "The meter falls faster while you are dark.",
    ),
    (
        "silent_baffled_generator",
        "Baffled Generator",
        _numeric("generator_signature_mult", GENERATOR_SIGNATURE_STEP),
        "The generator's contribution to the meter is baffled down.",
    ),
    (
        "silent_false_echo",
        "False Echo",
        _rule("jettisoned_scrap_is_a_decoy"),
        "Jettisoned scrap plants a false echo the lantern sweeps instead of you.",
    ),
    (
        "silent_shadow_scoop",
        "Shadow Scoop",
        _rule("scoop_is_silent_while_dark"),
        "The tractor scoop makes no noise while silent running is engaged.",
    ),
    (
        "silent_lantern_read",
        "Lantern Read",
        _rule("draw_lantern_path_early", lead_s=LANTERN_READ_LEAD_S),
        "The lantern's sweep path is drawn a second before it burns.",
    ),
    (
        "silent_dead_bus",
        "Dead Bus",
        _rule("silent_running_without_charge"),
        "Silent running can be entered on an empty capacitor.",
    ),
    (
        "silent_nebula_lungs",
        "Nebula Lungs",
        _rule("muffling_covers_generator"),
        "Biome muffling covers the generator hum as well as the hull.",
    ),
    (
        "silent_ghost_wake",
        "Ghost Wake",
        _rule("wakeless_jump", jumps=GHOST_WAKE_JUMPS_PER_SECTOR),
        "One jump per sector leaves no column in the Wake.",
    ),
    (
        "cold_start",
        "Cold Start",
        _rule("cold_start", seconds=balance.COLD_START_INVISIBLE_S),
        "Every sector opens powered down and invisible. The ambush predator's opening.",
    ),
)

_SALVAGE_ROWS = (
    (
        "salvage_underwriting",
        "Underwriting",
        _numeric("death_convert_rate", balance.CONVERT_RATE_DEATH_UPGRADED),
        "Scrap in the hold when you die converts at a better rate.",
    ),
    (
        "salvage_wide_scoop",
        "Wide Scoop",
        _numeric("scoop_radius_mult", SCOOP_RADIUS_STEP),
        "The tractor scoop reaches further.",
    ),
    (
        "salvage_extra_bearing",
        "Extra Bearing",
        _rule("chart_shows_extra_destination", destinations=EXTRA_BEARING_DESTINATIONS),
        "The chart offers one more destination than the route would allow.",
    ),
    (
        "salvage_haggling",
        "Haggling",
        _numeric("depot_price_mult", DEPOT_PRICE_STEP),
        "Depots charge you less.",
    ),
    (
        "salvage_refinery_tuning",
        "Refinery Tuning",
        _numeric("refinery_rate_bonus", REFINERY_RATE_STEP),
        "A refinery batch pays more Cores per batch.",
    ),
    (
        "salvage_pity_reroll",
        "Pity Reroll",
        _rule("free_pity_slot_reroll"),
        "A depot's pity slot may be rerolled once for nothing.",
    ),
    (
        "salvage_magnetic_sort",
        "Magnetic Sort",
        _rule("scoop_pulls_boxes_and_consumables"),
        "The scoop pulls ammunition boxes and consumables, not just scrap.",
    ),
    (
        "salvage_deep_insertion",
        "Deep Insertion",
        _rule(
            "deep_insertion",
            sector=balance.DEEP_INSERTION_START_SECTOR,
            signature=balance.DEEP_INSERTION_START_SIGNATURE,
        ),
        "Start the run deep, hot, and with no Act 1 income. For pilots who have solved the Shallows.",
    ),
    (
        "salvage_wreck_sense",
        "Wreck Sense",
        _rule("mark_unlooted_wrecks"),
        "Unlooted wrecks are marked the moment you enter a sector.",
    ),
    (
        "salvage_jettison_ledger",
        "Jettison Ledger",
        _rule("fed_scrap_still_scores"),
        "Scrap fed to the Shrike still counts toward the run score.",
    ),
    (
        "salvage_field_refinery",
        "Field Refinery",
        _rule("refinery_survives_docking"),
        "A refinery batch keeps running while you dock, trade and undock.",
    ),
    (
        "magpie_protocol",
        "Magpie Protocol",
        _rule("magpie_protocol", fraction=balance.MAGPIE_SALVAGE_FRACTION),
        "Stolen and destroyed salvage is collected automatically at half value. No scoop pass needed.",
    ),
)

_PREDATION_ROWS = (
    (
        "predation_quill_edge",
        "Quill Edge",
        _numeric("shrike_damage_mult", SHRIKE_DAMAGE_STEP),
        "You cut the hide deeper.",
    ),
    (
        "predation_fin_shear",
        "Fin Shear",
        _numeric("shrike_fin_damage_mult", SHRIKE_FIN_DAMAGE_STEP),
        "Fin plating gives way sooner.",
    ),
    (
        "predation_barbed_rounds",
        "Barbed Rounds",
        _rule("lockout_scrambles_warp_only"),
        "The arrival lockout scrambles the warp drive and nothing else; your shots still land.",
    ),
    (
        "predation_steady_nerve",
        "Steady Nerve",
        _numeric("lockout_duration_mult", LOCKOUT_DURATION_STEP),
        "The lockout is over sooner.",
    ),
    (
        "predation_fletching_luck",
        "Fletching Luck",
        _numeric("fletching_drop_mult", FLETCHING_DROP_STEP),
        "Heralds part with Fletchings more readily.",
    ),
    (
        "predation_counter_lantern",
        "Counter Lantern",
        _rule("dodged_sweep_refunds_capacitor", capacitor=COUNTER_LANTERN_CAPACITOR),
        "A sweep you dodge clean feeds the capacitor instead of the hull.",
    ),
    (
        "predation_carrion_sense",
        "Carrion Sense",
        _rule("heralds_drop_fuel", fuel=HERALD_FUEL_DROP),
        "Heralds drop fuel, which turns an arrival into a resupply.",
    ),
    (
        "predation_feeding_tax",
        "Feeding Tax",
        _rule("feeding_buys_double_time", multiplier=FEEDING_TAX_MULTIPLIER),
        "Scrap fed to the Shrike buys twice the seconds.",
    ),
    (
        "predation_scent_of_blood",
        "Scent of Blood",
        _rule("sheared_segments_stay_marked"),
        "A segment you have sheared stays marked, so the next cut is aimed.",
    ),
    (
        "predation_readable_ladder",
        "Readable Ladder",
        _rule("telegraph_never_compresses"),
        "The telegraph ladder never compresses past its second rung, however many arrivals you have taken.",
    ),
    (
        "predation_undertow",
        "Undertow",
        _rule("departure_sheds_plating"),
        "The Shrike's departure leaves a field of its own shed plating behind.",
    ),
    (
        "quillborn",
        "Quillborn",
        _rule("quillborn"),
        "While the Shrike is present its damage ramp ramps yours too. The stand-and-fight covenant.",
    ),
)

_BRANCH_ROWS = {
    "gunnery": _GUNNERY_ROWS,
    "engineering": _ENGINEERING_ROWS,
    "silent_running": _SILENT_ROWS,
    "salvage": _SALVAGE_ROWS,
    "predation": _PREDATION_ROWS,
}

#: Nodes that carry an unlock gate their branch does not. Such a node must sit
#: on a shoulder slot, never on the spine, or it would gate the branch's
#: keystone behind a feat the keystone has nothing to do with;
#: :func:`_validate_tree` enforces that.
_NODE_FEATS = {"salvage_deep_insertion": FEAT_FIRST_EXTRACTION}


def _build_tree() -> dict[str, DoctrineNode]:
    """Expand the branch rows into the full sixty-node tree."""
    tree: dict[str, DoctrineNode] = {}
    for branch_id in balance.DOCTRINE_BRANCHES_IDS:
        rows = _BRANCH_ROWS[branch_id]
        ids = [row[0] for row in rows]
        for slot, (node_id, title, effect, description) in enumerate(rows):
            feat = _NODE_FEATS.get(node_id) or BRANCHES[branch_id].feat
            tree[node_id] = DoctrineNode(
                id=node_id,
                branch=branch_id,
                kind=_SLOT_KINDS[slot],
                title=title,
                description=description,
                effect=effect,
                requires=tuple(ids[index] for index in _SLOT_REQUIRES[slot]),
                feat=feat,
            )
    return tree


#: Every doctrine node, keyed by id, in branch then slot order.
#:
#: Values are frozen :class:`DoctrineNode` records rather than bare dictionaries:
#: a mistyped field is then a construction error at import instead of a missing
#: key at run start.
DOCTRINE_TREE: dict[str, DoctrineNode] = _build_tree()

#: Every rule id any source may raise, with the node, rank or hull that owns it.
#: Built after the tree so :class:`Modifiers` can reject an unknown rule.
RULE_EFFECTS: dict[str, str] = {}


def branch_nodes(branch_id: str) -> tuple[DoctrineNode, ...]:
    """Every node in *branch_id*, in slot order."""
    if branch_id not in BRANCHES:
        raise ValueError(f"unknown branch {branch_id!r}; expected one of {sorted(BRANCHES)}")
    return tuple(node for node in DOCTRINE_TREE.values() if node.branch == branch_id)


def keystone_ids() -> tuple[str, ...]:
    """The five keystone node ids, in branch order."""
    return tuple(balance.DOCTRINE_KEYSTONES[branch] for branch in balance.DOCTRINE_BRANCHES_IDS)


def tree_cost() -> int:
    """What buying every node costs in Cores."""
    return sum(node.cost for node in DOCTRINE_TREE.values())


def prerequisites_of(node_id: str) -> frozenset[str]:
    """Every node that must be owned before *node_id* can be bought."""
    node = DOCTRINE_TREE.get(node_id)
    if node is None:
        raise ValueError(f"unknown doctrine node {node_id!r}")
    closure: set[str] = set()
    frontier = list(node.requires)
    while frontier:
        current = frontier.pop()
        if current in closure:
            continue
        closure.add(current)
        frontier.extend(DOCTRINE_TREE[current].requires)
    return frozenset(closure)


def path_cost_to(node_id: str) -> int:
    """What reaching *node_id* costs, the node and its prerequisites together."""
    return DOCTRINE_TREE[node_id].cost + sum(DOCTRINE_TREE[step].cost for step in prerequisites_of(node_id))


# ============================================================================
# Hulls
# ============================================================================


@dataclass(frozen=True)
class HullSpec:
    """One hull: its unlock feat, its character, and the effects it carries.

    The socket *count* is balance's; the socket *layout* belongs to
    ``modules.py`` and is reached through :func:`hull_socket_layout`.
    """

    id: str
    title: str
    feat: str | None
    description: str
    effects: tuple[Effect, ...] = ()

    @property
    def sockets(self) -> int:
        """How many sockets the hull carries."""
        return balance.HULL_SOCKETS[self.id]


HULLS: dict[str, HullSpec] = {
    "vagrant": HullSpec(
        "vagrant",
        "Vagrant",
        None,
        "The starter: balanced sockets, balanced handling, no opinion of its own.",
    ),
    "barge": HullSpec(
        "barge",
        "Barge",
        f"extract carrying at least {balance.BARGE_UNLOCK_SCRAP_CARRIED} scrap",
        "The Fortress chassis: two more sockets, and it turns like a moon.",
        effects=(_numeric("handling_mult", BARGE_HANDLING_MULT),),
    ),
    "dart": HullSpec(
        "dart",
        "Dart",
        "escape a Shrike arrival untouched",
        "The Salvager's: two fewer sockets, slippery, and it reads quieter to the hunter.",
        effects=(
            _numeric("handling_mult", DART_HANDLING_MULT),
            _numeric("signature_fill_mult", balance.DART_SIGNATURE_FILL_MULT),
        ),
    ),
    "hive": HullSpec(
        "hive",
        "Hive",
        f"extract at Hunt Rank {balance.HIVE_UNLOCK_HUNT_RANK}",
        "The Carrier fantasy: a drone-centric socket layout and bays for two turrets over the cap.",
        effects=(
            _rule("drone_centric_sockets"),
            _numeric("auto_turret_limit_bonus", HIVE_EXTRA_TURRETS),
        ),
    ),
}


def hull_socket_layout(hull_id: str) -> tuple:
    """The hull's socket layout, as ``modules.Socket`` records.

    Imported on demand so that opening the doctrine screen does not drag the
    whole run-time module stack in behind it.
    """
    from .modules import sockets_for_hull

    return sockets_for_hull(hull_id)


def hull_feat_met(hull_id: str, ledger: dict, profile: dict) -> bool:
    """Whether the run described by *ledger* earns *hull_id*."""
    if hull_id not in HULLS:
        raise ValueError(f"unknown hull {hull_id!r}; expected one of {sorted(HULLS)}")
    extracted = ledger.get("outcome") == "extracted"
    if hull_id == "barge":
        return extracted and float(ledger.get("scrap_carried", 0.0)) >= balance.BARGE_UNLOCK_SCRAP_CARRIED
    if hull_id == "dart":
        return bool(ledger.get("arrival_escaped_untouched"))
    if hull_id == "hive":
        return extracted and int(profile.get("hunt_rank", 0)) >= balance.HIVE_UNLOCK_HUNT_RANK
    return False


# ============================================================================
# Hunt Ranks
# ============================================================================


@dataclass(frozen=True)
class HuntRank:
    """One ascension tier: a single legible modifier, plus its Core income."""

    rank: int
    title: str
    description: str
    effects: tuple[Effect, ...]


HUNT_RANK_TIERS: dict[int, HuntRank] = {
    1: HuntRank(
        1,
        "Marked",
        "The signature meter fills faster.",
        (_numeric("signature_fill_mult", balance.HUNT_RANK1_SIGNATURE_FILL_MULT),),
    ),
    2: HuntRank(
        2,
        "Watched",
        "Depots stock one item fewer.",
        (_numeric("depot_stock_items", float(balance.HUNT_RANK2_DEPOT_STOCK_ITEMS)),),
    ),
    3: HuntRank(
        3,
        "Bled",
        "Breaches bleed oxygen at double the rate.",
        (_numeric("breach_bleed_mult", balance.HUNT_RANK3_BREACH_BLEED_MULT),),
    ),
    4: HuntRank(
        4,
        "Swept",
        "The lantern sweeps during phase-1 arrivals, in ordinary sectors.",
        (_rule("lantern_sweeps_during_phase_one"),),
    ),
}


def hunt_rank_effects(rank: int) -> list[Effect]:
    """Every effect a profile at *rank* carries, income bonus included.

    Ranks above ``balance.HUNT_RANKS_AT_LAUNCH`` contribute their Core income
    but no modifier, because ranks 5 to 8 are not implemented yet; asking for
    one is not an error, it simply gains nothing beyond the income.
    """
    if rank < 0 or rank > balance.HUNT_RANKS_TOTAL:
        raise ValueError(f"Hunt Rank {rank} is outside 0..{balance.HUNT_RANKS_TOTAL}")
    effects: list[Effect] = []
    for tier in range(1, rank + 1):
        effects.append(_numeric("core_income_bonus", balance.HUNT_RANK_CORE_INCOME_BONUS))
        entry = HUNT_RANK_TIERS.get(tier)
        if entry is not None:
            effects.extend(entry.effects)
    return effects


# ============================================================================
# Registry construction and the design law
# ============================================================================


def _all_effects() -> Iterable[tuple[Effect, str]]:
    """Every effect declared anywhere, paired with the source that owns it."""
    for node in DOCTRINE_TREE.values():
        yield node.effect, f"doctrine node {node.id!r}"
    for hull in HULLS.values():
        for effect in hull.effects:
            yield effect, f"hull {hull.id!r}"
    for tier in HUNT_RANK_TIERS.values():
        for effect in tier.effects:
            yield effect, f"Hunt Rank {tier.rank}"


def _build_rule_registry() -> None:
    """Collect every rule id, refusing a collision with a numeric key."""
    for effect, owner in _all_effects():
        if effect.kind == "numeric":
            if effect.key not in NUMERIC_EFFECTS:
                raise ValueError(f"{owner} writes unregistered numeric key {effect.key!r}")
            continue
        if effect.key in NUMERIC_EFFECTS:
            raise ValueError(f"{owner} declares rule {effect.key!r}, which is also a numeric key")
        RULE_EFFECTS.setdefault(effect.key, owner)


def _validate_tree() -> None:
    """Check the tree against balance.py and the design law, at import.

    A tree that has quietly drifted out of shape is a balance bug nobody sees
    until a player counts the nodes, so it is a hard failure here instead.
    """
    if tuple(BRANCHES) != tuple(balance.DOCTRINE_BRANCHES_IDS):
        raise ValueError(f"branches {tuple(BRANCHES)} do not match balance.DOCTRINE_BRANCHES_IDS")
    if len(DOCTRINE_TREE) != balance.DOCTRINE_NODES:
        raise ValueError(f"tree has {len(DOCTRINE_TREE)} nodes, balance says {balance.DOCTRINE_NODES}")

    for branch_id in BRANCHES:
        nodes = branch_nodes(branch_id)
        if len(nodes) != balance.DOCTRINE_NODES_PER_BRANCH:
            raise ValueError(f"branch {branch_id!r} has {len(nodes)} nodes")
        counts = {kind: sum(1 for node in nodes if node.kind == kind) for kind in NODE_COSTS}
        expected = {
            "minor": balance.DOCTRINE_MINORS_PER_BRANCH,
            "notable": balance.DOCTRINE_NOTABLES_PER_BRANCH,
            "keystone": balance.DOCTRINE_KEYSTONES_PER_BRANCH,
        }
        if counts != expected:
            raise ValueError(f"branch {branch_id!r} has node kinds {counts}, expected {expected}")
        keystone = balance.DOCTRINE_KEYSTONES[branch_id]
        if keystone not in DOCTRINE_TREE or DOCTRINE_TREE[keystone].kind != "keystone":
            raise ValueError(f"branch {branch_id!r} is missing its keystone {keystone!r}")

    if tree_cost() != balance.DOCTRINE_FULL_TREE_CORES:
        raise ValueError(f"the full tree costs {tree_cost()}, balance says {balance.DOCTRINE_FULL_TREE_CORES}")

    seen: set[str] = set()
    for node in DOCTRINE_TREE.values():
        for required in node.requires:
            if required not in DOCTRINE_TREE:
                raise ValueError(f"node {node.id!r} requires unknown node {required!r}")
            if DOCTRINE_TREE[required].branch != node.branch:
                raise ValueError(f"node {node.id!r} requires {required!r} from another branch")
            if required not in seen:
                raise ValueError(f"node {node.id!r} requires {required!r}, which is not declared before it")
        seen.add(node.id)

    for branch_id, keystone in balance.DOCTRINE_KEYSTONES.items():
        branch_feat = BRANCHES[branch_id].feat
        for step in prerequisites_of(keystone):
            if DOCTRINE_TREE[step].feat != branch_feat:
                raise ValueError(
                    f"keystone {keystone!r} is gated behind {step!r}, which carries the extra feat "
                    f"{DOCTRINE_TREE[step].feat!r}; a feat-gated node belongs on a shoulder slot"
                )

    numeric = sum(1 for node in DOCTRINE_TREE.values() if node.numeric)
    if numeric * 3 > balance.DOCTRINE_NODES:
        raise ValueError(
            f"{numeric} of {balance.DOCTRINE_NODES} nodes are numeric; the design law allows at most one third"
        )


_build_rule_registry()
_validate_tree()


# ============================================================================
# Milestones
# ============================================================================

#: The five first-run bounties in the order the design lists them. The ids and
#: their prices are ``save.MILESTONE_CORES``; this fixes the presentation order.
MILESTONE_ORDER: tuple[str, ...] = (
    "first_extraction",
    "first_vault",
    "first_elite_kill",
    "first_act3_entry",
    "first_arrival_survived",
)

MILESTONE_TITLES: dict[str, str] = {
    "first_extraction": "First Extraction",
    "first_vault": "First Vault Cracked",
    "first_elite_kill": "First Elite Killed",
    "first_act3_entry": "First Descent to Act 3",
    "first_arrival_survived": "First Arrival Survived",
}

if set(MILESTONE_ORDER) != set(save.MILESTONE_CORES):
    raise ValueError("MILESTONE_ORDER has drifted from save.MILESTONE_CORES")


def milestone_bounty(milestone_id: str) -> int:
    """The Cores paid the first time *milestone_id* is achieved."""
    try:
        return save.MILESTONE_CORES[milestone_id]
    except KeyError:
        raise ValueError(
            f"unknown milestone {milestone_id!r}; expected one of {sorted(save.MILESTONE_CORES)}"
        ) from None


# ============================================================================
# The profile node
# ============================================================================


class MetaProfile(Node):
    """The tree singleton owning everything that persists between runs.

    Added by ``flow.py`` as ``Services.META``. The profile dictionary is the one
    ``save.py`` reads and writes; this node is the only thing that interprets
    it. Nothing here reads live run state: a run is configured by the
    :class:`Modifiers` bag handed over at launch, so changing the tree
    mid-flight cannot alter the run in progress.
    """

    doctrine_changed = Signal(str, bool)  # SignalNames.DOCTRINE_CHANGED

    def __init__(self, profile: dict | None = None, **kwargs):
        super().__init__(**kwargs)
        self._explicit_profile = profile is not None
        self.profile: dict = save.default_profile()
        if profile is not None:
            self.adopt(profile)

    # -- lifecycle and persistence ----------------------------------------

    def on_ready(self):
        if self._explicit_profile:
            return
        system = self.save_system()
        if system is not None:
            self.profile = system.load_profile()

    def save_system(self):
        """The ``Services.SAVE`` singleton, or None while none is registered."""
        tree = self.tree
        if tree is None:
            return None
        return tree.singletons.get(Services.SAVE)

    def adopt(self, profile: dict) -> None:
        """Take *profile* as the live profile, filling anything it omits.

        A dictionary without a ``schema_version`` is assumed to be current,
        which is what makes a hand-built profile usable in a test or a debug
        console without reaching into the migration machinery.
        """
        payload = dict(profile)
        payload.setdefault("schema_version", save.PROFILE_SCHEMA_VERSION)
        self.profile = save.migrate_profile(payload)
        self._explicit_profile = True

    def persist(self) -> bool:
        """Write the profile through the save system; False if there is none."""
        system = self.save_system()
        if system is None:
            log.debug("MetaProfile has no SaveSystem singleton; the profile stays in memory")
            return False
        system.save_profile(self.profile)
        return True

    # -- Cores -------------------------------------------------------------

    def cores(self) -> int:
        """Cores banked and unspent."""
        return int(self.profile["cores"])

    def add_cores(self, amount: int, reason: str = "") -> int:
        """Bank *amount* Cores and return the new total."""
        if amount < 0:
            raise ValueError(f"add_cores takes a positive amount, got {amount}")
        self.profile["cores"] = self.cores() + int(amount)
        log.debug("banked %d Cores (%s), now %d", amount, reason or "unspecified", self.profile["cores"])
        return self.cores()

    def core_income_multiplier(self) -> float:
        """What a run's banked Cores are multiplied by, from Hunt Ranks."""
        return 1.0 + resolve(hunt_rank_effects(self.hunt_rank())).value("core_income_bonus")

    # -- the doctrine tree -------------------------------------------------

    def owned_nodes(self) -> tuple[str, ...]:
        """Every doctrine node bought, in purchase order."""
        return tuple(self.profile["doctrine"]["owned"])

    def is_owned(self, node_id: str) -> bool:
        """Whether *node_id* has been bought."""
        return node_id in self.profile["doctrine"]["owned"]

    def spent_cores(self) -> int:
        """What the current tree cost to buy."""
        return sum(DOCTRINE_TREE[node_id].cost for node_id in self.owned_nodes())

    def feat_met(self, feat: str | None) -> bool:
        """Whether the profile satisfies an unlock *feat*."""
        if feat is None:
            return True
        if feat == FEAT_FIRST_EXTRACTION:
            return int(self.profile["runs_extracted"]) > 0
        if feat == FEAT_FIRST_QUILL:
            return int(self.profile["quills"]) > 0
        raise ValueError(f"unknown feat {feat!r}")

    def purchase_blocker(self, node_id: str) -> str | None:
        """Why *node_id* cannot be bought right now, or None if it can.

        The reason is written for the doctrine screen to show verbatim.
        """
        node = DOCTRINE_TREE.get(node_id)
        if node is None:
            raise ValueError(f"unknown doctrine node {node_id!r}")
        if self.is_owned(node_id):
            return "already bought"
        if not self.feat_met(node.feat):
            return f"locked until you {FEAT_PROSE.get(node.feat, node.feat)}"
        missing = [required for required in node.requires if not self.is_owned(required)]
        if missing:
            names = ", ".join(DOCTRINE_TREE[required].title for required in missing)
            return f"requires {names}"
        if self.cores() < node.cost:
            return f"costs {node.cost} Cores, you have {self.cores()}"
        return None

    def available_nodes(self) -> tuple[str, ...]:
        """Every node that could be bought right now."""
        return tuple(node_id for node_id in DOCTRINE_TREE if self.purchase_blocker(node_id) is None)

    def buy_node(self, node_id: str) -> bool:
        """Buy *node_id*, spending its Cores. False if anything blocks it.

        A keystone bought while fewer than
        ``balance.DOCTRINE_MAX_ACTIVE_KEYSTONES`` are active becomes active at
        once, so a player with room never has to visit a second screen to use
        what they just bought.
        """
        blocker = self.purchase_blocker(node_id)
        if blocker is not None:
            log.debug("cannot buy %s: %s", node_id, blocker)
            return False
        node = DOCTRINE_TREE[node_id]
        self.profile["cores"] = self.cores() - node.cost
        self.profile["doctrine"]["owned"].append(node_id)
        if node.kind == "keystone" and len(self.active_keystones()) < balance.DOCTRINE_MAX_ACTIVE_KEYSTONES:
            self.profile["doctrine"]["active_keystones"].append(node_id)
        self.doctrine_changed.emit(node_id, True)
        return True

    def respec(self) -> int:
        """Refund every Core spent and empty the tree; returns the refund.

        Free and total, by design: the tree is a loadout language. Called
        between runs, when a run's :class:`Modifiers` have already been taken.
        """
        refund = self.spent_cores()
        removed = self.owned_nodes()
        self.profile["doctrine"]["owned"] = []
        self.profile["doctrine"]["active_keystones"] = []
        self.profile["cores"] = self.cores() + refund
        for node_id in removed:
            self.doctrine_changed.emit(node_id, False)
        return refund

    # -- keystones ---------------------------------------------------------

    def owned_keystones(self) -> tuple[str, ...]:
        """Every keystone bought, whether or not it is active."""
        return tuple(node_id for node_id in self.owned_nodes() if DOCTRINE_TREE[node_id].kind == "keystone")

    def active_keystones(self) -> list[str]:
        """The keystones taken into the next run, at most two of them."""
        return list(self.profile["doctrine"]["active_keystones"])

    def set_active_keystones(self, node_ids: Sequence[str]) -> None:
        """Choose the keystones for the next run.

        Raises rather than truncating: silently dropping the third choice would
        launch a run the player did not configure.
        """
        chosen = list(dict.fromkeys(node_ids))
        if len(chosen) > balance.DOCTRINE_MAX_ACTIVE_KEYSTONES:
            raise ValueError(
                f"at most {balance.DOCTRINE_MAX_ACTIVE_KEYSTONES} keystones may be active, got {len(chosen)}"
            )
        for node_id in chosen:
            node = DOCTRINE_TREE.get(node_id)
            if node is None or node.kind != "keystone":
                raise ValueError(f"{node_id!r} is not a keystone")
            if not self.is_owned(node_id):
                raise ValueError(f"keystone {node_id!r} has not been bought")
        self.profile["doctrine"]["active_keystones"] = chosen

    # -- the resolved effect bag -------------------------------------------

    def doctrine_effects(self) -> list[Effect]:
        """The effects the owned tree contributes, keystones filtered to active."""
        active = set(self.active_keystones())
        effects = []
        for node_id in self.owned_nodes():
            node = DOCTRINE_TREE[node_id]
            if node.kind == "keystone" and node_id not in active:
                continue
            effects.append(node.effect)
        return effects

    def modifiers(self) -> Modifiers:
        """The complete effect bag for the next run.

        Doctrine, active keystones, Hunt Rank and the selected hull, folded into
        one flat dictionary. ``flow.py`` takes this once at launch and passes it
        in the ``RUN_STARTED`` configuration; nothing reads it again mid-run.
        """
        effects = list(self.doctrine_effects())
        effects.extend(hunt_rank_effects(self.hunt_rank()))
        effects.extend(HULLS[self.selected_hull()].effects)
        return resolve(effects)

    # -- hulls -------------------------------------------------------------

    def unlocked_hulls(self) -> tuple[str, ...]:
        """Every hull the player may launch in."""
        return tuple(self.profile["hulls"]["unlocked"])

    def selected_hull(self) -> str:
        """The hull the next run launches in."""
        return self.profile["hulls"]["selected"]

    def select_hull(self, hull_id: str) -> None:
        """Choose the hull for the next run."""
        if hull_id not in self.unlocked_hulls():
            raise ValueError(f"hull {hull_id!r} is not unlocked")
        self.profile["hulls"]["selected"] = hull_id

    def unlock_hull(self, hull_id: str) -> bool:
        """Unlock *hull_id*; False if it was already unlocked."""
        if hull_id not in HULLS:
            raise ValueError(f"unknown hull {hull_id!r}; expected one of {sorted(HULLS)}")
        if hull_id in self.unlocked_hulls():
            return False
        self.profile["hulls"]["unlocked"].append(hull_id)
        return True

    # -- milestones --------------------------------------------------------

    def milestone_claimed(self, milestone_id: str) -> bool:
        """Whether the bounty for *milestone_id* has already been paid."""
        milestone_bounty(milestone_id)
        return bool(self.profile["milestones"].get(milestone_id, False))

    def unclaimed_milestones(self) -> tuple[str, ...]:
        """The bounties still outstanding, in presentation order."""
        return tuple(mid for mid in MILESTONE_ORDER if not self.milestone_claimed(mid))

    def claim_milestone(self, milestone_id: str) -> int:
        """Pay the bounty for *milestone_id* once; 0 if already claimed."""
        bounty = milestone_bounty(milestone_id)
        if self.milestone_claimed(milestone_id):
            return 0
        self.profile["milestones"][milestone_id] = True
        self.add_cores(bounty, f"milestone {milestone_id}")
        return bounty

    # -- Hunt Ranks --------------------------------------------------------

    def hunt_rank(self) -> int:
        """The current ascension tier, one per Roost kill."""
        return int(self.profile["hunt_rank"])

    def award_hunt_rank(self) -> int:
        """Advance one Hunt Rank and return the new one.

        Clamped at ``balance.HUNT_RANKS_AT_LAUNCH``: ranks 5 to 8 are designed
        but not implemented, and handing one out would promise a remix of the
        hunter that does not exist yet.
        """
        rank = min(self.hunt_rank() + 1, balance.HUNT_RANKS_AT_LAUNCH)
        self.profile["hunt_rank"] = rank
        return rank

    # -- ending a run ------------------------------------------------------

    def note_run_started(self) -> int:
        """Count a launch and return the run number, counting from one."""
        self.profile["runs_started"] = int(self.profile["runs_started"]) + 1
        return int(self.profile["runs_started"])

    def run_score(self, ledger: dict) -> int:
        """The run score the death and extraction ledgers rank on."""
        return int(
            float(ledger.get("scrap_earned", 0.0))
            + float(ledger.get("cores_banked", 0.0)) * balance.SCORE_CORES_WEIGHT
            + int(ledger.get("quills", 0)) * balance.SCORE_QUILLS_WEIGHT
            + int(ledger.get("deepest_sector", 0)) * SCORE_DEPTH_BONUS_PER_SECTOR
        )

    def record_run(self, ledger: dict) -> dict:
        """Fold a finished run into the profile and report what it earned.

        *ledger* is the run tally ``flow.py`` builds: ``outcome`` (one of
        ``"extracted"``, ``"died"`` or ``"abandoned"``), ``cores_banked``,
        ``scrap_earned``, ``scrap_carried``, ``quills``, ``deepest_sector``,
        ``hull_id``, ``milestones`` (ids achieved this run) and
        ``arrival_escaped_untouched``.

        The returned summary is what the ledger screen prints: run Cores after
        the Hunt Rank income bonus, milestone bounties separately, any hull the
        run earned, the score, and whether it beat the personal best for its
        hull. The profile is written to disk before returning.
        """
        hull_id = ledger.get("hull_id") or self.selected_hull()
        if hull_id not in HULLS:
            raise ValueError(f"run ledger names unknown hull {hull_id!r}")
        extracted = ledger.get("outcome") == "extracted"

        run_cores = int(round(float(ledger.get("cores_banked", 0.0)) * self.core_income_multiplier()))
        if run_cores:
            self.add_cores(run_cores, "run")

        milestone_cores = 0
        claimed: list[str] = []
        for milestone_id in ledger.get("milestones", ()):
            paid = self.claim_milestone(milestone_id)
            if paid:
                milestone_cores += paid
                claimed.append(milestone_id)

        quills = int(ledger.get("quills", 0))
        self.profile["quills"] = int(self.profile["quills"]) + quills
        if quills:
            self.profile["runs_since_last_quill"] = 0
        else:
            self.profile["runs_since_last_quill"] = int(self.profile["runs_since_last_quill"]) + 1

        if extracted:
            self.profile["runs_extracted"] = int(self.profile["runs_extracted"]) + 1

        unlocked = [
            candidate
            for candidate in HULLS
            if candidate not in self.unlocked_hulls() and hull_feat_met(candidate, ledger, self.profile)
        ]
        for candidate in unlocked:
            self.unlock_hull(candidate)

        score = self.run_score(ledger)
        best = int(self.profile["best_scores"].get(hull_id, 0))
        personal_best = score > best
        if personal_best:
            self.profile["best_scores"][hull_id] = score

        self.persist()
        return {
            "hull_id": hull_id,
            "run_cores": run_cores,
            "milestone_cores": milestone_cores,
            "cores_awarded": run_cores + milestone_cores,
            "cores_total": self.cores(),
            "milestones": claimed,
            "hulls_unlocked": unlocked,
            "score": score,
            "personal_best": personal_best,
        }