# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-a-context-window-manager-refuse-to-rehydrate-an-evicted-segment.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-a-context-window-manager-refuse-to-rehydrate-an-evicted-segment.warrant.json
# Markdown SHA-256:   8410a8e8c28dbb4b6d7eeb574c6c67e90bd364df35520f5a80cbdd139bb60c94
# Code AST SHA-256:   8daa0b4325733ca66cdf0184df633b0ceb7f70bf275d605a164024e52fc167dc
# Verified Classes:   RehydrationBlocked, Segment
# Defensive Guards:   3 fail-closed invariants (zero external deps)

class RehydrationBlocked(RuntimeError):
    """Raised when rehydration would displace a pinned segment or lacks swap margin."""
    pass


class Segment:
    def __init__(self, seg_id, salience, pinned=False):
        self.seg_id = seg_id
        self.salience = salience
        self.pinned = pinned


def rehydrate(incoming: Segment, resident: list[Segment], capacity: int,
              trigger: float, margin: float = 0.1) -> list[Segment]:
    occupancy = sum(s.salience for s in resident)
    if occupancy + incoming.salience < trigger and len(resident) < capacity:
        return resident + [incoming]  # slack: score threshold already cleared upstream

    # At capacity: must swap. Find the cheapest displacement set.
    evictable = sorted(
        (s for s in resident if not s.pinned), key=lambda s: s.salience
    )
    if not evictable:
        raise RehydrationBlocked(
            f"cannot admit {incoming.seg_id}: all resident segments pinned"
        )
    cheapest = evictable[0]
    if incoming.salience <= cheapest.salience + margin:
        raise RehydrationBlocked(
            f"incoming {incoming.seg_id} salience {incoming.salience:.2f} "
            f"does not beat displacement cost {cheapest.salience:.2f} + {margin}"
        )
    pinned_displaced = [s for s in resident if s.pinned and s.salience < incoming.salience]
    if pinned_displaced:
        raise RehydrationBlocked(
            f"rehydration of {incoming.seg_id} would force out pinned "
            f"{[s.seg_id for s in pinned_displaced]}"
        )
    return [s for s in resident if s is not cheapest] + [incoming]