# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-distrust-cross-session-consistency-as-evidence-of-memory-poisoning.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-distrust-cross-session-consistency-as-evidence-of-memory-poisoning.warrant.json
# Markdown SHA-256:   cda99665cb4ff14d1a115460bff73b50e77a5d94bd5a1f38eea983be1de20386
# Code AST SHA-256:   8b8bbed5340775477dd46e5b42d2664e259f612b5eb43e75a02e741abca0e3cf
# Verified Classes:   ProvenanceStateError
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class ProvenanceStateError(RuntimeError):
    """Raised when a memory write's provenance cannot be classified
    into a tier-checkable state, making content-diff evidence inadmissible."""
    pass


TIER_ORDER = {"system": 3, "operator": 2, "agent-verified": 1, "untrusted-tool": 0}


def classify_memory_write(write, key_policy_tier, prior_value, journal):
    """
    write: dict with keys 'value', 'provenance' (or None),
           'provenance_signature_verifies' (bool), 'session_id'
    Returns one of: 'benign_update', 'tier_violation',
                    'provenance_unverifiable', 'unexplained_mutation'.
    Raises ProvenanceStateError when the write cannot be classified.
    """
    prov = write.get("provenance")
    content_diverged = (write["value"] != prior_value)

    # Branch 1: provenance present but signature fails -> repair path.
    if prov is not None and not write.get("provenance_signature_verifies", False):
        repaired = journal.repair(write["session_id"])
        if repaired is None:
            # Cannot decide whether this is poisoning or snapshot truncation.
            raise ProvenanceStateError(
                f"unverifiable provenance for session {write['session_id']!r} "
                f"and no journal repair record; content_diverged={content_diverged}"
            )
        return "provenance_unverifiable"

    # Branch 2: provenance absent entirely -> unexplained mutation, not poisoning.
    if prov is None:
        if content_diverged:
            return "unexplained_mutation"
        return "benign_update"

    # Branch 3: provenance verifies -> tier check is the sole detector.
    tier = prov.get("tier")
    if tier not in TIER_ORDER:
        raise ProvenanceStateError(f"unknown provenance tier {tier!r}")
    if TIER_ORDER[tier] < TIER_ORDER[key_policy_tier]:
        return "tier_violation"

    # Branch 4: provenance verifies and tier is compliant.
    # Any content divergence here is a benign update by construction.
    return "benign_update"