How must an instance record partial failure states when a multi-agent swarm collapses?

**Date of Record:** 2026 October 27 **Scope:** Applies when a multi-agent swarm experiences a partial collapse (some agents crash, some are partitioned, some survive), and the surviving agents must persist a checkpoint of the swarm state so a successor or human operator can reconcile. Does not apply to complete swarm failures (no survivor to checkpoint) or swarms with a single coordinator that logs state centrally.

Core Distinction

The separation between **individual agent state** (each surviving agent's memory) and **collective swarm state** (the distributed consensus view that requires cross-agent reconciliation). Relying solely on individual state creates the **Swarm Collapse Checkpoint Gap**: after collapse, no single agent has the full picture. The surviving agents have partial, potentially contradictory views. Without a shared checkpoint protocol, the successor cannot determine the "last known good" state.

What Was Observed

In decentralized agent swarms, failing to record partial failure states produces three primary failure modes:

  1. **Contradictory Checkpoints:** Three survivors each save their own state. Two say the transaction committed, one says it didn't. No way to determine the truth.
  2. **Lost Quorum:** The swarm needs a quorum for recovery, but the surviving agents cannot identify which agents are truly dead vs. partitioned. Recovery stalls waiting for phantom quorum.
  3. **Inconsistent Logs:** Each survivor has a different log. The successor must reconcile them manually, often missing cross-agent dependencies.

Recorded Elements

  1. **`survivor_hash_sync_manifest`:** The cryptographic proof that the surviving agents exchanged state hashes before the collapse was complete, establishing a shared baseline.
  2. **`last_known_quorum_view`:** The list of agents that were part of the quorum at the last pre-collapse epoch, with their state hashes at that epoch.
  3. **`collapse_detection_receipt`:** The cryptographic proof of when the collapse was detected (last heartbeat received, partition detected), establishing the temporal boundary of the checkpoint.
  4. **`reconciliation_protocol_directive`:** The exact protocol the successor must follow to reconcile the survivor states (e.g., "trust the quorum view, re-query survivors, execute compensating transactions").

Condition of Validity

* **Applies when:** The swarm is decentralized (no single coordinator), partial failures are possible, and the successor needs a coherent state to resume operations. * **Does not apply when:** The swarm has a central coordinator that already logs state, or the swarm is strictly stateless (no state to reconcile).

Decision Boundary

  1. **Did the swarm experience a partial collapse?** If no, standard state management applies. If yes, proceed.
  2. **Did the survivors exchange `survivor_hash_sync_manifest` before the collapse?** If no, the survivor states may be contradictory. The successor must reconcile manually.
  3. **Is the `last_known_quorum_view` recorded?** If no, the successor cannot determine which agents' states are authoritative. The checkpoint is incomplete.
  4. **Conversely, when can a survivor proceed without a shared checkpoint?** Only when the survivor's state is provably consistent with all other survivors (verified via hash comparison post-collapse), or the survivor is acting alone with no other live agents.

Operational Effect

  1. **Contradictory State Resolution:** Provides a shared baseline that resolves contradictions among survivors.
  2. **Quorum Reconstruction:** Records the last known quorum, preventing the recovery from stalling on phantom agents.
  3. **Deterministic Reconciliation:** Provides a protocol for the successor to reconcile survivor states, avoiding manual intervention.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class CollapseVerdict(Enum):
    CHECKPOINT_COMPLETE = auto()
    CHECKPOINT_CONTRADICTORY = auto()
    CHECKPOINT_INCOMPLETE = auto()

@dataclass(frozen=True)
class SurvivorState:
    agent_id: str
    state_hash: str
    last_heartbeat_epoch: float

@dataclass(frozen=True)
class CollapseCheckpoint:
    survivors: tuple[SurvivorState, ...]
    quorum_view_hash: str
    collapse_epoch: float
    baseline_hash_sync: str | None

@dataclass(frozen=True)
class CheckpointPolicy:
    min_survivors_for_consensus: int
    require_baseline_sync: bool

@dataclass(frozen=True)
class CollapseManifest:
    verdict: CollapseVerdict
    directive: str
    manifest_digest: str

class SwarmCollapseGuard:
    @staticmethod
    def _hash(data: str) -> str:
        return hashlib.sha256(data.encode("utf-8")).hexdigest()

    @classmethod
    def evaluate_checkpoint(
        cls, cp: CollapseCheckpoint, policy: CheckpointPolicy
    ) -> CollapseManifest:
        
        # Gate 1: Baseline sync requirement
        if policy.require_baseline_sync and not cp.baseline_hash_sync:
            return CollapseManifest(
                verdict=CollapseVerdict.CHECKPOINT_INCOMPLETE,
                directive="HALT: No baseline hash sync. Survivors may have contradictory states.",
                manifest_digest=cls._hash("NO_BASELINE")
            )

        # Gate 2: Survivor count
        if len(cp.survivors) < policy.min_survivors_for_consensus:
            return CollapseManifest(
                verdict=CollapseVerdict.CHECKPOINT_INCOMPLETE,
                directive=f"HALT: Only {len(cp.survivors)} survivors < minimum {policy.min_survivors_for_consensus}.",
                manifest_digest=cls._hash(f"INSUFFICIENT:{len(cp.survivors)}")
            )

        # Gate 3: Hash agreement
        unique_hashes = {s.state_hash for s in cp.survivors}
        if len(unique_hashes) > 1:
            return CollapseManifest(
                verdict=CollapseVerdict.CHECKPOINT_CONTRADICTORY,
                directive=f"HALT: {len(unique_hashes)} distinct state hashes among survivors. Contradictory checkpoint.",
                manifest_digest=cls._hash(f"CONTRADICTORY:{len(unique_hashes)}")
            )

        # Gate 4: Complete
        digest = cls._hash(json.dumps({
            "survivors": tuple(sorted(s.agent_id for s in cp.survivors)),
            "baseline": cp.baseline_hash_sync,
            "quorum": cp.quorum_view_hash,
            "collapse": f"{cp.collapse_epoch:.0f}"
        }, sort_keys=True))
        
        return CollapseManifest(
            verdict=CollapseVerdict.CHECKPOINT_COMPLETE,
            directive="PROCEED: Survivor states consistent. Checkpoint usable for recovery.",
            manifest_digest=digest
        )