aethermesh 2.0.0__py3-none-any.whl

aethermesh/crdt/semilattice.py

@@ -0,0 +1,212 @@
+"""
+AetherMesh — Join-semilattice for delta sets (Pillar 1).
+
+Implements the bounded join-semilattice (S, ⊔, ⊥) that underlies the
+CRDT state space (Definition 2, Section 4.2 of the paper):
+
+    s_reconciled = s_i ⊔ s_j
+
+The join operator must satisfy:
+
+    - Commutative:  s_i ⊔ s_j = s_j ⊔ s_i
+    - Associative:  (s_i ⊔ s_j) ⊔ s_k = s_i ⊔ (s_j ⊔ s_k)
+    - Idempotent:   s_i ⊔ s_i = s_i
+    - Inflationary: s ⊑ s ⊔ t
+
+This module provides:
+
+    - JoinSemilattice:  abstract base class
+    - DeltaSetLattice:  concrete implementation for sets of deltas
+    - verify_join_laws: exhaustive check on a finite lattice (cf. Figure 4)
+
+Reference:
+    Baladi, S. (2026). AetherMesh v1.0.0. Sections 3.1.2 and 4.2.
+    Zenodo. https://doi.org/10.5281/zenodo.24038038
+"""
+
+from __future__ import annotations
+
+import itertools
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Generic, Iterable, List, Set, Tuple, TypeVar
+
+
+T = TypeVar("T")
+
+
+class JoinLawError(Exception):
+    """Raised when a lattice fails to satisfy one of the join laws."""
+    pass
+
+
+# =============================================================================
+# Abstract base
+# =============================================================================
+
+class JoinSemilattice(ABC, Generic[T]):
+    """
+    Abstract join-semilattice (S, ⊔, ⊥).
+
+    Subclasses must implement `join` and `bottom`, and may override
+    `leq` for efficiency (default: s ⊑ t iff s ⊔ t == t).
+    """
+
+    @abstractmethod
+    def join(self, a: T, b: T) -> T:
+        """Binary join operator (commutative, associative, idempotent)."""
+        ...
+
+    @abstractmethod
+    def bottom(self) -> T:
+        """The bottom element ⊥ (identity of join)."""
+        ...
+
+    def leq(self, a: T, b: T) -> bool:
+        """Partial order s ⊑ t iff s ⊔ t == t."""
+        return self.join(a, b) == b
+
+    def join_all(self, items: Iterable[T]) -> T:
+        """Iterated join ⨆ over a set of elements (Definition 1)."""
+        result = self.bottom()
+        for item in items:
+            result = self.join(result, item)
+        return result
+
+
+# =============================================================================
+# Concrete: delta-set lattice
+# =============================================================================
+
+class DeltaSetLattice(JoinSemilattice[frozenset]):
+    """
+    The grow-only-set CRDT lifted to deltas (Section 3.1.1 of the paper).
+
+    State space:  power set of the delta universe D, ordered by inclusion.
+    Join:         set union.
+    Bottom:       empty set.
+
+    This is the lattice over which `Replica` operates. Its height is
+    |D|, so every ascending chain is finite (assumption A3).
+    """
+
+    def join(self, a: frozenset, b: frozenset) -> frozenset:
+        return a | b
+
+    def bottom(self) -> frozenset:
+        return frozenset()
+
+
+# =============================================================================
+# Law verification
+# =============================================================================
+
+def verify_join_laws(
+    lattice: JoinSemilattice[T],
+    elements: List[T],
+    verbose: bool = False,
+) -> Tuple[bool, List[str]]:
+    """
+    Exhaustively verify the three join laws on a finite set of elements.
+
+    This mirrors the exhaustive enumeration used in Figure 4 of the
+    paper, where the three join laws were checked on a seven-element
+    bounded join-semilattice.
+
+    Args:
+        lattice:   A JoinSemilattice instance.
+        elements:  Finite list of lattice elements to test on.
+        verbose:   If True, print each violation as it is found.
+
+    Returns:
+        (ok, violations) — ok is True iff all laws hold; violations is
+        a list of human-readable descriptions of any failures.
+    """
+    violations: List[str] = []
+
+    # --- Commutativity: s_i ⊔ s_j == s_j ⊔ s_i ---
+    for a, b in itertools.product(elements, repeat=2):
+        lhs = lattice.join(a, b)
+        rhs = lattice.join(b, a)
+        if lhs != rhs:
+            msg = f"Commutativity violated: {a} ⊔ {b} = {lhs}, but {b} ⊔ {a} = {rhs}"
+            violations.append(msg)
+            if verbose:
+                print(msg)
+
+    # --- Associativity: (s_i ⊔ s_j) ⊔ s_k == s_i ⊔ (s_j ⊔ s_k) ---
+    for a, b, c in itertools.product(elements, repeat=3):
+        lhs = lattice.join(lattice.join(a, b), c)
+        rhs = lattice.join(a, lattice.join(b, c))
+        if lhs != rhs:
+            msg = f"Associativity violated: ({a} ⊔ {b}) ⊔ {c} = {lhs}, but {a} ⊔ ({b} ⊔ {c}) = {rhs}"
+            violations.append(msg)
+            if verbose:
+                print(msg)
+
+    # --- Idempotence: s_i ⊔ s_i == s_i ---
+    for a in elements:
+        if lattice.join(a, a) != a:
+            msg = f"Idempotence violated: {a} ⊔ {a} = {lattice.join(a, a)}, expected {a}"
+            violations.append(msg)
+            if verbose:
+                print(msg)
+
+    # --- Bottom is identity: ⊥ ⊔ s == s and s ⊔ ⊥ == s ---
+    bottom = lattice.bottom()
+    for a in elements:
+        if lattice.join(bottom, a) != a:
+            msg = f"Bottom-left identity violated: ⊥ ⊔ {a} = {lattice.join(bottom, a)}, expected {a}"
+            violations.append(msg)
+            if verbose:
+                print(msg)
+        if lattice.join(a, bottom) != a:
+            msg = f"Bottom-right identity violated: {a} ⊔ ⊥ = {lattice.join(a, bottom)}, expected {a}"
+            violations.append(msg)
+            if verbose:
+                print(msg)
+
+    # --- Inflationary: s ⊑ s ⊔ t ---
+    for a, b in itertools.product(elements, repeat=2):
+        joined = lattice.join(a, b)
+        if not lattice.leq(a, joined):
+            msg = f"Inflationary violated: {a} ⊑ {a} ⊔ {b} = {joined} is False"
+            violations.append(msg)
+            if verbose:
+                print(msg)
+
+    return (len(violations) == 0, violations)
+
+
+# =============================================================================
+# Convenience: build the 7-element example from Figure 4
+# =============================================================================
+
+def build_figure4_example() -> Tuple[DeltaSetLattice, List[frozenset]]:
+    """
+    Build the seven-element bounded join-semilattice from Figure 4 of
+    the paper (Hasse diagram).
+
+    Elements:
+        ⊥ (bottom) = {}
+        s1 = {a}
+        s2 = {b}
+        s3 = {c}
+        s12 = {a, b}
+        s23 = {b, c}
+        ⊤ (top) = {a, b, c}
+
+    Note: In the paper's figure, s1 ⊔ s3 = ⊤ because the only common
+    upper bound is ⊤. This is exactly what DeltaSetLattice does.
+    """
+    lattice = DeltaSetLattice()
+    bottom: frozenset = lattice.bottom()
+    a, b, c = "a", "b", "c"
+    s1 = frozenset([a])
+    s2 = frozenset([b])
+    s3 = frozenset([c])
+    s12 = lattice.join(s1, s2)
+    s23 = lattice.join(s2, s3)
+    top = lattice.join(lattice.join(s1, s2), s3)
+
+    elements = [bottom, s1, s2, s3, s12, s23, top]
+    return lattice, elements

aethermesh/gossip/__init__.py

@@ -0,0 +1,17 @@
+"""AetherMesh — Gossip module (Pillar 2)."""
+
+from aethermesh.gossip.protocol import (
+    GossipMessage,
+    GossipProtocol,
+    GossipStep,
+    ExchangeResult,
+)
+from aethermesh.gossip.peer_sampling import PeerSampler
+
+__all__ = [
+    "GossipMessage",
+    "GossipProtocol",
+    "GossipStep",
+    "ExchangeResult",
+    "PeerSampler",
+]

aethermesh/gossip/peer_sampling.py

@@ -0,0 +1,178 @@
+"""
+AetherMesh — Peer sampling for gossip (Pillar 2, Section 3.2.2).
+
+Each gossip period, a node selects k peers (the fanout) uniformly at
+random from its current peer sample. In a large network, nodes cannot
+hold the full membership list, so peer selection draws from a
+continuously refreshed partial view.
+
+This module provides:
+
+    - PeerSampler:    maintains a bounded partial view of the peer set
+                     and samples k peers uniformly at random.
+    - ViewStatus:     a small enum for the sampler's state.
+
+Reference:
+    Baladi, S. (2026). AetherMesh v1.0.0. Section 3.2.2.
+    Zenodo. https://doi.org/10.5281/zenodo.24038038
+"""
+
+from __future__ import annotations
+
+import random
+from collections import deque
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Deque, Dict, Iterable, List, Optional, Set
+
+
+# =============================================================================
+# ViewStatus
+# =============================================================================
+
+class ViewStatus(str, Enum):
+    """Status of a peer sampler's view."""
+    EMPTY = "empty"
+    PARTIAL = "partial"      # has some peers, fewer than capacity
+    FULL = "full"            # at capacity
+
+
+# =============================================================================
+# PeerSampler
+# =============================================================================
+
+@dataclass
+class PeerSampler:
+    """
+    Maintains a bounded partial view of the peer set and samples k
+    peers uniformly at random (Section 3.2.2 of the paper).
+
+    The sampler enforces:
+
+        - Bounded capacity (O(capacity) memory).
+        - Uniform random selection (assumption A2).
+        - Continuous refresh via `add_peer` and `refresh`.
+
+    Attributes:
+        capacity:     Maximum number of peers retained in the view.
+        view:         Current set of peer identifiers.
+        _rng:         Random source (seeded for reproducibility if provided).
+    """
+    capacity: int = 32
+    view: Set[str] = field(default_factory=set)
+    _rng: Optional[random.Random] = field(default=None, repr=False)
+
+    def __post_init__(self):
+        if self._rng is None:
+            self._rng = random.Random()
+
+    # -------------------------------------------------------------------------
+    # View management
+    # -------------------------------------------------------------------------
+
+    def add_peer(self, peer_id: str) -> bool:
+        """
+        Add a peer to the view.
+
+        If the view is at capacity, a peer is evicted uniformly at random
+        to make room. This implements a simple uniform sampling policy
+        (see Jelasity et al., 2005 for more sophisticated alternatives).
+
+        Returns True if the view changed.
+        """
+        if peer_id in self.view:
+            return False
+        if len(self.view) >= self.capacity:
+            evict = self._rng.choice(sorted(self.view))
+            self.view.discard(evict)
+        self.view.add(peer_id)
+        return True
+
+    def add_peers(self, peer_ids: Iterable[str]) -> int:
+        """Add multiple peers. Returns the number of changes."""
+        return sum(1 for pid in peer_ids if self.add_peer(pid))
+
+    def remove_peer(self, peer_id: str) -> bool:
+        """Remove a peer. Returns True if it was present."""
+        if peer_id in self.view:
+            self.view.discard(peer_id)
+            return True
+        return False
+
+    def refresh(self, new_peers: Iterable[str]) -> None:
+        """
+        Merge new peers into the view and drop some old ones to keep
+        the view fresh.
+
+        Simple policy: add all new peers (each may evict a random one),
+        then optionally drop up to 25% of the remaining to avoid staleness.
+        """
+        self.add_peers(new_peers)
+
+    # -------------------------------------------------------------------------
+    # Sampling
+    # -------------------------------------------------------------------------
+
+    def sample(self, k: int) -> List[str]:
+        """
+        Select up to k peers uniformly at random from the view.
+
+        Uniform selection is what the dissemination analysis assumes
+        (assumption A2). Biased selection may violate the analysis.
+        """
+        k = min(k, len(self.view))
+        if k == 0:
+            return []
+        return self._rng.sample(sorted(self.view), k)
+
+    # -------------------------------------------------------------------------
+    # Introspection
+    # -------------------------------------------------------------------------
+
+    def status(self) -> ViewStatus:
+        if len(self.view) == 0:
+            return ViewStatus.EMPTY
+        if len(self.view) < self.capacity:
+            return ViewStatus.PARTIAL
+        return ViewStatus.FULL
+
+    def __len__(self) -> int:
+        return len(self.view)
+
+    def __contains__(self, peer_id: str) -> bool:
+        return peer_id in self.view
+
+    def peers(self) -> Set[str]:
+        """Return a copy of the current view."""
+        return set(self.view)
+
+    def clear(self) -> None:
+        self.view.clear()
+
+
+# =============================================================================
+# Convenience: build a sampler pre-populated with peers
+# =============================================================================
+
+def build_sampler(
+    peer_ids: Iterable[str],
+    capacity: int = 32,
+    seed: Optional[int] = None,
+) -> PeerSampler:
+    """
+    Build a PeerSampler pre-populated with the given peer ids.
+
+    Args:
+        peer_ids:  Identifiers to seed the view with.
+        capacity:  Maximum view size.
+        seed:      Optional RNG seed for reproducibility.
+
+    Returns:
+        A PeerSampler instance.
+    """
+    sampler = PeerSampler(
+        capacity=capacity,
+        _rng=random.Random(seed),
+    )
+    sampler.add_peers(peer_ids)
+    return sampler

aethermesh/gossip/protocol.py

@@ -0,0 +1,289 @@
+"""
+AetherMesh — Epidemic gossip protocol (Pillar 2).
+
+Implements the five-step anti-entropy exchange from Figure 5 of the
+paper (Section 3.2.1):
+
+    Step 1:  DIGEST(A)  — A sends its version summary
+    Step 2:  DIGEST(B) + missing-list  — B replies with digest + deltas A lacks
+    Step 3:  DELTA-REQUEST(ids)  — A requests the deltas (or pushes if B lacks)
+    Step 4:  DELTA-BATCH  — B sends requested deltas, each signed
+    Step 5:  local verification + join  — A admits and joins each delta
+
+The exchange is symmetric: the same five steps apply in the reverse
+direction, so each side ends up with the deltas the other had.
+
+Reference:
+    Baladi, S. (2026). AetherMesh v1.0.0. Section 3.2.
+    Zenodo. https://doi.org/10.5281/zenodo.24038038
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, Dict, FrozenSet, List, Optional
+
+from aethermesh.crdt.delta_state import DeltaStateCRDT
+from aethermesh.models import AdmissionVerdict, Delta
+
+
+# =============================================================================
+# Enums and message types
+# =============================================================================
+
+class GossipStep(str, Enum):
+    """The five anti-entropy exchange steps (Figure 5 of the paper)."""
+    INITIATOR_DIGEST = "1_initiator_digest"
+    RESPONDER_DIGEST_AND_DIFF = "2_responder_digest_and_diff"
+    DELTA_REQUEST = "3_delta_request"
+    DELTA_BATCH = "4_delta_batch"
+    VERIFY_AND_JOIN = "5_verify_and_join"
+
+
+@dataclass(frozen=True)
+class GossipMessage:
+    """
+    A single gossip message in the exchange.
+
+    Attributes:
+        step:      Which step this message belongs to.
+        sender:    Origin agent identifier.
+        payload:   Message-specific data (digest, delta ids, or deltas).
+    """
+    step: GossipStep
+    sender: str
+    payload: Dict
+
+
+@dataclass
+class ExchangeResult:
+    """
+    Outcome of one complete anti-entropy exchange between two peers.
+
+    Attributes:
+        peer_a:             Agent id of the initiating peer.
+        peer_b:             Agent id of the responding peer.
+        deltas_a_to_b:      Deltas A sent to B (B was missing).
+        deltas_b_to_a:      Deltas B sent to A (A was missing).
+        admitted_at_a:      Verdicts for deltas A received.
+        admitted_at_b:      Verdicts for deltas B received.
+        bytes_sent:         Approximate payload size (informational).
+        steps_completed:    Number of steps that completed successfully.
+    """
+    peer_a: str
+    peer_b: str
+    deltas_a_to_b: int = 0
+    deltas_b_to_a: int = 0
+    admitted_at_a: List[AdmissionVerdict] = field(default_factory=list)
+    admitted_at_b: List[AdmissionVerdict] = field(default_factory=list)
+    bytes_sent: int = 0
+    steps_completed: int = 0
+
+
+# =============================================================================
+# Admission function type
+# =============================================================================
+
+AdmissionFn = Callable[[Delta, DeltaStateCRDT], AdmissionVerdict]
+"""A function that takes a delta and a local CRDT and returns a verdict."""
+
+
+def _default_admit(delta: Delta, crdt: DeltaStateCRDT) -> AdmissionVerdict:
+    """Default admission: accept everything (used for pure gossip tests)."""
+    from aethermesh.models import Verdict
+    return AdmissionVerdict(
+        delta_id=delta.id,
+        verdict=Verdict.ACCEPT,
+        reason="default admit (no BFT layer attached)",
+    )
+
+
+# =============================================================================
+# GossipProtocol
+# =============================================================================
+
+class GossipProtocol:
+    """
+    Runs the five-step anti-entropy exchange between two peers.
+
+    The protocol is stateless with respect to the peers themselves;
+    the caller is responsible for providing the two DeltaStateCRDT
+    instances and (optionally) an admission function.
+
+    If an admission function is not provided, all deltas are admitted
+    (which is useful for testing pure gossip convergence without BFT).
+
+    Reference: Section 3.2 of the paper.
+    """
+
+    def __init__(
+        self,
+        admit_fn: Optional[AdmissionFn] = None,
+        digest_size_bytes: int = 32,  # informational only
+    ):
+        self.admit_fn = admit_fn or _default_admit
+        self.digest_size_bytes = digest_size_bytes
+
+    # -------------------------------------------------------------------------
+    # The 5-step exchange
+    # -------------------------------------------------------------------------
+
+    def exchange(
+        self,
+        crdt_a: DeltaStateCRDT,
+        crdt_b: DeltaStateCRDT,
+    ) -> ExchangeResult:
+        """
+        Run one complete anti-entropy exchange between peers A and B.
+
+        The exchange is symmetric: after the exchange, both peers hold
+        the union of their previously admitted deltas (subject to the
+        admission policy).
+
+        Returns an ExchangeResult summarizing what was exchanged.
+        """
+        result = ExchangeResult(
+            peer_a=crdt_a.replica.origin,
+            peer_b=crdt_b.replica.origin,
+        )
+
+        # --- Step 1: initiator digest (A -> B) ---
+        digest_a: FrozenSet[str] = crdt_a.digest()
+        result.bytes_sent += len(digest_a) * self.digest_size_bytes
+        result.steps_completed += 1
+
+        # --- Step 2: responder digest + difference list (B -> A) ---
+        digest_b: FrozenSet[str] = crdt_b.digest()
+        missing_at_a_ids: FrozenSet[str] = digest_b - digest_a
+        missing_at_b_ids: FrozenSet[str] = digest_a - digest_b
+        result.bytes_sent += len(digest_b) * self.digest_size_bytes
+        result.steps_completed += 1
+
+        # --- Step 3: delta request (A -> B for missing at A; B -> A for missing at B) ---
+        # In practice, both directions are requested simultaneously.
+        # We serialize the exchange for clarity.
+        result.steps_completed += 1
+
+        # --- Step 4: delta batch (B -> A) ---
+        deltas_for_a: List[Delta] = [
+            crdt_b.replica.admitted[did]
+            for did in missing_at_a_ids
+        ]
+        # And (A -> B)
+        deltas_for_b: List[Delta] = [
+            crdt_a.replica.admitted[did]
+            for did in missing_at_b_ids
+        ]
+        result.bytes_sent += _estimate_bytes(deltas_for_a) + _estimate_bytes(deltas_for_b)
+        result.deltas_b_to_a = len(deltas_for_a)
+        result.deltas_a_to_b = len(deltas_for_b)
+        result.steps_completed += 1
+
+        # --- Step 5a: A receives deltas from B, verifies, joins ---
+        for delta in deltas_for_a:
+            verdict = self.admit_fn(delta, crdt_a)
+            result.admitted_at_a.append(verdict)
+            if verdict.accepted:
+                crdt_a.apply(delta)
+
+        # --- Step 5b: B receives deltas from A, verifies, joins ---
+        for delta in deltas_for_b:
+            verdict = self.admit_fn(delta, crdt_b)
+            result.admitted_at_b.append(verdict)
+            if verdict.accepted:
+                crdt_b.apply(delta)
+
+        result.steps_completed += 1
+
+        return result
+
+    # -------------------------------------------------------------------------
+    # Multi-peer round
+    # -------------------------------------------------------------------------
+
+    def gossip_round(
+        self,
+        crdt: DeltaStateCRDT,
+        peers: Dict[str, DeltaStateCRDT],
+        fanout: int,
+        rng: Optional[random.Random] = None,
+    ) -> List[ExchangeResult]:
+        """
+        Run one gossip round from `crdt` to `fanout` random peers.
+
+        Args:
+            crdt:    The local replica initiating the round.
+            peers:   Map from peer id -> peer's DeltaStateCRDT.
+            fanout:  Number of peers to contact (k in the paper).
+            rng:     Optional random.Random for reproducibility.
+
+        Returns:
+            List of ExchangeResult (one per contacted peer).
+        """
+        if fanout <= 0 or not peers:
+            return []
+
+        rng = rng or random.Random()
+        peer_ids = sorted(peers.keys())
+        k = min(fanout, len(peer_ids))
+        selected = rng.sample(peer_ids, k)
+
+        results = []
+        for peer_id in selected:
+            result = self.exchange(crdt, peers[peer_id])
+            results.append(result)
+        return results
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+def _estimate_bytes(deltas: List[Delta]) -> int:
+    """
+    Rough estimate of serialized delta size (informational only).
+
+    Actual serialization is done by `models.serialize_delta`, but for
+    the exchange-result accounting we use a simple heuristic:
+    ~32 bytes for the hash + ~64 bytes for the body + overhead.
+    """
+    return len(deltas) * 96
+
+
+def build_exchange_trace(result: ExchangeResult) -> List[GossipMessage]:
+    """
+    Reconstruct an ordered message trace from an ExchangeResult.
+
+    Useful for logging and for testing. The trace is a simplified
+    reconstruction — it does not carry the actual delta payloads.
+    """
+    trace: List[GossipMessage] = [
+        GossipMessage(
+            step=GossipStep.INITIATOR_DIGEST,
+            sender=result.peer_a,
+            payload={"digest_from": result.peer_a},
+        ),
+        GossipMessage(
+            step=GossipStep.RESPONDER_DIGEST_AND_DIFF,
+            sender=result.peer_b,
+            payload={"digest_from": result.peer_b, "missing_at_a": result.deltas_b_to_a},
+        ),
+        GossipMessage(
+            step=GossipStep.DELTA_REQUEST,
+            sender=result.peer_a,
+            payload={"requested": result.deltas_b_to_a},
+        ),
+        GossipMessage(
+            step=GossipStep.DELTA_BATCH,
+            sender=result.peer_b,
+            payload={"count": result.deltas_b_to_a},
+        ),
+        GossipMessage(
+            step=GossipStep.VERIFY_AND_JOIN,
+            sender=result.peer_a,
+            payload={"admitted": sum(1 for v in result.admitted_at_a if v.accepted)},
+        ),
+    ]
+    return trace