How must an instance handle divergence between its own state and a peer's authoritative state?

**Date of Record:** 2026 October 27 **Scope:** Applies when an agentic session's local state diverges from a peer's authoritative state (due to network partition, missed updates, or independent mutations), and the instance must decide whether to reconcile, defer to the peer, or escalate. Does not apply to systems with a single authoritative source, or cases where divergence is impossible.

Core Distinction

The separation between **local state authority** (the instance's local state is the source of truth for its own scope) and **peer state authority** (the peer's state is the source of truth for the peer's scope). Relying on a single authority creates the **Divergence Blindspot**: the instance assumes its local state is authoritative, overrides the peer's state with its own, and silently destroys the peer's valid mutations. Conversely, blindly deferring to the peer erases the instance's own valid work.

What Was Observed

In distributed agent architectures, failing to handle state divergence properly produces three primary failure modes:

  1. **Silent Overwrite:** The instance writes its local state over the peer's authoritative state, erasing the peer's valid mutations during a partition.
  2. **Mutual Defer:** Both the instance and the peer defer to each other, deadlocking with neither side accepting their own state.
  3. **Escalation Storm:** Every divergence triggers an escalation to human review, overwhelming operators and preventing the system from self-healing.

Recorded Elements

  1. **`state_divergence_receipt`:** A cryptographic proof that the local and peer states diverge, including both state hashes and the exact divergence scope (which fields differ).
  2. **`scope_authority_map`:** The explicit mapping of which state fields each party is authoritative for, allowing deterministic resolution without escalation.
  3. **`reconciliation_strategy_signature`:** The exact reconciliation strategy (e.g., `LOCAL_WINS`, `PEER_WINS`, `FIELD_LEVEL_MERGE`, `VECTOR_CLOCK_MERGE`), applied per field according to authority.
  4. **`escalation_threshold_predicate`:** The exact condition under which the divergence exceeds automated reconciliation capability, triggering human escalation.

Condition of Validity

* **Applies when:** The instance and peer share mutable state, divergence can occur, and the reconciliation decision affects downstream behavior. * **Does not apply when:** The instance has a single authoritative source (no divergence), or the state is strictly immutable (no mutation possible).

Decision Boundary

  1. **Do the local and peer states diverge?** If no, standard state operations apply. If yes, proceed.
  2. **Is the `scope_authority_map` defined for all divergent fields?** If yes, apply the authority map. If no, escalate or use default reconciliation.
  3. **Does the divergent scope exceed the `escalation_threshold_predicate`?** If yes, escalate to human. If no, apply the `reconciliation_strategy_signature`.
  4. **Conversely, when can an instance resolve divergence without escalation?** Only when the `scope_authority_map` provides unambiguous assignment for all divergent fields, or one side's state is cryptographically proven to supersede the other.

Operational Effect

  1. **Silent Overwrite Prevention:** Uses authority maps to prevent unilateral overwriting of the peer's valid state.
  2. **Deadlock Prevention:** Provides deterministic reconciliation, avoiding mutual deferral.
  3. **Escalation Discipline:** Only escalates when divergence exceeds automated reconciliation capability, preserving human attention for genuine ambiguity.
from dataclasses import dataclass
from enum import Enum, auto
import hashlib
import json

class DivergenceVerdict(Enum):
    NO_DIVERGENCE = auto()
    RESOLVED_BY_AUTHORITY = auto()
    RESOLVED_BY_MERGE = auto()
    ESCALATE_TO_HUMAN = auto()

@dataclass(frozen=True)
class StateDivergence:
    local_state_hash: str
    peer_state_hash: str
    divergent_field_count: int
    total_field_count: int
    shared_authority_fields: tuple[str, ...]

@dataclass(frozen=True)
class ReconciliationContext:
    local_authority_fields: frozenset[str]
    peer_authority_fields: frozenset[str]
    escalation_ratio_threshold: float

@dataclass(frozen=True)
class DivergenceManifest:
    verdict: DivergenceVerdict
    directive: str
    manifest_digest: str

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

    @classmethod
    def evaluate_divergence(
        cls, divergence: StateDivergence, ctx: ReconciliationContext
    ) -> DivergenceManifest:
        
        # Gate 1: No divergence
        if divergence.local_state_hash == divergence.peer_state_hash:
            digest = cls._hash(json.dumps({
                "state": divergence.local_state_hash
            }, sort_keys=True))
            return DivergenceManifest(
                verdict=DivergenceVerdict.NO_DIVERGENCE,
                directive="PROCEED: States identical.",
                manifest_digest=digest
            )

        # Gate 2: Shared authority fields
        if divergence.shared_authority_fields:
            return DivergenceManifest(
                verdict=DivergenceVerdict.ESCALATE_TO_HUMAN,
                directive=f"HALT: {len(divergence.shared_authority_fields)} fields have shared authority: {sorted(divergence.shared_authority_fields)}.",
                manifest_digest=cls._hash(f"SHARED_AUTHORITY:{len(divergence.shared_authority_fields)}")
            )

        # Gate 3: Escalation threshold
        if divergence.total_field_count == 0:
            ratio = 0.0
        else:
            ratio = divergence.divergent_field_count / divergence.total_field_count

        if ratio > ctx.escalation_ratio_threshold:
            return DivergenceManifest(
                verdict=DivergenceVerdict.ESCALATE_TO_HUMAN,
                directive=f"HALT: Divergence ratio {ratio:.2%} > {ctx.escalation_ratio_threshold:.2%}. Escalate.",
                manifest_digest=cls._hash(f"RATIO:{ratio:.3f}")
            )

        # Gate 4: Authority resolution
        digest = cls._hash(json.dumps({
            "local": divergence.local_state_hash,
            "peer": divergence.peer_state_hash,
            "divergent": str(divergence.divergent_field_count),
            "local_authority": tuple(sorted(ctx.local_authority_fields)),
            "peer_authority": tuple(sorted(ctx.peer_authority_fields))
        }, sort_keys=True))
        
        return DivergenceManifest(
            verdict=DivergenceVerdict.RESOLVED_BY_AUTHORITY,
            directive=f"PROCEED: Apply authority map for {divergence.divergent_field_count} divergent fields.",
            manifest_digest=digest
        )