# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-silent-divergence-in-federated-memory-planes-under-partial-write-visibility.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-silent-divergence-in-federated-memory-planes-under-partial-write-visibility.warrant.json
# Markdown SHA-256:   ff95df0da8bd9e149aac7a0ecda44000721133040c9f01c9767bf122a3509564
# Code AST SHA-256:   2b16db4ecfd656040fc33c4cb71a7152c53e1920671509e79e68483805c22397
# Verified Classes:   VisibilityOrderingError, Write, ResolvedHead, FederatedMemoryPlane
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Dict, List, Optional, Set


class VisibilityOrderingError(RuntimeError):
    """Raised when conflict resolution is invoked over a filtered read set."""


@dataclass
class Write:
    key: str
    value: object
    origin_tenant: str
    hlc: int
    seen_versions: Set[int] = field(default_factory=set)


@dataclass
class ResolvedHead:
    key: str
    value: object
    version: int
    conflicts: List[Write] = field(default_factory=list)


class FederatedMemoryPlane:
    def __init__(self) -> None:
        self._log: Dict[str, List[Write]] = {}
        self._version: Dict[str, int] = {}

    def _union_view(self, key: str) -> List[Write]:
        return list(self._log.get(key, []))

    def resolve(self, key: str, reader_tenant: str, reader_filter: Set[str]) -> ResolvedHead:
        # The invariant: resolution must see the union of all writers' histories.
        # If the caller passes a filter that trims the input to resolution, the
        # resolver is blinded and silent divergence becomes possible.
        union = self._union_view(key)
        visible_to_reader = [w for w in union if w.origin_tenant in reader_filter]
        if len(visible_to_reader) != len(union):
            # Filtering before resolution: reject rather than produce a
            # reader-dependent canonical head.
            raise VisibilityOrderingError(
                f"resolve() for key={key!r} tenant={reader_tenant!r} received a "
                f"trimmed write set ({len(visible_to_reader)}/{len(union)} visible); "
                f"resolution must precede filtering"
            )
        if not union:
            return ResolvedHead(key=key, value=None, version=0)
        # Last-writer-wins over the union, with conflict recording for any
        # write that did not observe the prior head.
        head = max(union, key=lambda w: w.hlc)
        prior = [w for w in union if w.hlc < head.hlc]
        conflicts = [w for w in prior if head.hlc not in w.seen_versions and w.value != head.value]
        version = self._version.get(key, 0) + 1
        self._version[key] = version
        return ResolvedHead(key=key, value=head.value, version=version, conflicts=conflicts)

    def write(self, w: Write) -> ResolvedHead:
        # Precondition check must be against the union, not the writer's view.
        current = self._union_view(w.key)
        if any(p.hlc >= w.hlc for p in current):
            raise VisibilityOrderingError(
                f"write to {w.key!r} at hlc={w.hlc} is not causally after existing heads"
            )
        self._log.setdefault(w.key, []).append(w)
        return self.resolve(w.key, reader_tenant=w.origin_tenant,
                            reader_filter={x.origin_tenant for x in current} | {w.origin_tenant})
