# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-a-self-editing-context-failure-salience-score-inversion-at-the-pruning-horizon.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-a-self-editing-context-failure-salience-score-inversion-at-the-pruning-horizon.warrant.json
# Markdown SHA-256:   ab9275ec353f10bf5effe329a9e1f0032286471256c2c06ef1e9d8cc16e50563
# Code AST SHA-256:   f4e3f71358081756d9323e92dd080740d459ea65fb866962356c9db766f88696
# Verified Classes:   SalienceInversionError, Segment, RemovalLedger
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Callable


class SalienceInversionError(RuntimeError):
    """Raised when a cluster is nominated for removal a second time after
    being re-derived, indicating the pruning is scoring against its own output."""


@dataclass
class Segment:
    key: str
    text: str
    cluster: str


@dataclass
class RemovalLedger:
    removed: dict[str, int] = field(default_factory=dict)

    def record(self, cluster: str) -> int:
        self.removed[cluster] = self.removed.get(cluster, 0) + 1
        return self.removed[cluster]


def prune(
    segments: list[Segment],
    score_fn: Callable[[list[Segment]], dict[str, float]],
    budget: int,
    ledger: RemovalLedger,
    frozen_snapshot: list[Segment] | None = None,
) -> list[Segment]:
    # Score against the frozen pre-edit snapshot, never the live buffer.
    scoring_view = frozen_snapshot if frozen_snapshot is not None else list(segments)
    scores = score_fn(scoring_view)

    ranked = sorted(segments, key=lambda s: scores.get(s.key, 0.0))
    to_remove = ranked[: max(0, len(segments) - budget)]

    for seg in to_remove:
        count = ledger.record(seg.cluster)
        if count >= 2:
            raise SalienceInversionError(
                f"cluster {seg.cluster!r} nominated for removal {count} times; "
                f"re-derived content is being re-pruned — freeze scoring context "
                f"and require explicit justification for second removal"
            )

    removed_keys = {s.key for s in to_remove}
    return [s for s in segments if s.key not in removed_keys]
