hermes-agent/tests/agent/test_credits_policy.py

"""Tests for evaluate_credits_notices — pure threshold reconciliation policy (L4.1).

All tests use fresh latch = {"active": set(), "seen_below_90": False, "usage_band": None} per scenario.
CreditsState is constructed directly (not parsed from headers).
"""

from __future__ import annotations

import pytest

from agent.credits_tracker import (
    CREDITS_NOTICE_KIND,
    CREDITS_RESTORED_TTL_MS,
    AgentNotice,
    CreditsState,
    evaluate_credits_notices,
)


# ── Helpers ──────────────────────────────────────────────────────────────────


def fresh_latch() -> dict:
    return {"active": set(), "seen_below_90": False, "usage_band": None}


def state_with_fraction(
    uf: float | None,
    *,
    paid_access: bool = True,
    denominator_kind: str = "subscription_cap",
    purchased_micros: int = 0,
    purchased_usd: str = "0.00",
    subscription_limit_usd: str | None = "20.00",
) -> CreditsState:
    """Build a minimal CreditsState that yields the desired used_fraction.

    used_fraction = (limit - subscription_micros) / limit

    When uf is None, we set limit to None so used_fraction returns None.
    """
    if uf is None:
        return CreditsState(
            subscription_limit_micros=None,
            subscription_limit_usd=None,
            subscription_micros=0,
            denominator_kind="none",
            paid_access=paid_access,
            purchased_micros=purchased_micros,
            purchased_usd=purchased_usd,
        )
    # We want (limit - sub) / limit == uf  →  sub = limit * (1 - uf)
    limit = 20_000_000  # $20 in micros
    sub = int(limit * (1.0 - uf))
    return CreditsState(
        subscription_limit_micros=limit,
        subscription_limit_usd=subscription_limit_usd,
        subscription_micros=sub,
        denominator_kind=denominator_kind,
        paid_access=paid_access,
        purchased_micros=purchased_micros,
        purchased_usd=purchased_usd,
    )


# ── Scenario 1: crossing 90% threshold ───────────────────────────────────────


class TestWarn90Crossing:
    def test_below_lowest_band_no_notice_but_latch_set(self):
        latch = fresh_latch()
        s = state_with_fraction(0.10)  # below the 50% band
        to_show, to_clear = evaluate_credits_notices(s, latch)
        assert all(n.key != "credits.usage" for n in to_show)
        assert "credits.usage" not in to_clear
        assert latch["seen_below_90"] is True

    def test_crossing_to_90_fires_once(self):
        latch = fresh_latch()
        # First call: uf < 0.5 — sets seen_below_90 (below lowest band)
        s1 = state_with_fraction(0.10)
        evaluate_credits_notices(s1, latch)
        # Second call: uf >= 0.9 — should fire the usage band at 90
        s2 = state_with_fraction(0.95)
        to_show, to_clear = evaluate_credits_notices(s2, latch)
        keys = [n.key for n in to_show]
        assert "credits.usage" in keys
        assert "credits.usage" not in to_clear

    def test_no_refire_on_repeated_over_90(self):
        latch = fresh_latch()
        s_below = state_with_fraction(0.10)
        evaluate_credits_notices(s_below, latch)
        s_over = state_with_fraction(0.95)
        evaluate_credits_notices(s_over, latch)
        # Third call: still ≥ 0.9 — must NOT re-fire
        to_show, to_clear = evaluate_credits_notices(s_over, latch)
        assert all(n.key != "credits.usage" for n in to_show)
        assert "credits.usage" not in to_clear


# ── Scenario 2: recovery + re-cross ──────────────────────────────────────────


class TestWarn90RecoveryReCross:
    def test_recovery_clears_warn90(self):
        latch = fresh_latch()
        # Cross below → above
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(state_with_fraction(0.95), latch)
        # Recovery: uf drops back below ALL bands → usage notice clears entirely
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.10), latch)
        assert "credits.usage" in to_clear
        assert "credits.usage" not in latch["active"]

    def test_recross_after_recovery_fires_again(self):
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(state_with_fraction(0.95), latch)
        evaluate_credits_notices(state_with_fraction(0.10), latch)  # recovery
        # Re-cross: uf >= 0.9 again — should fire again because the band is clearable
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.95), latch)
        keys = [n.key for n in to_show]
        assert "credits.usage" in keys


# ── Scenario 3: open-already-over (hybrid Q3 gate) ───────────────────────────


class TestOpenAlreadyOver:
    def test_warn90_does_not_fire_without_seen_below_90(self):
        """First call uf≥0.9 with seen_below_90=False — warn90 must NOT fire."""
        latch = fresh_latch()
        assert latch["seen_below_90"] is False
        s = state_with_fraction(0.95)
        to_show, to_clear = evaluate_credits_notices(s, latch)
        assert all(n.key != "credits.usage" for n in to_show)
        assert "credits.usage" not in to_clear


# ── Scenario 3b: boundary — exact 0.9 and just-below-1.0 ────────────────────


class TestBoundaryFractions:
    def test_exact_0_9_fires_warn90(self):
        """used_fraction == 0.9 exactly must fire warn90 (threshold is inclusive)."""
        latch = fresh_latch()
        # First: prime seen_below_90 with a sub-50% observation
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        # Now construct a state where used_fraction is EXACTLY 0.9:
        # subscription_limit_micros=20_000_000, subscription_micros=2_000_000
        # → used = 18_000_000 / 20_000_000 = 0.9 exactly
        s = CreditsState(
            subscription_limit_micros=20_000_000,
            subscription_limit_usd="20.00",
            subscription_micros=2_000_000,
            denominator_kind="subscription_cap",
            paid_access=True,
        )
        assert s.used_fraction == 0.9
        to_show, to_clear = evaluate_credits_notices(s, latch)
        keys = [n.key for n in to_show]
        assert "credits.usage" in keys
        assert "credits.usage" not in to_clear

    def test_just_below_1_0_does_not_fire_grant_spent(self):
        """subscription_micros = limit - 1 (used_fraction just under 1.0) must NOT fire grant_spent.

        Locks the boundary so a future used_fraction clamp refactor cannot fire
        grant_spent a micro early.
        """
        latch = fresh_latch()
        limit = 20_000_000
        s = CreditsState(
            subscription_limit_micros=limit,
            subscription_limit_usd="20.00",
            subscription_micros=1,           # limit - 1 → used_fraction < 1.0
            denominator_kind="subscription_cap",
            purchased_micros=5_000_000,
            purchased_usd="5.00",
            paid_access=True,
        )
        assert s.used_fraction is not None and s.used_fraction < 1.0
        to_show, to_clear = evaluate_credits_notices(s, latch)
        assert all(n.key != "credits.grant_spent" for n in to_show)
        assert "credits.grant_spent" not in to_clear


# ── Scenario 4: grant_spent ───────────────────────────────────────────────────


class TestGrantSpent:
    def _grant_state(self, purchased_micros: int = 12_340_000) -> CreditsState:
        return state_with_fraction(
            1.0,
            denominator_kind="subscription_cap",
            purchased_micros=purchased_micros,
            purchased_usd="12.34",
        )

    def test_grant_spent_fires_on_first_obs(self):
        """No crossing gate for grant_spent — fires immediately on first obs."""
        latch = fresh_latch()
        to_show, to_clear = evaluate_credits_notices(self._grant_state(), latch)
        keys = [n.key for n in to_show]
        assert "credits.grant_spent" in keys

    def test_grant_spent_no_refire(self):
        latch = fresh_latch()
        evaluate_credits_notices(self._grant_state(), latch)
        to_show, to_clear = evaluate_credits_notices(self._grant_state(), latch)
        assert all(n.key != "credits.grant_spent" for n in to_show)
        assert "credits.grant_spent" not in to_clear

    def test_grant_spent_clears_when_purchased_zero(self):
        latch = fresh_latch()
        evaluate_credits_notices(self._grant_state(), latch)
        # Now purchased → 0: grant_cond becomes False
        s_no_purchase = state_with_fraction(
            1.0,
            denominator_kind="subscription_cap",
            purchased_micros=0,
            purchased_usd="0.00",
        )
        to_show, to_clear = evaluate_credits_notices(s_no_purchase, latch)
        assert "credits.grant_spent" in to_clear
        assert all(n.key != "credits.grant_spent" for n in to_show)


# ── Scenario 5: depleted + recovery ──────────────────────────────────────────


class TestDepleted:
    def test_depleted_fires_level_error_kind_sticky(self):
        latch = fresh_latch()
        s = CreditsState(paid_access=False)
        to_show, to_clear = evaluate_credits_notices(s, latch)
        depleted_notices = [n for n in to_show if n.key == "credits.depleted"]
        assert len(depleted_notices) == 1
        n = depleted_notices[0]
        assert n.level == "error"
        assert n.kind == CREDITS_NOTICE_KIND

    def test_recovery_emits_clear_and_restored(self):
        latch = fresh_latch()
        # Fire depleted
        evaluate_credits_notices(CreditsState(paid_access=False), latch)
        # Now recovered
        to_show, to_clear = evaluate_credits_notices(CreditsState(paid_access=True), latch)
        assert "credits.depleted" in to_clear
        restored = [n for n in to_show if n.key == "credits.restored"]
        assert len(restored) == 1
        r = restored[0]
        assert r.level == "success"
        assert r.kind == "ttl"
        assert r.ttl_ms == CREDITS_RESTORED_TTL_MS

    def test_depleted_refires_after_recovery(self):
        latch = fresh_latch()
        evaluate_credits_notices(CreditsState(paid_access=False), latch)
        evaluate_credits_notices(CreditsState(paid_access=True), latch)
        # Goes depleted again
        to_show, to_clear = evaluate_credits_notices(CreditsState(paid_access=False), latch)
        keys = [n.key for n in to_show]
        assert "credits.depleted" in keys


# ── Scenario 5b: free-model suppression of the depleted notice ───────────────


class TestDepletedFreeModelSuppression:
    def test_depleted_suppressed_when_model_is_free(self):
        latch = fresh_latch()
        s = CreditsState(paid_access=False)
        to_show, to_clear = evaluate_credits_notices(s, latch, model_is_free=True)
        assert all(n.key != "credits.depleted" for n in to_show)
        assert "credits.depleted" not in latch["active"]
        assert to_clear == []

    def test_switch_to_free_model_clears_without_restored(self):
        latch = fresh_latch()
        # Depleted on a paid model → notice fires
        evaluate_credits_notices(CreditsState(paid_access=False), latch)
        assert "credits.depleted" in latch["active"]
        # Same depleted account, but now on a free model → clear, NO "restored"
        to_show, to_clear = evaluate_credits_notices(
            CreditsState(paid_access=False), latch, model_is_free=True
        )
        assert "credits.depleted" in to_clear
        assert "credits.depleted" not in latch["active"]
        assert all(n.key != "credits.restored" for n in to_show)

    def test_switch_back_to_paid_model_while_depleted_reshows(self):
        latch = fresh_latch()
        evaluate_credits_notices(CreditsState(paid_access=False), latch)
        evaluate_credits_notices(CreditsState(paid_access=False), latch, model_is_free=True)
        # Back on a paid model, still depleted → notice re-fires
        to_show, to_clear = evaluate_credits_notices(CreditsState(paid_access=False), latch)
        keys = [n.key for n in to_show]
        assert "credits.depleted" in keys
        assert "credits.depleted" in latch["active"]

    def test_genuine_recovery_on_free_model_no_spurious_restored(self):
        """Recovery observed while suppressed (notice never shown) → nothing to
        clear, no 'restored' (there was no visible depleted state to restore)."""
        latch = fresh_latch()
        evaluate_credits_notices(CreditsState(paid_access=False), latch, model_is_free=True)
        to_show, to_clear = evaluate_credits_notices(
            CreditsState(paid_access=True), latch, model_is_free=True
        )
        assert to_clear == []
        assert all(n.key != "credits.restored" for n in to_show)

    def test_genuine_recovery_still_emits_restored_when_notice_active(self):
        """paid_access flip back to True with the notice showing → clear + restored
        (unchanged behaviour, regardless of the model-free flag)."""
        latch = fresh_latch()
        evaluate_credits_notices(CreditsState(paid_access=False), latch)
        to_show, to_clear = evaluate_credits_notices(
            CreditsState(paid_access=True), latch, model_is_free=True
        )
        assert "credits.depleted" in to_clear
        restored = [n for n in to_show if n.key == "credits.restored"]
        assert len(restored) == 1

    def test_free_flag_does_not_affect_other_notices(self):
        """Usage-band and grant notices are independent of the model-free gate."""
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch, model_is_free=True)
        to_show, _ = evaluate_credits_notices(
            state_with_fraction(0.95, paid_access=False), latch, model_is_free=True
        )
        keys = [n.key for n in to_show]
        assert "credits.usage" in keys
        assert "credits.depleted" not in keys


# ── Scenario 5c: is_free_tier_model (local-data-only check) ──────────────────


class TestIsFreeTierModel:
    def test_free_suffix_is_free(self):
        from agent.credits_tracker import is_free_tier_model

        assert is_free_tier_model("nvidia/nemotron-3-ultra:free") is True
        assert is_free_tier_model("Hermes-4-70B:free", "https://inference-api.nousresearch.com") is True

    def test_empty_or_paid_model_is_not_free(self):
        from agent.credits_tracker import is_free_tier_model

        assert is_free_tier_model("") is False
        assert is_free_tier_model("Hermes-4-405B") is False

    def test_pricing_cache_peek_zero_priced_model(self, monkeypatch):
        from agent.credits_tracker import is_free_tier_model
        import hermes_cli.models as models_mod

        # The picker keys the cache on the pre-/v1 root (get_pricing_for_provider
        # strips a trailing /v1 before fetch_models_with_pricing).
        monkeypatch.setattr(
            models_mod,
            "_pricing_cache",
            {
                "https://inference-api.nousresearch.com": {
                    "some/zero-priced": {"prompt": "0", "completion": "0"},
                    "some/paid": {"prompt": "0.000001", "completion": "0.000002"},
                }
            },
        )
        # The agent holds the /v1-suffixed URL (DEFAULT_NOUS_INFERENCE_URL) —
        # the helper must normalize it down to the picker's cache key.
        base = "https://inference-api.nousresearch.com/v1"
        assert is_free_tier_model("some/zero-priced", base) is True
        assert is_free_tier_model("some/paid", base) is False
        # Pre-stripped and trailing-slash variants resolve to the same key.
        assert is_free_tier_model("some/zero-priced", "https://inference-api.nousresearch.com/") is True
        assert is_free_tier_model("some/zero-priced", "https://inference-api.nousresearch.com/v1/") is True

    def test_cache_miss_is_not_free_and_no_fetch(self, monkeypatch):
        from agent.credits_tracker import is_free_tier_model
        import hermes_cli.models as models_mod

        monkeypatch.setattr(models_mod, "_pricing_cache", {})

        def _boom(*args, **kwargs):  # any network attempt fails the test
            raise AssertionError("is_free_tier_model must never hit the network")

        import urllib.request

        monkeypatch.setattr(urllib.request, "urlopen", _boom)
        assert is_free_tier_model("some/model", "https://inference-api.nousresearch.com/v1") is False

    def test_exception_fails_open_to_false(self, monkeypatch):
        from agent.credits_tracker import is_free_tier_model
        import hermes_cli.models as models_mod

        class _Exploding:
            def get(self, *_a, **_kw):
                raise RuntimeError("boom")

        monkeypatch.setattr(models_mod, "_pricing_cache", _Exploding())
        assert is_free_tier_model("some/model", "https://inference-api.nousresearch.com") is False


# ── Scenario 6: denominator none (uf is None) ────────────────────────────────


class TestDenominatorNone:
    def test_no_warn90_when_uf_none(self):
        latch = fresh_latch()
        s = state_with_fraction(None)
        to_show, to_clear = evaluate_credits_notices(s, latch)
        assert all(n.key != "credits.usage" for n in to_show)
        assert "credits.usage" not in to_clear

    def test_no_grant_spent_when_uf_none(self):
        latch = fresh_latch()
        s = CreditsState(
            subscription_limit_micros=None,
            denominator_kind="none",
            purchased_micros=5_000_000,
            purchased_usd="5.00",
        )
        to_show, to_clear = evaluate_credits_notices(s, latch)
        assert all(n.key != "credits.grant_spent" for n in to_show)

    def test_warn90_clears_when_uf_becomes_none(self):
        """If warn90 was active and uf becomes None, it should clear."""
        latch = fresh_latch()
        # Establish usage notice active: cross below → above
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(state_with_fraction(0.95), latch)
        assert "credits.usage" in latch["active"]
        # Now uf becomes None (denominator changed to "none")
        s_none = state_with_fraction(None)
        to_show, to_clear = evaluate_credits_notices(s_none, latch)
        assert "credits.usage" in to_clear
        assert "credits.usage" not in latch["active"]


# ── Scenario 7: copy / verbatim USD strings ──────────────────────────────────


class TestNoticeCopy:
    def test_warn90_contains_verbatim_subscription_limit_usd(self):
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        s = state_with_fraction(0.95, subscription_limit_usd="20.00")
        to_show, _ = evaluate_credits_notices(s, latch)
        warn_notice = next(n for n in to_show if n.key == "credits.usage")
        assert "$20.00" in warn_notice.text
        assert "cap" in warn_notice.text

    def test_grant_spent_contains_verbatim_purchased_usd(self):
        latch = fresh_latch()
        s = state_with_fraction(
            1.0,
            denominator_kind="subscription_cap",
            purchased_micros=12_340_000,
            purchased_usd="12.34",
        )
        to_show, _ = evaluate_credits_notices(s, latch)
        grant_notice = next(n for n in to_show if n.key == "credits.grant_spent")
        assert "$12.34" in grant_notice.text
        assert "top-up left" in grant_notice.text

    def test_depleted_mentions_credits_command(self):
        latch = fresh_latch()
        s = CreditsState(paid_access=False)
        to_show, _ = evaluate_credits_notices(s, latch)
        depleted_notice = next(n for n in to_show if n.key == "credits.depleted")
        assert "/topup" in depleted_notice.text


# ── Scenario 8: severity order in a single call ──────────────────────────────


class TestSeverityOrder:
    def test_multiple_new_notices_ordered_ascending_severity(self):
        """grant_spent < depleted in to_show when both fire in one call.

        (usage is suppressed here: purchased>0 — see TestTopUpSuppression.
        usage + grant_spent are now mutually exclusive by design.)
        """
        latch = {"active": set(), "seen_below_90": True, "usage_band": None}

        # Build state: subscription_cap, uf >= 1.0, purchased_micros > 0, NOT paid_access
        # grant_cond: subscription_cap + uf >= 1.0 + purchased > 0 ✓
        # depleted_cond: not paid_access ✓
        # usage band: suppressed (purchased > 0)
        s = CreditsState(
            subscription_limit_micros=20_000_000,
            subscription_limit_usd="20.00",
            subscription_micros=0,  # uf = 1.0
            denominator_kind="subscription_cap",
            purchased_micros=5_000_000,
            purchased_usd="5.00",
            paid_access=False,
        )
        to_show, _ = evaluate_credits_notices(s, latch)
        keys = [n.key for n in to_show]
        assert "credits.usage" not in keys
        assert "credits.grant_spent" in keys
        assert "credits.depleted" in keys
        # Ascending severity: grant_spent before depleted
        assert keys.index("credits.grant_spent") < keys.index("credits.depleted")

    def test_usage_before_depleted_without_topup(self):
        """With no top-up funds, usage fires and precedes depleted."""
        latch = {"active": set(), "seen_below_90": True, "usage_band": None}
        s = CreditsState(
            subscription_limit_micros=20_000_000,
            subscription_limit_usd="20.00",
            subscription_micros=0,  # uf = 1.0
            denominator_kind="subscription_cap",
            purchased_micros=0,
            purchased_usd="0.00",
            paid_access=False,
        )
        to_show, _ = evaluate_credits_notices(s, latch)
        keys = [n.key for n in to_show]
        assert "credits.usage" in keys
        assert "credits.depleted" in keys
        assert keys.index("credits.usage") < keys.index("credits.depleted")


# ── Scenario 8b: top-up suppression of the usage gauge ───────────────────────


class TestTopUpSuppression:
    """purchased_micros > 0 suppresses the sub-cap usage gauge: the cap is the
    wrong denominator for an account that can keep spending top-up funds."""

    def test_no_usage_band_with_topup_at_90pct(self):
        latch = fresh_latch()
        evaluate_credits_notices(
            state_with_fraction(0.10, purchased_micros=5_000_000, purchased_usd="5.00"),
            latch,
        )
        to_show, to_clear = evaluate_credits_notices(
            state_with_fraction(0.95, purchased_micros=5_000_000, purchased_usd="5.00"),
            latch,
        )
        assert all(n.key != "credits.usage" for n in to_show)
        assert latch["usage_band"] is None

    def test_topup_landing_mid_session_clears_active_band(self):
        """A showing 90% warn must clear when a top-up lands (purchased 0 → >0)."""
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(state_with_fraction(0.95), latch)
        assert latch["usage_band"] == 90
        to_show, to_clear = evaluate_credits_notices(
            state_with_fraction(0.95, purchased_micros=10_000_000, purchased_usd="10.00"),
            latch,
        )
        assert "credits.usage" in to_clear
        assert latch["usage_band"] is None
        assert all(n.key != "credits.usage" for n in to_show)

    def test_band_resumes_after_topup_spent(self):
        """purchased back to 0 with usage still in-band → gauge resumes."""
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(
            state_with_fraction(0.95, purchased_micros=10_000_000, purchased_usd="10.00"),
            latch,
        )
        assert latch["usage_band"] is None
        to_show, _ = evaluate_credits_notices(state_with_fraction(0.95), latch)
        n = next(n for n in to_show if n.key == "credits.usage")
        assert "90%" in n.text
        assert latch["usage_band"] == 90

    def test_grant_spent_still_fires_with_topup(self):
        """Suppression only affects the gauge — grant_spent (which NEEDS purchased>0)
        is untouched."""
        latch = fresh_latch()
        s = state_with_fraction(
            1.0,
            denominator_kind="subscription_cap",
            purchased_micros=12_340_000,
            purchased_usd="12.34",
        )
        to_show, _ = evaluate_credits_notices(s, latch)
        keys = [n.key for n in to_show]
        assert "credits.grant_spent" in keys
        assert "credits.usage" not in keys

    def test_depleted_unaffected_by_topup_suppression(self):
        latch = fresh_latch()
        s = CreditsState(paid_access=False, purchased_micros=5_000_000, purchased_usd="5.00")
        to_show, _ = evaluate_credits_notices(s, latch)
        assert any(n.key == "credits.depleted" for n in to_show)


# ── Invariant: never fire + clear same key in one call ────────────────────────


class TestNoFireAndClearSameKey:
    def test_usage_never_both_fired_and_cleared(self):
        latch = fresh_latch()
        # Run many state transitions; across each, assert no key is in both lists
        states = [
            state_with_fraction(0.10),
            state_with_fraction(0.95),
            state_with_fraction(0.10),
            state_with_fraction(0.95),
            state_with_fraction(None),
        ]
        for s in states:
            to_show, to_clear = evaluate_credits_notices(s, latch)
            fired_keys = {n.key for n in to_show}
            cleared_keys = set(to_clear)
            overlap = fired_keys & cleared_keys
            assert not overlap, f"Key(s) both fired and cleared: {overlap}"

    def test_depleted_never_both_fired_and_cleared(self):
        latch = fresh_latch()
        states = [
            CreditsState(paid_access=False),
            CreditsState(paid_access=True),
            CreditsState(paid_access=False),
        ]
        for s in states:
            to_show, to_clear = evaluate_credits_notices(s, latch)
            fired_keys = {n.key for n in to_show}
            cleared_keys = set(to_clear)
            overlap = fired_keys & cleared_keys
            assert not overlap, f"Key(s) both fired and cleared: {overlap}"


# ── Scenario 9: escalating usage bands (50 → 75 → 90) ────────────────────────


class TestUsageBands:
    """The usage notice shows the HIGHEST crossed band as a single escalating line."""

    def _band_text(self, to_show):
        n = next((n for n in to_show if n.key == "credits.usage"), None)
        return n.text if n else None

    def test_50_band_fires_info(self):
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)  # prime
        to_show, _ = evaluate_credits_notices(state_with_fraction(0.55), latch)
        n = next(n for n in to_show if n.key == "credits.usage")
        assert "50%" in n.text and n.level == "info"
        assert latch["usage_band"] == 50

    def test_75_band_fires_warn(self):
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        to_show, _ = evaluate_credits_notices(state_with_fraction(0.80), latch)
        n = next(n for n in to_show if n.key == "credits.usage")
        assert "75%" in n.text and n.level == "warn"
        assert latch["usage_band"] == 75

    def test_climb_replaces_band(self):
        """Climbing 50→75→90 replaces the single line (clear old + show new)."""
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        # 55% → 50 band
        evaluate_credits_notices(state_with_fraction(0.55), latch)
        assert latch["usage_band"] == 50
        # 80% → climbs to 75, clearing the 50 line
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.80), latch)
        assert "credits.usage" in to_clear
        assert "75%" in self._band_text(to_show)
        assert latch["usage_band"] == 75
        # 95% → climbs to 90
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.95), latch)
        assert "credits.usage" in to_clear
        assert "90%" in self._band_text(to_show)
        assert latch["usage_band"] == 90

    def test_step_down_on_recovery(self):
        """Recovering steps the band back down, then clears below the lowest band."""
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(state_with_fraction(0.95), latch)
        assert latch["usage_band"] == 90
        # drop to 80% → steps down to 75
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.80), latch)
        assert "credits.usage" in to_clear
        assert "75%" in self._band_text(to_show)
        # drop to 55% → steps down to 50
        to_show, _ = evaluate_credits_notices(state_with_fraction(0.55), latch)
        assert "50%" in self._band_text(to_show)
        # drop below 50% → clears entirely
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.10), latch)
        assert "credits.usage" in to_clear
        assert latch["usage_band"] is None

    def test_no_refire_same_band(self):
        latch = fresh_latch()
        evaluate_credits_notices(state_with_fraction(0.10), latch)
        evaluate_credits_notices(state_with_fraction(0.80), latch)  # fires 75
        # still 80% → same band, no re-emit, no clear
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.80), latch)
        assert all(n.key != "credits.usage" for n in to_show)
        assert "credits.usage" not in to_clear

    def test_exact_band_boundaries_inclusive(self):
        """Thresholds are inclusive: exactly 0.50 / 0.75 / 0.90 land in their band."""
        for uf, want in [(0.50, 50), (0.75, 75), (0.90, 90)]:
            latch = fresh_latch()
            latch["seen_below_90"] = True  # allow firing
            evaluate_credits_notices(state_with_fraction(uf), latch)
            assert latch["usage_band"] == want, (uf, latch["usage_band"])

    def test_open_below_lowest_band_no_notice(self):
        latch = fresh_latch()
        to_show, to_clear = evaluate_credits_notices(state_with_fraction(0.30), latch)
        assert all(n.key != "credits.usage" for n in to_show)
        assert latch["usage_band"] is None