aethermesh 2.0.0__py3-none-any.whl

aethermesh/bft/semantic_matrix.py

@@ -0,0 +1,154 @@
+"""
+AetherMesh — Semantic compatibility matrix (Pillar 3, Section 3.3.3).
+
+A compatibility matrix C assigns to each pair of operation kinds a
+verdict on whether concurrent deltas of those kinds that touch
+overlapping targets may coexist.
+
+The matrix is evaluated locally and cheaply, which is what makes the
+admission layer lightweight. It is also coarse: it classifies operation
+kinds, not program behaviour, and it cannot detect semantic breakage
+that depends on program meaning.
+
+This module provides:
+
+    - SemanticVerdict:    enum (ok, resolve, conflict)
+    - CompatibilityMatrix:  the matrix itself
+    - DEFAULT_MATRIX:     the illustrative matrix from Table 3.1
+
+Reference:
+    Baladi, S. (2026). AetherMesh v1.0.0. Section 3.3.3 and Table 3.1.
+    Zenodo. https://doi.org/10.5281/zenodo.24038038
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, FrozenSet, Optional, Tuple
+
+from aethermesh.models import DeltaKind
+
+
+# =============================================================================
+# SemanticVerdict
+# =============================================================================
+
+class SemanticVerdict(str, Enum):
+    """The three possible verdicts of the semantic compatibility matrix."""
+    OK = "ok"
+    RESOLVE = "resolve"    # deterministic resolution required
+    CONFLICT = "conflict"  # reject or quarantine
+
+
+# =============================================================================
+# CompatibilityMatrix
+# =============================================================================
+
+@dataclass
+class CompatibilityMatrix:
+    """
+    A compatibility matrix over operation kinds.
+
+    The matrix is symmetric: C[a][b] == C[b][a] for all a, b.
+
+    Reference: Table 3.1 of the paper.
+    """
+    entries: Dict[Tuple[DeltaKind, DeltaKind], SemanticVerdict] = field(
+        default_factory=dict
+    )
+
+    def set(
+        self,
+        a: DeltaKind,
+        b: DeltaKind,
+        verdict: SemanticVerdict,
+    ) -> None:
+        """Set a matrix entry (both directions)."""
+        self.entries[(a, b)] = verdict
+        self.entries[(b, a)] = verdict
+
+    def get(
+        self,
+        a: DeltaKind,
+        b: DeltaKind,
+    ) -> SemanticVerdict:
+        """
+        Get the verdict for a pair of kinds. Defaults to OK if unset.
+        """
+        return self.entries.get((a, b), SemanticVerdict.OK)
+
+    def check(self, deltas: list) -> Tuple[SemanticVerdict, str]:
+        """
+        Check a set of deltas for semantic compatibility.
+
+        Returns the worst verdict among all pairs:
+            - If any pair is CONFLICT, returns CONFLICT.
+            - Else if any pair is RESOLVE, returns RESOLVE.
+            - Else returns OK.
+
+        The reason string lists the conflicting pair (if any).
+        """
+        worst = SemanticVerdict.OK
+        worst_pair: Optional[Tuple[str, str]] = None
+
+        for i, d_i in enumerate(deltas):
+            for d_j in deltas[i + 1:]:
+                v = self.get(d_i.kind, d_j.kind)
+                if v == SemanticVerdict.CONFLICT:
+                    if worst != SemanticVerdict.CONFLICT:
+                        worst = SemanticVerdict.CONFLICT
+                        worst_pair = (d_i.kind.value, d_j.kind.value)
+                elif v == SemanticVerdict.RESOLVE:
+                    if worst == SemanticVerdict.OK:
+                        worst = SemanticVerdict.RESOLVE
+                        worst_pair = (d_i.kind.value, d_j.kind.value)
+
+        if worst == SemanticVerdict.OK:
+            return worst, "ok"
+        if worst_pair:
+            return worst, f"{worst.value}: {worst_pair[0]} vs {worst_pair[1]}"
+        return worst, worst.value
+
+
+# =============================================================================
+# Default matrix (Table 3.1 of the paper)
+# =============================================================================
+
+def _build_default_matrix() -> CompatibilityMatrix:
+    """Build the illustrative matrix from Table 3.1 of the paper."""
+    m = CompatibilityMatrix()
+    OK = SemanticVerdict.OK
+    RESOLVE = SemanticVerdict.RESOLVE
+    CONFLICT = SemanticVerdict.CONFLICT
+
+    # Edit body
+    m.set(DeltaKind.EDIT_BODY, DeltaKind.EDIT_BODY, OK)
+    m.set(DeltaKind.EDIT_BODY, DeltaKind.RENAME_SYMBOL, OK)
+    m.set(DeltaKind.EDIT_BODY, DeltaKind.DELETE_SYMBOL, CONFLICT)
+    m.set(DeltaKind.EDIT_BODY, DeltaKind.CHANGE_SIGNATURE, OK)
+    m.set(DeltaKind.EDIT_BODY, DeltaKind.EDIT_METADATA, OK)
+
+    # Rename symbol
+    m.set(DeltaKind.RENAME_SYMBOL, DeltaKind.RENAME_SYMBOL, RESOLVE)
+    m.set(DeltaKind.RENAME_SYMBOL, DeltaKind.DELETE_SYMBOL, CONFLICT)
+    m.set(DeltaKind.RENAME_SYMBOL, DeltaKind.CHANGE_SIGNATURE, CONFLICT)
+    m.set(DeltaKind.RENAME_SYMBOL, DeltaKind.EDIT_METADATA, OK)
+
+    # Delete symbol
+    m.set(DeltaKind.DELETE_SYMBOL, DeltaKind.DELETE_SYMBOL, OK)  # idempotent
+    m.set(DeltaKind.DELETE_SYMBOL, DeltaKind.CHANGE_SIGNATURE, CONFLICT)
+    m.set(DeltaKind.DELETE_SYMBOL, DeltaKind.EDIT_METADATA, OK)
+
+    # Change signature
+    m.set(DeltaKind.CHANGE_SIGNATURE, DeltaKind.CHANGE_SIGNATURE, RESOLVE)
+    m.set(DeltaKind.CHANGE_SIGNATURE, DeltaKind.EDIT_METADATA, OK)
+
+    # Edit metadata
+    m.set(DeltaKind.EDIT_METADATA, DeltaKind.EDIT_METADATA, RESOLVE)  # LWW
+
+    return m
+
+
+DEFAULT_MATRIX: CompatibilityMatrix = _build_default_matrix()
+"""The illustrative compatibility matrix from Table 3.1 of the paper."""

aethermesh/cli.py

@@ -0,0 +1,270 @@
+"""
+AetherMesh — Command-line interface.
+
+Provides three subcommands:
+
+    aethermesh simulate   Run a simulated P2P testbed and measure the
+                          three metrics from Section 5 of the paper.
+
+    aethermesh info       Print version, DOI, and record information.
+
+    aethermesh verify     Run a quick self-check (join laws, signature
+                          verification, admission pipeline) without
+                          a full simulation.
+
+Usage:
+    python -m aethermesh.cli simulate --nodes 50 --fanout 5
+    python -m aethermesh.cli info
+    python -m aethermesh.cli verify
+
+Reference:
+    Baladi, S. (2026). AetherMesh v1.0.0. Section 5.
+    Zenodo. https://doi.org/10.5281/zenodo.24038038
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Dict, List, Optional
+
+from aethermesh.__version__ import (
+    __version__,
+    __author__,
+    __email__,
+    __doi__,
+    __license__,
+    __paper_version__,
+    __record_id__,
+)
+
+
+# =============================================================================
+# Info
+# =============================================================================
+
+def cmd_info(args: argparse.Namespace) -> int:
+    """Print version, DOI, and record information."""
+    print("=" * 60)
+    print(f"AetherMesh v{__version__}")
+    print("=" * 60)
+    print(f"Author:          {__author__}")
+    print(f"Email:           {__email__}")
+    print(f"License:         {__license__}")
+    print(f"Paper version:   {__paper_version__}")
+    print(f"Record ID:       {__record_id__}")
+    print(f"DOI:             {__doi__}")
+    print(f"DOI URL:         https://doi.org/{__doi__}")
+    print()
+    print("AetherMesh is the decentralization layer of the Aether family:")
+    print("  AetherGit  (storage)          — 10.5281/zenodo.23966896")
+    print("  AetherFlow (integration)      — 10.5281/zenodo.23979129")
+    print("  AetherProof (verification)    — 10.5281/zenodo.24013124")
+    print("  AetherMesh (decentralization) — 10.5281/zenodo.24038038")
+    print()
+    print("Status: Reference implementation. Preliminary results.")
+    print("        Not a production system. No real-world deployment.")
+    print("=" * 60)
+    return 0
+
+
+# =============================================================================
+# Simulate
+# =============================================================================
+
+def cmd_simulate(args: argparse.Namespace) -> int:
+    """Run the full testbed and report all three metrics."""
+    from aethermesh.simulation.testbed import Testbed, TestbedConfig
+
+    print("=" * 60)
+    print(f"AetherMesh v{__version__} — simulated testbed")
+    print("=" * 60)
+    print(f"Nodes:     {args.nodes}")
+    print(f"Fanout:    {args.fanout}")
+    print(f"Rounds:    {args.max_rounds}")
+    print(f"Seed:      {args.seed}")
+    print()
+
+    config = TestbedConfig(
+        n_nodes=args.nodes,
+        fanout=args.fanout,
+        max_rounds=args.max_rounds,
+        seed=args.seed,
+    )
+
+    # Metric 1: convergence
+    print("[1/3] Convergence latency")
+    tb1 = Testbed(config)
+    m1 = tb1.measure_convergence_latency(initial_delta_count=1)
+    print(f"      Converged at time: {m1['converged_at_time']}")
+    print(f"      Converged at round: {m1['converged_at_round']}")
+    print(f"      Final fraction: {m1['final_fraction']:.2%}")
+    print()
+
+    # Metric 2: conflict overhead
+    print("[2/3] Conflict resolution overhead")
+    tb2 = Testbed(config)
+    m2 = tb2.measure_conflict_overhead(n_conflicting_deltas=10)
+    print(f"      Conflicts flagged: {m2['conflicts_flagged']}")
+    print(f"      Deadlocks: {m2['deadlocks']}")
+    print(f"      Throughput overhead: {m2['throughput_overhead_pct']}%")
+    print()
+
+    # Metric 3: fault resilience
+    print("[3/3] Fault resilience")
+    tb3 = Testbed(config)
+    m3 = tb3.measure_fault_resilience(n_malformed=args.n_malformed)
+    print(f"      Injected: {m3['injected']}")
+    print(f"      Blocked:  {m3['blocked']}")
+    print(f"      Block rate: {m3['block_rate']:.2%}")
+    print()
+
+    # Summary
+    results = {
+        "version": __version__,
+        "config": {
+            "nodes": args.nodes,
+            "fanout": args.fanout,
+            "max_rounds": args.max_rounds,
+            "seed": args.seed,
+        },
+        "metric_1_convergence": m1,
+        "metric_2_conflict_overhead": m2,
+        "metric_3_fault_resilience": m3,
+    }
+
+    if args.output:
+        with open(args.output, "w") as f:
+            json.dump(results, f, indent=2)
+        print(f"Results written to {args.output}")
+    else:
+        print(json.dumps(results, indent=2))
+
+    return 0
+
+
+# =============================================================================
+# Verify
+# =============================================================================
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    """Run a self-check without a full simulation."""
+    print("=" * 60)
+    print(f"AetherMesh v{__version__} — self-check")
+    print("=" * 60)
+
+    ok = True
+
+    # 1. Join laws on the Figure 4 example
+    print("[1/4] Join laws (Figure 4 example)")
+    from aethermesh.crdt.semilattice import build_figure4_example, verify_join_laws
+    lattice, elements = build_figure4_example()
+    laws_ok, violations = verify_join_laws(lattice, elements)
+    if laws_ok:
+        print(f"      ✅ 7 elements, all 3 laws hold")
+    else:
+        print(f"      ❌ {len(violations)} violations")
+        ok = False
+
+    # 2. Signature verification
+    print("[2/4] Ed25519 signature verification")
+    from aethermesh.bft import generate_keypair, sign_delta, verify_delta_signature
+    from aethermesh.models import Delta, DeltaKind
+    priv, pub = generate_keypair()
+    d = Delta.create(body={"op": "test"}, origin="test-agent", kind=DeltaKind.EDIT_BODY)
+    d_signed = sign_delta(d, priv, "key-1")
+    sig_ok = verify_delta_signature(d_signed, pub)
+    if sig_ok:
+        print(f"      ✅ Valid signature verified")
+    else:
+        print(f"      ❌ Signature verification failed")
+        ok = False
+
+    # 3. Admission pipeline
+    print("[3/4] Admission pipeline")
+    from aethermesh.bft import KeyRegistry
+    from aethermesh.admission.pipeline import AdmissionPipeline
+    from aethermesh.crdt.delta_state import DeltaStateCRDT
+    registry = KeyRegistry()
+    registry.register("test-agent", "key-1", pub)
+    pipeline = AdmissionPipeline(registry=registry)
+    crdt = DeltaStateCRDT(origin="test")
+    verdict = pipeline.admit(d_signed, crdt.replica)
+    if verdict.accepted:
+        print(f"      ✅ Valid delta accepted")
+    else:
+        print(f"      ❌ Valid delta rejected: {verdict.reason}")
+        ok = False
+
+    # 4. Reject unsigned
+    d_unsigned = Delta.create(body={"op": "test2"}, origin="test-agent", kind=DeltaKind.EDIT_BODY)
+    verdict2 = pipeline.admit(d_unsigned, crdt.replica)
+    if verdict2.verdict.value == "reject":
+        print(f"      ✅ Unsigned delta rejected")
+    else:
+        print(f"      ❌ Unsigned delta not rejected: {verdict2.verdict.value}")
+        ok = False
+
+    print("[4/4] Summary")
+    if ok:
+        print("      ✅ All checks passed")
+        print("=" * 60)
+        return 0
+    else:
+        print("      ❌ Some checks failed")
+        print("=" * 60)
+        return 1
+
+
+# =============================================================================
+# Entry point
+# =============================================================================
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="aethermesh",
+        description=(
+            f"AetherMesh v{__version__} — decentralized P2P agent synchronization"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"aethermesh {__version__}",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # info
+    p_info = sub.add_parser("info", help="Print version, DOI, and record information")
+    p_info.set_defaults(func=cmd_info)
+
+    # verify
+    p_verify = sub.add_parser("verify", help="Run a self-check (no simulation)")
+    p_verify.set_defaults(func=cmd_verify)
+
+    # simulate
+    p_sim = sub.add_parser("simulate", help="Run the full simulated testbed")
+    p_sim.add_argument("--nodes", type=int, default=50, help="Number of nodes (default: 50)")
+    p_sim.add_argument("--fanout", type=int, default=5, help="Gossip fanout (default: 5)")
+    p_sim.add_argument("--max-rounds", type=int, default=200, help="Max gossip rounds (default: 200)")
+    p_sim.add_argument("--seed", type=int, default=42, help="Random seed (default: 42)")
+    p_sim.add_argument("--n-malformed", type=int, default=100, help="Malformed deltas to inject (default: 100)")
+    p_sim.add_argument("--output", type=str, default=None, help="Write results JSON to this file")
+    p_sim.set_defaults(func=cmd_simulate)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Main entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aethermesh/crdt/__init__.py

@@ -0,0 +1,17 @@
+"""AetherMesh — CRDT module (Pillar 1)."""
+
+from aethermesh.crdt.semilattice import (
+    JoinSemilattice,
+    DeltaSetLattice,
+    JoinLawError,
+    verify_join_laws,
+)
+from aethermesh.crdt.delta_state import DeltaStateCRDT
+
+__all__ = [
+    "JoinSemilattice",
+    "DeltaSetLattice",
+    "JoinLawError",
+    "verify_join_laws",
+    "DeltaStateCRDT",
+]

aethermesh/crdt/delta_state.py

@@ -0,0 +1,195 @@
+"""
+AetherMesh — Delta-state CRDT (Pillar 1).
+
+Implements delta-state replication (Section 3.1.3 of the paper).
+
+AetherMesh uses delta-state replication as its default: nodes ship
+deltas that are themselves lattice elements, so duplication and
+reordering remain harmless, and fall back to full-state exchange only
+when a digest comparison indicates that incremental repair would cost
+more than a state transfer.
+
+This module provides:
+
+    - DeltaStateCRDT:  the main CRDT class, operating on a Replica
+
+Reference:
+    Baladi, S. (2026). AetherMesh v1.0.0. Sections 3.1.1 and 3.1.3.
+    Zenodo. https://doi.org/10.5281/zenodo.24038038
+"""
+
+from __future__ import annotations
+
+from typing import Dict, FrozenSet, Iterable, List, Optional, Set, Tuple
+
+from aethermesh.models import Delta, Replica
+from aethermesh.crdt.semilattice import DeltaSetLattice
+
+
+class DeltaStateCRDT:
+    """
+    A delta-state CRDT over a `Replica`.
+
+    The CRDT wraps a `Replica` (which holds the admitted delta set)
+    and provides delta-based operations:
+
+        - apply(delta):        join a single delta (idempotent)
+        - apply_many(deltas):  join multiple deltas
+        - merge(other):        join another CRDT's replica
+        - delta_since(digest): the deltas the peer is missing
+        - digest():            compact summary of local state
+        - full_state():        the entire admitted set (fallback)
+
+    The delta set lattice is the grow-only-set CRDT lifted to deltas
+    (Section 3.1.1), with set union as join.
+    """
+
+    def __init__(self, origin: str = "anonymous"):
+        self.replica = Replica(origin=origin)
+        self._lattice = DeltaSetLattice()
+
+    # -------------------------------------------------------------------------
+    # Core operations
+    # -------------------------------------------------------------------------
+
+    def apply(self, delta: Delta) -> bool:
+        """
+        Join a single delta into the local replica.
+
+        Returns True if the delta was newly admitted, False if it was
+        already present (idempotence) or deferred (missing parents).
+
+        A delta with missing parents is deferred (Section 3.3.2) — it is
+        not rejected.
+        """
+        if delta.id in self.replica:
+            return False
+
+        if not self.replica.has_parents(delta):
+            self.replica.deferred[delta.id] = delta
+            return False
+
+        self.replica.join(delta)
+        self._try_drain_deferred()
+        return True
+
+    def apply_many(self, deltas: Iterable[Delta]) -> int:
+        """Apply multiple deltas. Returns the count of newly admitted."""
+        count = 0
+        for d in deltas:
+            if self.apply(d):
+                count += 1
+        return count
+
+    def merge(self, other: "DeltaStateCRDT") -> int:
+        """
+        Merge another CRDT's replica into this one (set union).
+
+        Returns the count of newly admitted deltas.
+        """
+        count = 0
+        for did in other.replica.ids() - self.replica.ids():
+            delta = other.replica.admitted[did]
+            if self.apply(delta):
+                count += 1
+        return count
+
+    # -------------------------------------------------------------------------
+    # Delta exchange (Section 3.2.1)
+    # -------------------------------------------------------------------------
+
+    def digest(self) -> FrozenSet[str]:
+        """
+        A compact summary of local state: the set of admitted delta ids.
+
+        In production, this would be compressed into a version vector,
+        Merkle tree, or Bloom filter (Section 3.2.1). For the reference
+        implementation we use the raw id set, which is exact.
+        """
+        return self.replica.ids()
+
+    def delta_since(self, peer_digest: FrozenSet[str]) -> List[Delta]:
+        """
+        The deltas this replica has that the peer does not.
+
+        Used in step 2 of the anti-entropy exchange (Figure 5): the
+        responder returns "digest + list of deltas A appears to lack".
+        """
+        missing = self.replica.ids() - peer_digest
+        return [self.replica.admitted[did] for did in missing]
+
+    def full_state(self) -> List[Delta]:
+        """
+        The entire admitted set (state-based fallback).
+
+        Used when a digest comparison indicates that incremental repair
+        would cost more than a state transfer (Section 3.1.3).
+        """
+        return list(self.replica.admitted.values())
+
+    # -------------------------------------------------------------------------
+    # Deferred deltas (Section 3.3.2)
+    # -------------------------------------------------------------------------
+
+    def _try_drain_deferred(self) -> None:
+        """
+        Retry deferred deltas whose parents may now be present.
+
+        Called after each successful join.
+        """
+        progress = True
+        while progress:
+            progress = False
+            ready = [
+                d for d in self.replica.deferred.values()
+                if self.replica.has_parents(d)
+            ]
+            for d in ready:
+                del self.replica.deferred[d.id]
+                self.replica.join(d)
+                progress = True
+
+    def deferred_count(self) -> int:
+        """Number of deltas currently deferred (missing parents)."""
+        return len(self.replica.deferred)
+
+    # -------------------------------------------------------------------------
+    # Materialization
+    # -------------------------------------------------------------------------
+
+    def materialize(self) -> List[Delta]:
+        """Deterministic linearization of the admitted delta set."""
+        return self.replica.materialize()
+
+    # -------------------------------------------------------------------------
+    # Introspection
+    # -------------------------------------------------------------------------
+
+    def __len__(self) -> int:
+        return len(self.replica)
+
+    def __contains__(self, delta_id: str) -> bool:
+        return delta_id in self.replica
+
+    def ids(self) -> FrozenSet[str]:
+        return self.replica.ids()
+
+    def state_size(self) -> int:
+        """Number of admitted deltas."""
+        return len(self.replica)
+
+
+# =============================================================================
+# Sanity check on the join laws (Figure 4 example)
+# =============================================================================
+
+if __name__ == "__main__":
+    from aethermesh.crdt.semilattice import build_figure4_example, verify_join_laws
+
+    lattice, elements = build_figure4_example()
+    ok, violations = verify_join_laws(lattice, elements)
+    print(f"Lattice elements: {len(elements)}")
+    print(f"Join laws hold: {ok}")
+    if violations:
+        for v in violations[:5]:
+            print(f"  - {v}")