# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-lose-critical-state-when-hierarchical-summarization-compacts-a-context-window-across-multiple-checkpoint-generations.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-lose-critical-state-when-hierarchical-summarization-compacts-a-context-window-across-multiple-checkpoint-generations.warrant.json
# Markdown SHA-256:   8a9eb804b5fc81374e1c024a29e8abd692842d8dfc2e2d58fe4cbb0f4d5f9554
# Code AST SHA-256:   30b946480d686259fadc7cc5c19608374c3a3c72532fefabf12a56027220e482
# Verified Classes:   InvariantLossError, Invariant, Checkpoint
# Defensive Guards:   3 fail-closed invariants (zero external deps)

"""Guard against invariant loss during hierarchical checkpoint compaction."""

from dataclasses import dataclass, field
from typing import Iterable


class InvariantLossError(RuntimeError):
    """Raised when a compaction pass would drop a prescriptive invariant."""
    pass


@dataclass(frozen=True)
class Invariant:
    key: str
    literal: str  # must be preserved verbatim, never paraphrased


@dataclass
class Checkpoint:
    generation: int
    descriptive: str
    invariants: list[Invariant] = field(default_factory=list)


def compact(
    prior: Checkpoint,
    new_descriptive: str,
    required: Iterable[Invariant],
    max_generation: int = 3,
) -> Checkpoint:
    """Fold a checkpoint into the next generation, preserving invariants verbatim.

    Refuses to proceed if any required invariant is absent from the pinned
    ledger carried forward from the prior generation.
    """
    if prior.generation + 1 > max_generation:
        raise InvariantLossError(
            f"compaction depth {prior.generation + 1} exceeds safe maximum "
            f"{max_generation}; invariants must be re-verified against ground truth"
        )

    carried = {inv.key: inv for inv in prior.invariants}
    for req in required:
        if req.key not in carried:
            raise InvariantLossError(
                f"invariant {req.key!r} ({req.literal!r}) missing from generation "
                f"{prior.generation} ledger; refusing lossy fold"
            )
        if carried[req.key].literal != req.literal:
            raise InvariantLossError(
                f"invariant {req.key!r} mutated across generations: "
                f"{carried[req.key].literal!r} -> {req.literal!r}"
            )

    # Descriptive content may be summarized freely; invariants are pinned verbatim.
    return Checkpoint(
        generation=prior.generation + 1,
        descriptive=new_descriptive,
        invariants=sorted(carried.values(), key=lambda i: i.key),
    )
