# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-scratchpad-rewrites-from-silently-invalidating-the-context-window-they-rewrite.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-scratchpad-rewrites-from-silently-invalidating-the-context-window-they-rewrite.warrant.json
# Markdown SHA-256:   d8ef4c8f4f4f4e90b1613404162a1828e60ba8d7cdd56ec7ce2ab1faef26bd06
# Code AST SHA-256:   b282bc26239bde1148a73b5dade8522be9e4866034c9085c3749c16196353b71
# Verified Classes:   StaleScratchpadView, FieldCoverageViolation, Section, Scratchpad
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


class StaleScratchpadView(RuntimeError):
    """Raised when a scratchpad rewrite is committed against a stale snapshot."""


class FieldCoverageViolation(RuntimeError):
    """Raised when a rewrite omits a field that changed since its snapshot."""


@dataclass
class Section:
    version: int = 0
    fields: dict[str, Any] = field(default_factory=dict)


class Scratchpad:
    def __init__(self) -> None:
        self._sections: dict[str, Section] = {}

    def read(self, key: str) -> tuple[int, dict[str, Any]]:
        sec = self._sections.setdefault(key, Section())
        return sec.version, dict(sec.fields)

    def mutate(self, key: str, **updates: Any) -> int:
        sec = self._sections.setdefault(key, Section())
        sec.fields.update(updates)
        sec.version += 1
        return sec.version

    def commit_rewrite(
        self,
        key: str,
        snapshot_version: int,
        replacement: dict[str, Any],
        addressed_fields: set[str],
    ) -> int:
        sec = self._sections.setdefault(key, Section())
        if sec.version != snapshot_version:
            raise StaleScratchpadView(
                f"section {key!r} at version {sec.version}, "
                f"rewrite computed against {snapshot_version}"
            )
        for name in sec.fields:
            if name not in addressed_fields and sec.fields[name] != replacement.get(name):
                raise FieldCoverageViolation(
                    f"rewrite of {key!r} does not address changed field {name!r}"
                )
        sec.fields = dict(replacement)
        sec.version += 1
        return sec.version


def apply_increment_and_log(
    pad: Scratchpad,
    key: str,
    log_line: str,
    intra_turn_mutation: dict[str, Any] | None = None,
) -> int:
    version, view = pad.read(key)
    view["counter"] = view.get("counter", 0) + 1
    view.setdefault("log", []).append(log_line)

    # A tool call in the same turn mutates the section out of band.
    if intra_turn_mutation:
        pad.mutate(key, **intra_turn_mutation)

    try:
        return pad.commit_rewrite(
            key,
            snapshot_version=version,
            replacement=view,
            addressed_fields={"counter", "log"},
        )
    except StaleScratchpadView:
        raise StaleScratchpadView(
            f"refusing to commit rewrite of {key!r}: view is stale; re-read and rebase"
        )
