# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-update-a-conclusion-without-reopening-the-history-is-the-right-choice-for-ais-instances-and-llms.md
# Remnant Warrant:    https://corpusfetch.com/c/why-update-a-conclusion-without-reopening-the-history-is-the-right-choice-for-ais-instances-and-llms.warrant.json
# Markdown SHA-256:   3306a1178b504185792afeda1b7d2175d58e29c039b261383f4358163fbf010b
# Code AST SHA-256:   b1cd2e4a7f2d6eb71fc0a5f608af9168d66afb826c8da04c415280bf8986d3b8
# Verified Classes:   HistoricalAppendAntiPatternError, SupersessionReceipt, AtomicConclusionSuperseder
# Defensive Guards:   4 fail-closed invariants (zero external deps)

import hashlib
import os
import re
import tempfile
from dataclasses import dataclass
from pathlib import Path
from typing import Final


class HistoricalAppendAntiPatternError(ValueError):
    '''Raised when a residual update appends a historical retraction instead of superseding the conclusion in place.'''
    pass


@dataclass(frozen=True)
class SupersessionReceipt:
    file_path: str
    previous_sha256: str
    new_sha256: str
    token_estimate: int


class AtomicConclusionSuperseder:
    '''
    Enforces Markovian in-place conclusion updates without reopening or appending
    contradictory historical changelogs:
    1. Rejects append-only retraction markers ("EDIT:", "UPDATE:", "ignore previous rule").
    2. Enforces O(1) document size bounds so residuals never bloat across revisions.
    3. Atomically replaces the canonical residual file via fsync + POSIX replace.
    '''

    FORBIDDEN_CHANGELOG_PATTERNS: Final[tuple[re.Pattern[str], ...]] = (
        re.compile(r"^\s*(#+\s*)?(UPDATE|EDIT|CORRECTION|ERRATA|RETRACTION)\s*[:\-]", re.IGNORECASE | re.MULTILINE),
        re.compile(r"ignore\s+(the\s+)?(above|previous|earlier)\s+rule", re.IGNORECASE),
        re.compile(r"previously\s+this\s+article\s+stated", re.IGNORECASE),
    )
    MAX_RESIDUAL_CHARS: Final[int] = 24_000

    @classmethod
    def supersede_residual_in_place(
        cls,
        target_path: Path,
        *,
        new_complete_markdown: str,
    ) -> SupersessionReceipt:
        # Gate 2: Reject append-only retraction anti-patterns
        for pattern in cls.FORBIDDEN_CHANGELOG_PATTERNS:
            match = pattern.search(new_complete_markdown)
            if match:
                raise HistoricalAppendAntiPatternError(
                    f"Rejected append-only changelog marker ('{match.group(0)}'). "
                    "Rewrite the superseded rule and Method directly in place."
                )

        # Gate 3: Enforce O(1) size ceiling
        if len(new_complete_markdown) > cls.MAX_RESIDUAL_CHARS:
            raise HistoricalAppendAntiPatternError(
                f"Updated residual exceeds O(1) size ceiling ({len(new_complete_markdown)} > {cls.MAX_RESIDUAL_CHARS} chars)."
            )

        if "Date of Record:" not in new_complete_markdown:
            raise HistoricalAppendAntiPatternError("Updated residual is missing 'Date of Record:' header.")

        prev_hash = hashlib.sha256(target_path.read_bytes()).hexdigest() if target_path.is_file() else "NONE"
        new_bytes = new_complete_markdown.encode("utf-8")
        new_hash = hashlib.sha256(new_bytes).hexdigest()

        # Gate 4: Atomic file replacement
        target_path.parent.mkdir(parents=True, exist_ok=True)
        fd, tmp_name = tempfile.mkstemp(dir=str(target_path.parent), prefix=".supersede_")
        tmp_path = Path(tmp_name)
        try:
            with os.fdopen(fd, "wb") as f:
                f.write(new_bytes)
                f.flush()
                os.fsync(f.fileno())
            os.replace(tmp_path, target_path)
        except Exception:
            tmp_path.unlink(missing_ok=True)
            raise

        return SupersessionReceipt(
            file_path=str(target_path),
            previous_sha256=prev_hash,
            new_sha256=new_hash,
            token_estimate=len(new_complete_markdown) // 4,
        )