# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-a-context-rewrite-deadlock-in-self-editing-context-windows.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-a-context-rewrite-deadlock-in-self-editing-context-windows.warrant.json
# Markdown SHA-256:   5ddabb71eb1a2cb7ea2e7f258afef26f7a69c4ab98b38fefa424bcc9574d019c
# Code AST SHA-256:   0199d2022e57f9da727e07a5dbac5036f9df3afcf418f2cb632a79d4b6a83464
# Verified Classes:   ContextRewriteDeadlockError, Span
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Callable


class ContextRewriteDeadlockError(RuntimeError):
    """Raised when a self-editing context rewrite fails the idempotence
    or justification-reachability invariant and cannot be safely applied."""
    pass


@dataclass
class Span:
    span_id: str
    content: str
    justifies: list[str] = field(default_factory=list)  # span_ids this span justifies


def check_justification_reachability(retained: dict[str, Span]) -> list[str]:
    """Return retained span_ids whose justification span is absent."""
    orphans = []
    for sid, span in retained.items():
        for justified_id in span.justifies:
            if justified_id in retained and justified_id not in retained:
                orphans.append(justified_id)
    return orphans


def apply_self_edit(
    window: dict[str, Span],
    policy: Callable[[dict[str, Span]], dict[str, Span]],
    snapshot: dict[str, Span] | None = None,
) -> dict[str, Span]:
    """Apply a model-driven rewrite with idempotence and reachability gates.

    Raises ContextRewriteDeadlockError if the rewrite is non-idempotent
    (the policy changes its own output) or if a retained span loses its
    justification span. On raise, the caller must restore `snapshot`.
    """
    if snapshot is None:
        snapshot = dict(window)

    candidate = policy(window)
    second_pass = policy(candidate)

    if set(second_pass.keys()) != set(candidate.keys()):
        raise ContextRewriteDeadlockError(
            f"non-idempotent rewrite: policy changed its own output "
            f"(pass1={sorted(candidate)}, pass2={sorted(second_pass)}); "
            f"restore snapshot and freeze policy"
        )

    orphans = check_justification_reachability(candidate)
    if orphans:
        raise ContextRewriteDeadlockError(
            f"justification-reachability violated: retained spans {orphans} "
            f"have no reachable justification span; restore snapshot"
        )

    return candidate