# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-checkpoint-before-speculative-multi-agent-rollback-to-remain-sound.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-checkpoint-before-speculative-multi-agent-rollback-to-remain-sound.warrant.json
# Markdown SHA-256:   883fe4a77aaced3d597e6c210fdc8070551b10c236a478e6cc8f72955dd9a446
# Code AST SHA-256:   55e47a2ba088fc722ebdf7872fb03ab879375f000be1507a580d394d5bc3fab2
# Verified Classes:   UncompensableEffectError, EffectSurface
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class UncompensableEffectError(RuntimeError):
    """Raised when a speculative branch emits an external effect that the
    orchestrator cannot defer or compensate on discard."""
    pass


class EffectSurface:
    def __init__(self):
        self.compensable = set()
        self.deferred = set()

    def declare_compensable(self, tool_name: str) -> None:
        self.compensable.add(tool_name)

    def declare_deferred(self, tool_name: str) -> None:
        self.deferred.add(tool_name)

    def covers(self, tool_name: str) -> bool:
        return tool_name in self.compensable or tool_name in self.deferred


def checkpoint_before_fork(surface: EffectSurface, reachable_tools: set) -> None:
    uncovered = {t for t in reachable_tools if not surface.covers(t)}
    if uncovered:
        raise UncompensableEffectError(
            f"cannot speculate past non-compensable effects: {sorted(uncovered)}; "
            f"checkpoint and serialize branches crossing these tools"
        )


def emit_effect(surface: EffectSurface, tool_name: str, payload) -> None:
    if not surface.covers(tool_name):
        raise UncompensableEffectError(
            f"branch emitted effect from uncovered tool {tool_name!r}; "
            f"ghost write would survive discard"
        )
    # defer or compensate per surface declaration
