# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-irrecoverable-divergence-in-speculative-multi-agent-branch-and-merge-graphs.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-irrecoverable-divergence-in-speculative-multi-agent-branch-and-merge-graphs.warrant.json
# Markdown SHA-256:   1740d0e0b8537739baea09a8477225ea1b98e3c636545bffbc04806a22effe60
# Code AST SHA-256:   ecf38d0ca794684428bd57869f6f25bec965057d2a93a92e053de5b91474e4fa
# Verified Classes:   RollbackUnsafeError, Branch
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class RollbackUnsafeError(RuntimeError):
    """Raised when a branch cannot be safely rolled back to its fork checkpoint."""
    pass


class Branch:
    def __init__(self, branch_id, parent=None):
        self.branch_id = branch_id
        self.parent = parent
        self.external_effects = set()   # resources written outside coordinator graph
        self.tracked_writes = set()     # resources inside coordinator graph
        self.children = []

    def fork(self, child_id):
        child = Branch(child_id, parent=self)
        self.children.append(child)
        return child

    def record_external_effect(self, resource):
        self.external_effects.add(resource)

    def has_live_descendants(self):
        return any(not c.rolled_back for c in self.children)


def assert_rollback_safe(branch):
    if branch.external_effects:
        raise RollbackUnsafeError(
            f"branch {branch.branch_id} has untracked external effects: "
            f"{sorted(branch.external_effects)}; rollback would produce latent divergence"
        )
    if branch.has_live_descendants():
        raise RollbackUnsafeError(
            f"branch {branch.branch_id} has live descendant branches; "
            f"rollback must be issued at subtree root, not interior node"
        )
    return True


def rollback(branch):
    assert_rollback_safe(branch)
    branch.rolled_back = True
    return branch.parent
