# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-evicts-on-score-alone-the-tier-residency-invariant-in-hierarchical-context-budgeting.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-evicts-on-score-alone-the-tier-residency-invariant-in-hierarchical-context-budgeting.warrant.json
# Markdown SHA-256:   ceaf0f4a5b40970fcd1cfbd79986780a0e3153861ddba2fda50f0355c36eeec6
# Code AST SHA-256:   b210d1a38f3b10ceef46a7ab120ac3caa07dee10ebc02daade721f964e0e1ad1
# Verified Classes:   TierFloorViolation, PinnedEvictionRefused
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class TierFloorViolation(RuntimeError):
    """Raised when eviction would breach a tier's minimum residency."""
    pass


class PinnedEvictionRefused(TierFloorViolation):
    """Raised when a pinned-tier item is selected for eviction without override."""
    pass


def select_evictions(candidates, budget_deficit, floors, score_fn, override_tokens=frozenset()):
    """
    Gate-then-rank eviction.

    candidates: iterable of items with .tier and .tokens
    budget_deficit: tokens that must be freed
    floors: dict tier -> minimum resident tokens that must remain
    score_fn: item -> float, ranking only (lower = evict first)
    override_tokens: explicit opt-in ids permitted to breach pinned floor
    """
    # --- Gate: admissibility. Consult tier residency BEFORE scoring. ---
    admissible = []
    for item in candidates:
        floor = floors.get(item.tier, 0)
        resident = sum(c.tokens for c in candidates if c.tier == item.tier)
        if resident - item.tokens < floor:
            if item.tier == "pinned" and item.id not in override_tokens:
                raise PinnedEvictionRefused(
                    f"pinned item {item.id!r} cannot be evicted; "
                    f"resident={resident} floor={floor} tokens={item.tokens}"
                )
            if item.tier != "pinned" and item.id not in override_tokens:
                # Protected tier would be breached: not admissible.
                continue
        admissible.append(item)

    # --- Rank: score only the admissible remainder. ---
    victims = sorted(admissible, key=score_fn)
    freed = 0
    chosen = []
    for v in victims:
        if freed >= budget_deficit:
            break
        chosen.append(v)
        freed += v.tokens

    if freed < budget_deficit:
        raise TierFloorViolation(
            f"cannot relieve deficit={budget_deficit} within admissible set; "
            f"freed={freed}. Escalate to tier demotion, do not breach floors."
        )
    return chosen
