# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-serialize-shared-blackboards-when-agents-mutate-state-concurrently.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-serialize-shared-blackboards-when-agents-mutate-state-concurrently.warrant.json
# Markdown SHA-256:   4e144e9dca09a1568200768df75c4bc3f5f6b51d08dcc66efd7a94bd93d27a13
# Code AST SHA-256:   e03d5f570c9c2f0439222a0380b6ba90dcccec95a7574dd32b609217a5f81a4b
# Verified Classes:   SerializationVerdict, StateSnapshot, WriteIntent, BlackboardManifest, BlackboardSerializationGuard
# Defensive Guards:   0 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class SerializationVerdict(Enum):
    SAFE_TO_WRITE = auto()
    CONFLICT_DETECTED = auto()
    REQUIRES_LOCK = auto()

@dataclass(frozen=True)
class StateSnapshot:
    version: int
    payload_hash: str

@dataclass(frozen=True)
class WriteIntent:
    transaction_id: str
    expected_version: int
    new_payload_hash: str

@dataclass(frozen=True)
class BlackboardManifest:
    verdict: SerializationVerdict
    directive: str
    manifest_digest: str

class BlackboardSerializationGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_write(
        cls, snapshot: StateSnapshot, intent: WriteIntent
    ) -> BlackboardManifest:
        
        # Gate 1: Missing expected version (pessimistic lock required)
        if intent.expected_version <= 0:
            return BlackboardManifest(
                verdict=SerializationVerdict.REQUIRES_LOCK,
                directive="ACTION: Expected version missing. Acquire pessimistic lock before writing.",
                manifest_digest=cls._hash("LOCK_REQUIRED")
            )

        # Gate 2: Version conflict detection
        if intent.expected_version != snapshot.version:
            return BlackboardManifest(
                verdict=SerializationVerdict.CONFLICT_DETECTED,
                directive=f"ABORT: Expected version {intent.expected_version}, current is {snapshot.version}. Re-read and re-evaluate.",
                manifest_digest=cls._hash(f"CONFLICT:{intent.expected_version}:{snapshot.version}")
            )

        # Gate 3: Safe to write
        digest = cls._hash(json.dumps({
            "txn": intent.transaction_id,
            "version": str(snapshot.version),
            "payload": intent.new_payload_hash
        }, sort_keys=True))
        
        return BlackboardManifest(
            verdict=SerializationVerdict.SAFE_TO_WRITE,
            directive="PROCEED: Version matches. Execute atomic write.",
            manifest_digest=digest
        )