# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-silent-loss-of-work-during-speculative-agent-branch-rollback-and-merge-reconciliation.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-silent-loss-of-work-during-speculative-agent-branch-rollback-and-merge-reconciliation.warrant.json
# Markdown SHA-256:   7bd2ee7d03f60421a47d3a4cc82da232ed46ab3f5354aa80a11a9fea4654f881
# Code AST SHA-256:   fc232a8e23803b765e3445bc1245e2f592656913d804ef1e9a06bdd357a5ba0e
# Verified Classes:   RollbackProvenanceError
# Defensive Guards:   1 fail-closed invariants (zero external deps)

class RollbackProvenanceError(RuntimeError):
    """Raised when a rollback would delete a branch record still referenced by a committed merge."""
    pass


def rollback_branch(branch_id, reference_index, delete_records, tombstone_records):
    """
    Roll back a speculative branch without orphaning committed merges.

    reference_index maps record_id -> set of committed merge ids that cite it.
    delete_records and tombstone_records are callables that mutate the store.
    Must be invoked inside the rollback transaction.
    """
    record_ids = list_branch_records(branch_id)
    referenced = [rid for rid in record_ids if reference_index.get(rid)]

    if referenced:
        # Unknown/abandoned branch with live provenance: tombstone, never delete.
        tombstone_records(branch_id, record_ids)
        raise RollbackProvenanceError(
            f"branch {branch_id} has {len(referenced)} record(s) referenced by "
            f"committed merges {sorted({m for rid in referenced for m in reference_index[rid]})}; "
            f"tombstoned instead of deleted"
        )

    delete_records(branch_id, record_ids)
