# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-reconcile-a-semantic-memory-record-whose-staleness-flag-was-set-by-a-different-writer-than-the-one-that-produced-the-current-va.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-reconcile-a-semantic-memory-record-whose-staleness-flag-was-set-by-a-different-writer-than-the-one-that-produced-the-current-va.warrant.json
# Markdown SHA-256:   47b20c89a40cc15360ec178776ece2a5f18ca1528e4b0b7805dc7c5121b64871
# Code AST SHA-256:   b555951a183175cc262bdb17a78b888ea2a545c069c55c2fe89bf73f8af8f3b2
# Verified Classes:   StaleFlagProvenanceError, SemanticRecord
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from typing import Optional


class StaleFlagProvenanceError(RuntimeError):
    """Raised when a staleness flag cannot be safely attributed to a value version."""


@dataclass(frozen=True)
class SemanticRecord:
    key: str
    value: object
    version: int
    stale: bool
    flag_against_version: Optional[int]  # None == unguarded flag, provenance unknown


def resolve_on_read(record: SemanticRecord) -> tuple[str, object]:
    """Return ('serve', value) or ('fallback', None) per version-scoped staleness policy."""
    if not record.stale:
        return ("serve", record.value)

    if record.flag_against_version is None:
        # Unguarded flag: cannot attribute to this value. Treat as fresh but signal repair.
        return ("serve_needs_repair", record.value)

    if record.flag_against_version == record.version:
        return ("fallback", None)

    if record.flag_against_version < record.version:
        # Flag was computed against a superseded version; the current value was never
        # evaluated by the detector. Do not honor it.
        return ("serve_needs_repair", record.value)

    # flag_against_version > version: monotonicity violation or cross-region skew.
    raise StaleFlagProvenanceError(
        f"flag_against_version={record.flag_against_version} > version={record.version} "
        f"for key={record.key!r}; refusing to resolve"
    )


def repair_flag(record: SemanticRecord, expected_version: int) -> SemanticRecord:
    """Clear an inherited flag via CAS on version; abort if version moved."""
    if record.version != expected_version:
        raise StaleFlagProvenanceError(
            f"CAS failed for key={record.key!r}: expected v{expected_version}, "
            f"found v{record.version}"
        )
    return SemanticRecord(
        key=record.key,
        value=record.value,
        version=record.version,
        stale=False,
        flag_against_version=None,
    )
