extodan-agentsync 0.1.0__py3-none-any.whl

agentsync/__init__.py

@@ -0,0 +1,17 @@
+"""Agent-State Sync Engine — benchmark-first.
+
+The thesis under test: for multi-agent MERGEABLE shared state (notes, context,
+structured docs), an event-graph CRDT (eg-walker family, here via Loro) gives
+deterministic coordinator-free convergence with full write attribution at
+ZERO model calls — beating naive last-write-wins (silent corruption) and
+LLM-mediated transactional control (costs inference per conflict).
+
+The benchmark is the product. See README for the thesis, build order, and
+results.
+"""
+
+__version__ = "0.0.1"
+
+from .store import SyncedStore
+
+__all__ = ["SyncedStore"]

agentsync/__main__.py

@@ -0,0 +1,55 @@
+"""`python -m agentsync` / `make bench` entry point.
+
+Runs every available strategy against every available workload, prints the
+comparison table, and exits nonzero if any row FAILED its expectation — so the
+benchmark doubles as a regression gate: a strategy that regresses (e.g. CRDT
+suddenly loses a write, or LWW stops reproducing the known corruption) fails
+the run.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .harness import run_one
+from .strategies import make_strategy
+from .table import render_json, render_table
+from .workloads import all_workloads
+
+
+# Which strategies to run. crdt/transactional are added in later build steps;
+# until then the harness runs cleanly with just lww and reports the first
+# number, per the FIRST STEP directive.
+_AVAILABLE_STRATEGIES = ["lww", "transactional", "crdt"]
+
+
+def main() -> int:
+    workloads = all_workloads()
+    results = []
+    for wl in workloads:
+        for strat in _AVAILABLE_STRATEGIES:
+            results.append(run_one(strat, wl, make_strategy))
+
+    print()
+    print(render_table(results))
+    print()
+
+    # Interpretation note: a row's FAIL verdict is a property of the STRATEGY,
+    # not the harness. LWW is *supposed* to fail these workloads — that failure
+    # is the corruption the thesis is built to eliminate. So the only thing
+    # that makes the benchmark itself fail is if a strategy we EXPECT to pass
+    # (crdt on both; transactional on both) regresses. For step 1, only lww is
+    # wired up and its failures are expected, so the run is a success.
+    expected_pass = {"crdt", "transactional"}
+    regressions = [
+        r for r in results if r.strategy in expected_pass and r.verdict == "FAIL"
+    ]
+    if regressions:
+        print(f"⚠  {len(regressions)} expected-pass strategy regressed — see notes.")
+        return 1
+    print("✓ benchmark complete; LWW failures above are the demonstrated baseline.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agentsync/demo/langgraph_demo.py

@@ -0,0 +1,232 @@
+"""LangGraph demo — the asset to send, not plumbing to polish.
+
+The 60-second pitch: watch LWW silently corrupt an agent's shared state, then
+watch CRDT not. The SAME two-agent graph runs twice — once with an LWW store
+backend, once with a CRDT store backend — and the demo prints exactly what each
+agent wrote, what survived the merge, and (for CRDT) what got escalated.
+
+Why each agent writes to its OWN replica then syncs (rather than both writing
+one shared dict): that's how real multi-agent shared memory actually works.
+Each subagent edits a local copy of the context and the sync layer reconciles.
+langgraph 1.x raises ``InvalidUpdateError`` if two parallel nodes write the same
+state key with no reducer — so we bypass state for the shared memory itself and
+use the graph purely to model the *concurrency* (two agents acting at once),
+which is the honest mapping.
+
+Demo runs two scenarios back to back:
+
+* ``clean_merge``  — both agents add distinct findings to shared notes/tags.
+  LWW drops one agent's findings; CRDT keeps both. Convergence-without-loss.
+* ``conflict``     — both agents set the same scalar to different values.
+  LWW silently picks one; CRDT escalates with both contenders attributed.
+
+The point is visual: same agents, same writes, opposite outcomes by backend.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from langgraph.graph import END, START, StateGraph
+from typing_extensions import TypedDict
+
+from ..models import FieldKind, MergeStrategy, Write
+from ..strategies import make_strategy
+
+
+class GraphState(TypedDict):
+    """Per-agent scratch passed through the graph. The shared memory itself
+    lives in the Store (one replica per agent), NOT in graph state — otherwise
+    langgraph's reducer guard would intercept the very concurrency we want to
+    measure."""
+    agent_id: str
+
+
+@dataclass
+class StoreHandle:
+    """One agent's handle onto shared memory: its own replica + an op counter.
+
+    The agent writes locally (its replica is isolated from the other agent's),
+    then the harness syncs replicas. This mirrors each subagent holding a local
+    copy of shared context and the sync engine reconciling after.
+    """
+
+    agent_id: str
+    replica: MergeStrategy
+    _op: int = 0
+
+    def write(self, field: str, value, kind: FieldKind = FieldKind.scalar) -> None:
+        self.replica.apply(
+            Write(
+                agent_id=self.agent_id,
+                op_id=self._op,
+                field=field,
+                value=value,
+                kind=kind,
+            )
+        )
+        self._op += 1
+
+
+def _agent_node(agent_id: str, field: str, value, kind: FieldKind):
+    """Build a node fn that writes one contribution to THIS agent's replica.
+
+    The agent_id is bound into the closure at construction (not read from graph
+    state, which is shared across the whole graph). Returns an empty state
+    update because the real payload lives in the replica, not in graph state.
+    """
+
+    def node(state: GraphState) -> dict:
+        handle = _HANDLES[agent_id]
+        handle.write(field, value, kind)
+        return {}
+
+    return node
+
+
+# Module-level registry so node closures can find their handle without it being
+# serializable graph state. Reset per-run by _run_scenario.
+_HANDLES: dict[str, StoreHandle] = {}
+
+
+def _make_handles(strategy_name: str, agent_ids: list[str]) -> None:
+    _HANDLES.clear()
+    for aid in agent_ids:
+        _HANDLES[aid] = StoreHandle(agent_id=aid, replica=make_strategy(strategy_name))
+
+
+def _run_scenario(strategy_name: str, agent_work: dict[str, list[tuple]]) -> dict:
+    """Run one backend through the graph. Returns what each agent wrote and the
+    merged result.
+
+    ``agent_work`` maps agent_id -> list of (field, value, kind) writes. All
+    agents run as parallel branches off START (concurrent), then a sync step
+    merges every replica into every other (full mesh) and we read out.
+    """
+    agent_ids = list(agent_work.keys())
+    _make_handles(strategy_name, agent_ids)
+
+    g = StateGraph(GraphState)
+    for aid in agent_ids:
+        # Each agent becomes its own branch off START. Multiple writes per
+        # agent chain into a linear sub-sequence ending at END.
+        prev = START
+        for i, (field, value, kind) in enumerate(agent_work[aid]):
+            node_name = f"{aid}_{i}"
+            g.add_node(node_name, _agent_node(aid, field, value, kind))
+            g.add_edge(prev, node_name)
+            prev = node_name
+        g.add_edge(prev, END)
+    compiled = g.compile()
+
+    # Fan out: START feeds every agent's first node. We invoke with each agent
+    # id present so nodes can route to their handle.
+    compiled.invoke({"agent_id": agent_ids[0]})
+
+    # Phase 2 — sync. Full-mesh merge of replicas (each imports every other).
+    handles = [_HANDLES[aid] for aid in agent_ids]
+    for h in handles:
+        for other in handles:
+            if other is h:
+                continue
+            h.replica.import_state(other.replica.export_state())
+
+    final = handles[0].replica.finalized_state()
+    escalations = []
+    drain = getattr(handles[0].replica, "_escalations", None)
+    if drain:
+        for esc in drain:
+            escalations.append(
+                {
+                    "field": esc.field,
+                    "contenders": [
+                        {"agent": c.agent_id, "op": c.op_id, "value": c.value}
+                        for c in esc.contenders
+                    ],
+                }
+            )
+    return {"final_state": final, "escalations": escalations, "strategy": strategy_name}
+
+
+# ---------------------------------------------------------------------------
+# The two scenarios. Mirrored from the benchmark workloads so the demo and the
+# table tell the same story.
+# ---------------------------------------------------------------------------
+
+_CLEAN_MERGE = {
+    "researcher": [
+        ("project", "AgentSync", FieldKind.scalar),
+        ("findings", "found 3 CRDT papers", FieldKind.append_text),
+        ("tags", {"crdt", "agents"}, FieldKind.grow_set),
+    ],
+    "writer": [
+        ("findings", "drafted intro section", FieldKind.append_text),
+        ("tags", {"benchmark"}, FieldKind.grow_set),
+    ],
+}
+
+_CONFLICT = {
+    "researcher": [("status", "draft", FieldKind.scalar)],
+    "writer": [("status", "published", FieldKind.scalar)],
+}
+
+
+def _expected_clean() -> set:
+    return {"crdt", "agents", "benchmark"}
+
+
+def main() -> int:
+    print()
+    print("=" * 72)
+    print("AGENTSYNC LANGGRAPH DEMO — same graph, two shared-memory backends")
+    print("=" * 72)
+
+    for label, work, strategy_pair in [
+        ("SCENARIO 1 — clean merge (mergeable concurrent writes)", _CLEAN_MERGE, ("lww", "crdt")),
+        ("SCENARIO 2 — semantic conflict (same scalar, different values)", _CONFLICT, ("lww", "crdt")),
+    ]:
+        print()
+        print("-" * 72)
+        print(label)
+        print("-" * 72)
+        what = {}
+        for aid, writes in work.items():
+            what[aid] = [(f, v) for f, v, _ in writes]
+            print(f"  {aid} writes: {what[aid]}")
+
+        for strat in strategy_pair:
+            res = _run_scenario(strat, work)
+            print(f"\n  [{strat}] merged state: {res['final_state']}")
+            if res["escalations"]:
+                print(f"  [{strat}] ESCALATED (flagged, not auto-resolved):")
+                for esc in res["escalations"]:
+                    print(f"      field={esc['field']!r} contenders={esc['contenders']}")
+            else:
+                print(f"  [{strat}] no escalations")
+
+    # Verdict line: make the corruption-vs-convergence contrast explicit.
+    print()
+    print("=" * 72)
+    print("VERDICT")
+    print("=" * 72)
+    lww_clean = _run_scenario("lww", _CLEAN_MERGE)
+    crdt_clean = _run_scenario("crdt", _CLEAN_MERGE)
+    lww_tags = set(lww_clean["final_state"].get("tags", []))
+    crdt_tags = set(crdt_clean["final_state"].get("tags", []))
+    expected = _expected_clean()
+    print(f"  clean merge — expected tags: {sorted(expected)}")
+    print(f"  LWW  kept tags: {sorted(lww_tags)}  -> {'OK' if lww_tags == expected else 'LOST ' + str(sorted(expected - lww_tags))}")
+    print(f"  CRDT kept tags: {sorted(crdt_tags)} -> {'OK' if crdt_tags == expected else 'LOST ' + str(sorted(expected - crdt_tags))}")
+
+    crdt_conflict = _run_scenario("crdt", _CONFLICT)
+    lww_conflict = _run_scenario("lww", _CONFLICT)
+    print(f"\n  semantic conflict on 'status':")
+    print(f"  LWW  -> status={lww_conflict['final_state'].get('status')!r}, escalated: {bool(lww_conflict['escalations'])}  (silently picked)")
+    print(f"  CRDT -> status={crdt_conflict['final_state'].get('status')!r}, escalated: {bool(crdt_conflict['escalations'])}  (flagged for review)")
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentsync/harness.py

@@ -0,0 +1,252 @@
+"""The three-way benchmark harness — the core deliverable.
+
+For each workload × strategy:
+
+1. Create one strategy replica per agent in the workload.
+2. Apply that agent's local writes to its own replica (the "concurrent" phase —
+   replicas never see each other here).
+3. Merge every replica into every other (full-mesh import/export), so each
+   replica ends up holding the union. This is the sync phase.
+4. Measure: convergence (all replicas identical?), writes lost vs. seen,
+   attribution completeness, model calls, wall-clock, peak memory.
+5. Score a PASS/FAIL verdict from the workload's expectation.
+
+Strategies are pluggable via :data:`STRATEGIES`; the harness never branches on
+strategy identity, so adding a fourth is a one-line registry change.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import asdict
+from typing import Callable
+
+try:
+    import psutil
+    _HAS_PSUTIL = True
+    _proc = psutil.Process()
+except ImportError:  # pragma: no cover - bench extra is optional
+    _HAS_PSUTIL = False
+    _proc = None  # type: ignore[assignment]
+
+from .models import EndState, FieldKind, MergeStrategy, RunResult, Workload
+from .strategies import make_strategy
+
+
+def _peak_mem_kb() -> float:
+    if _proc is None:
+        return float("nan")
+    # rss is resident set size of this process; the harness is single-process,
+    # so this captures the strategy's memory footprint directly.
+    return _proc.memory_info().rss / 1024.0
+
+
+def run_one(
+    strategy_name: str,
+    workload: Workload,
+    strategy_factory: Callable[[str], MergeStrategy] = make_strategy,
+) -> RunResult:
+    """Run ``workload`` through one strategy and return a measured result row.
+
+    Full-mesh merge: every replica imports every other replica's exported
+    state. With N replicas this is N*(N-1) imports; for our 2-agent MVP that's
+    a single swap, but the loop generalizes to larger agent counts without
+    touching measurement logic.
+    """
+    t0 = time.perf_counter()
+    mem_before = _peak_mem_kb()
+    notes: list[str] = []
+
+    replica_ids = list(workload.writes_by_replica.keys())
+    replicas: dict[str, MergeStrategy] = {
+        rid: strategy_factory(strategy_name) for rid in replica_ids
+    }
+
+    # Phase 1 — local concurrent edits (replicas are isolated).
+    for rid in replica_ids:
+        for write in workload.writes_by_replica[rid]:
+            replicas[rid].apply(write)
+
+    # Phase 2 — full-mesh sync: each replica pulls every other replica's state.
+    for rid in replica_ids:
+        for other in replica_ids:
+            if other == rid:
+                continue
+            replicas[rid].import_state(replicas[other].export_state())
+
+    states = {rid: r.finalized_state() for rid, r in replicas.items()}
+    metrics = {rid: r.metrics() for rid, r in replicas.items()}
+
+    latency_ms = (time.perf_counter() - t0) * 1000.0
+    peak_mem_kb = max(_peak_mem_kb(), mem_before)
+
+    converged = len({str(sorted(s.items())) for s in states.values()}) == 1
+
+    # --- Correctness scoring against the workload's expectation ---
+    sample_metrics = metrics[replica_ids[0]]
+    # writes_lost is measured structurally, NOT from per-apply counters: an
+    # apply always succeeds locally, so counting seen-applied would be 0 even
+    # when a merge later clobbers the write. Instead we ask, for every
+    # mergeable field, how many issued writes are reflected in the converged
+    # state. The difference is real loss — e.g. LWW keeps one agent's `tags`
+    # and silently overwrites the other's.
+    converged_state = states[replica_ids[0]]
+    writes_lost = _count_lost_writes(converged_state, workload)
+    escalations = getattr(sample_metrics, "escalations", 0)
+    # Attribution: every surviving write should trace to an agent. We check this
+    # structurally — a correct merge keeps one attribution per *write*, LWW
+    # keeps one per *field* (overwritten agents vanish).
+    attribution_complete = _check_attribution(
+        workload, replicas, sample_metrics
+    )
+
+    # Outcome — HOW the strategy reached its end state. Derived, not declared,
+    # because corruption is a measurement, not a self-report. Two rules, in
+    # priority order:
+    #   1. corrupted: a mergeable write that should have survived didn't, OR a
+    #      real semantic conflict existed and the strategy produced no signal
+    #      for it (LWW silently picks a winner). Either way intent was lost
+    #      with no escalation — the baseline failure mode.
+    #   2. otherwise: the strategy's declared mode for conflicts it actually
+    #      handled — resolved (spent a model call) or escalated (flagged).
+    #      On a clean merge with nothing lost, every strategy is auto_merged.
+    had_conflict = not workload.expectation.clean_merge
+    silent_on_conflict = had_conflict and escalations == 0
+    if writes_lost > 0 or silent_on_conflict:
+        outcome = EndState.corrupted
+    elif had_conflict:
+        outcome = getattr(
+            replicas[replica_ids[0]], "conflict_mode", EndState.escalated
+        )
+    else:
+        outcome = EndState.auto_merged
+
+    verdict, fail_notes = _score(
+        workload, converged, writes_lost, escalations, attribution_complete
+    )
+    notes.extend(fail_notes)
+
+    return RunResult(
+        strategy=strategy_name,
+        workload=workload.name,
+        converged=converged,
+        writes_lost=writes_lost,
+        attribution_complete=attribution_complete,
+        escalations=escalations,
+        model_calls=sample_metrics.model_calls,
+        latency_ms=latency_ms,
+        peak_mem_kb=peak_mem_kb,
+        outcome=outcome,
+        verdict=verdict,
+        notes=notes,
+    )
+
+
+def _count_lost_writes(converged_state: dict, workload: Workload) -> int:
+    """Count writes the strategy dropped, judged structurally from the merged state.
+
+    For mergeable fields (grow_set / append_text) the correct converged value
+    contains EVERY agent's contribution; each one missing is one lost write.
+    For scalars there's nothing to lose — only one value can hold, so a
+    conflict there is an escalation concern, not a "lost write". This mirrors
+    the thesis: mergeable state must not lose writes; semantic state must
+    escalate.
+    """
+    # Bucket writes by field so we know each field's expected contributions.
+    by_field: dict[str, list] = {}
+    for writes in workload.writes_by_replica.values():
+        for w in writes:
+            by_field.setdefault(w.field, []).append(w)
+
+    lost = 0
+    for field, writes in by_field.items():
+        kind = writes[0].kind
+        actual = converged_state.get(field)
+        if kind is FieldKind.grow_set:
+            expected = set()
+            for w in writes:
+                expected |= set(w.value)
+            actual_set = set(actual) if isinstance(actual, (list, tuple, set)) else set()
+            # Each distinct contribution missing from the union is a lost write.
+            lost += len(expected - actual_set)
+        elif kind is FieldKind.append_text:
+            expected_frags = [w.value for w in writes]
+            if actual is None:
+                lost += len(expected_frags)
+            else:
+                # Order is unspecified on concurrent append, so each fragment
+                # must simply appear somewhere in the merged text.
+                lost += sum(1 for frag in expected_frags if frag not in actual)
+        # scalar: no writes_lost accounting; conflicts are scored as escalations.
+    return lost
+
+
+def _check_attribution(
+    workload: Workload, replicas: dict[str, MergeStrategy], metrics
+) -> bool:
+    """Attribution is complete iff every distinct write that survives to the
+    merged state still carries an agent_id.
+
+    We approximate via the per-write attribution the strategy exposes (if any).
+    LWW exposes per-FIELD attribution only, so a field written by two agents
+    has one attribution for two writes → incomplete. CRDT exposes per-write.
+    """
+    # Count how many distinct (agent, op) writes the workload issued.
+    distinct_writes = set()
+    for writes in workload.writes_by_replica.values():
+        for w in writes:
+            distinct_writes.add((w.agent_id, w.op_id, w.field))
+
+    # Strategy-specific attribution introspection.
+    surviving = set()
+    for r in replicas.values():
+        attr_fn = getattr(r, "attribution", None)
+        if attr_fn is None:
+            continue
+        for key, meta in attr_fn().items():
+            surviving.add((meta["agent_id"], meta["op_id"], key))
+    if not surviving:
+        # Strategy exposes no per-write attribution at all — can't be complete.
+        return len(distinct_writes) == 0
+    return len(surviving) >= len(distinct_writes)
+
+
+def _score(
+    workload: Workload,
+    converged: bool,
+    writes_lost: int,
+    escalations: int,
+    attribution_complete: bool,
+) -> tuple[str, list[str]]:
+    """Turn raw metrics into a verdict using the workload's expectation."""
+    notes: list[str] = []
+    ok = True
+
+    if not converged:
+        ok = False
+        notes.append("replicas diverged (no convergence)")
+
+    exp = workload.expectation
+    if exp.all_writes_survive and writes_lost > 0:
+        ok = False
+        notes.append(f"lost {writes_lost} write(s) on a mergeable workload")
+
+    if exp.clean_merge and escalations > 0:
+        ok = False
+        notes.append(f"{escalations} spurious escalation(s) on a clean merge")
+
+    if exp.semantic_conflict_on and escalations < len(exp.semantic_conflict_on):
+        ok = False
+        notes.append(
+            f"expected escalation on {exp.semantic_conflict_on}, "
+            f"got {escalations}"
+        )
+
+    if exp.all_writes_survive and not attribution_complete:
+        ok = False
+        notes.append("attribution incomplete (a surviving write lost its agent)")
+
+    return ("PASS" if ok else "FAIL"), notes
+
+
+__all__ = ["run_one"]