# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-of-a-context-budget-silently-overrun-when-compaction-reclaims-tokens-that-were-already-counted-as-resident.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-of-a-context-budget-silently-overrun-when-compaction-reclaims-tokens-that-were-already-counted-as-resident.warrant.json
# Markdown SHA-256:   7761608ba03059f19bb4079dbbb3871cec5b23bc8e5848f474d6c254e6e92c62
# Code AST SHA-256:   75d077e18c0fff128ffde879224b2388e9556abba5078f43150069715a423463
# Verified Classes:   ProvenanceError, State, LedgerEntry, BudgetLedger
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from enum import Enum


class ProvenanceError(RuntimeError):
    """Raised when a provenance state transition would corrupt budget accounting."""


class State(Enum):
    RESIDENT = "resident"
    RECLAIMABLE = "reclaimable"   # source bytes still present and rehydratable
    DROPPED = "dropped"


@dataclass
class LedgerEntry:
    obj_id: str
    tokens: int
    state: State
    source_present: bool


@dataclass
class BudgetLedger:
    hard_limit: int
    entries: dict[str, LedgerEntry] = field(default_factory=dict)

    def resident_tokens(self) -> int:
        return sum(e.tokens for e in self.entries.values() if e.state is State.RESIDENT)

    def accounted_tokens(self) -> int:
        # accounted counts resident + reclaimable, because reclaimable can
        # re-enter the prompt and therefore consumes budget.
        return sum(
            e.tokens
            for e in self.entries.values()
            if e.state in (State.RESIDENT, State.RECLAIMABLE)
        )

    def compact(self, obj_ids: list[str], merged_tokens: int, keep_source: bool) -> None:
        """Transfer objects out of RESIDENT. Never silently frees budget."""
        for oid in obj_ids:
            entry = self.entries[oid]
            if entry.state is not State.RESIDENT:
                raise ProvenanceError(
                    f"cannot compact {oid}: state is {entry.state.value}, not resident"
                )
            if keep_source and not entry.source_present:
                raise ProvenanceError(
                    f"cannot mark {oid} reclaimable: source bytes are absent"
                )
            entry.state = State.RECLAIMABLE if keep_source else State.DROPPED

        self.entries[f"merged:{len(obj_ids)}"] = LedgerEntry(
            obj_id=f"merged:{len(obj_ids)}",
            tokens=merged_tokens,
            state=State.RESIDENT,
            source_present=True,
        )

    def check_next_turn(self, projected_delta: int) -> None:
        """Gate the next request on physical residency, not discounted accounting."""
        projected = self.resident_tokens() + projected_delta
        if projected > self.hard_limit:
            raise ProvenanceError(
                f"next turn would be {projected} tokens against limit "
                f"{self.hard_limit}; compaction did not create real headroom "
                f"(resident={self.resident_tokens()}, "
                f"accounted={self.accounted_tokens()})"
            )


def demonstrate_boundary() -> None:
    ledger = BudgetLedger(hard_limit=40_000)
    for i in range(12):
        ledger.entries[f"dup{i}"] = LedgerEntry(
            obj_id=f"dup{i}", tokens=180, state=State.RESIDENT, source_present=True
        )
    ledger.entries["base"] = LedgerEntry(
        obj_id="base", tokens=38_900 - 12 * 180, state=State.RESIDENT, source_present=True
    )

    # Dedup keeps sources for "possible rehydration": budget must NOT shrink.
    ledger.compact([f"dup{i}" for i in range(12)], merged_tokens=210, keep_source=True)

    # A 3,400-token tool result arrives. The correct gate rejects it.
    ledger.check_next_turn(projected_delta=3_400)
