# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-when-cross-org-speculative-execution-must-abort-rather-than-merge.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-when-cross-org-speculative-execution-must-abort-rather-than-merge.warrant.json
# Markdown SHA-256:   43cd2a7ca519c5f1267313f5ad2e088031006f5546fecacb7fa5a1bd237bd081
# Code AST SHA-256:   c89334c863f376cfc5dc0762717764f9b8d776e7f55678d3a2c3513a747d73b1
# Verified Classes:   UnsafeSpeculativeMerge, Branch, ClosureGraph
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass, field
from typing import FrozenSet, Mapping, Optional


class UnsafeSpeculativeMerge(RuntimeError):
    """Raised when a cross-org speculative merge cannot be proven conflict-free."""


@dataclass(frozen=True)
class Branch:
    org: str
    reads: FrozenSet[str]
    writes: FrozenSet[str]


@dataclass
class ClosureGraph:
    # derived_state -> set of base states whose mutation invalidates it
    edges: Mapping[str, FrozenSet[str]] = field(default_factory=dict)
    # timestamp/version of the graph; must be >= materializer lag bound
    version: int = 0

    def closure(self, seeds: FrozenSet[str]) -> FrozenSet[str]:
        seen: set[str] = set()
        stack = list(seeds)
        while stack:
            node = stack.pop()
            if node in seen:
                continue
            seen.add(node)
            stack.extend(self.edges.get(node, frozenset()))
        return frozenset(seen)


def merge_speculative(
    a: Branch,
    b: Branch,
    graph: Optional[ClosureGraph],
    min_graph_version: int,
    shared_invariants: Mapping[str, FrozenSet[str]],
) -> None:
    if a.writes & b.writes:
        raise UnsafeSpeculativeMerge(
            f"direct write conflict between {a.org} and {b.org}: "
            f"{sorted(a.writes & b.writes)}"
        )

    if graph is None or graph.version < min_graph_version:
        raise UnsafeSpeculativeMerge(
            "derived-state closure graph missing or stale; "
            "write-set disjointness alone is not proof of non-interference"
        )

    a_vs_b = a.reads & graph.closure(b.writes)
    b_vs_a = b.reads & graph.closure(a.writes)
    if a_vs_b or b_vs_a:
        raise UnsafeSpeculativeMerge(
            f"cross-branch read-to-write edge through derived state: "
            f"{a.org} reads {sorted(a_vs_b)} invalidated by {b.org}; "
            f"{b.org} reads {sorted(b_vs_a)} invalidated by {a.org}"
        )

    for name, members in shared_invariants.items():
        touched_by_a = members & (a.reads | a.writes)
        touched_by_b = members & (b.reads | b.writes)
        if touched_by_a and touched_by_b:
            raise UnsafeSpeculativeMerge(
                f"shared invariant '{name}' spans both branches: "
                f"{sorted(touched_by_a)} vs {sorted(touched_by_b)}"
            )
    # merge proceeds here
