cascade-mcp 0.1.0__py3-none-any.whl

cascade/__init__.py

@@ -0,0 +1,7 @@
+"""cascade — cascade-resolution routing router, MCP server, and simulator.
+
+Modules:
+    cascade_routing  core resolution router (WINNER/FORK/RECOMPUTE/OCC arms)
+    server           MCP stdio server wrapping the router as tools
+    cascade_sim      standalone regime simulator
+"""

cascade/cascade_routing.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+cascade_routing.py — pure OCC vs pure cascade vs per-field HYBRID.
+Fair head-to-head: forked/committed fields keep contending (no freeze), so
+conflict volumes are comparable across policies. Tracks BOTH costs:
+  recomputes    wasted expensive re-runs (OCC overpays these under churn)
+  silent_errors committed-but-actually-wrong values (cascade risks these)
+
+Each field has a TRUE tolerance (drift its answer can absorb). Hybrid routes
+zero-tolerance fields to OCC (safe) and tolerant fields to the semantic cascade
+with materiality = measured tolerance. tol_safety>1 models OVER-estimating it.
+fresh_loser_redo_prob models the assumption that a fresh loser re-runs anyway.
+"""
+from __future__ import annotations
+import math
+import random
+from dataclasses import dataclass
+from collections import Counter
+
+@dataclass
+class Field:
+    id: str; level: int; deps: list
+    rev: int = 0; value: float = 1.0
+    true_tol: float = 0.25; policy: str = "cascade"; materiality: float = 0.20
+
+@dataclass
+class Write:
+    tier: int; conf: float; read_rev: dict; read_val: dict
+
+@dataclass
+class Config:
+    n_levels: int = 3; fields_per_level: int = 6; deps_per_field: int = 3
+    conf_levels: tuple = (0.5, 0.7, 0.85, 0.95, 0.99)
+    rounds: int = 12000
+    source_write_prob: float = 0.25; contention_prob: float = 0.30
+    width: tuple = (2, 3); lag: int = 4; value_drift: float = 0.08
+    frac_zero_tol: float = 0.30; zero_tol: float = 0.01; gen_tol: float = 0.25
+    policy: str = "hybrid"; global_materiality: float = 0.20
+    route_threshold: float = 0.05; tol_safety: float = 1.0
+    # multiplicative log-normal noise on the per-field tolerance ESTIMATE.
+    # tol_safety is systematic bias; tol_est_noise is the honest "you measured
+    # it, but imperfectly" spread. At >0 the hybrid over-estimates on ~half its
+    # fields even with tol_safety=1 -> silent errors appear (the safety=1 zero
+    # is a perfect-knowledge artifact, not a property of the design).
+    tol_est_noise: float = 0.0
+    fresh_loser_redo_prob: float = 0.0; seed: int = 0
+
+def drift(w, F):
+    return max((abs(F[d].value/v0 - 1.0) if v0 else 0.0 for d, v0 in w.read_val.items()), default=0.0)
+def rev_stale(w, F):
+    return any(F[d].rev > s for d, s in w.read_rev.items())
+def bump(f, rng, cfg):
+    f.rev += 1; f.value *= (1.0 + rng.gauss(0.0, cfg.value_drift))
+
+def build(cfg, rng):
+    F, by = {}, []
+    for lvl in range(cfg.n_levels):
+        ids = [f"L{lvl}_{i}" for i in range(cfg.fields_per_level)]; by.append(ids)
+        for fid in ids:
+            deps = [] if lvl == 0 else rng.sample(
+                [x for p in by[:lvl] for x in p], min(cfg.deps_per_field, cfg.fields_per_level*lvl))
+            f = Field(fid, lvl, deps)
+            if lvl > 0:
+                f.true_tol = cfg.zero_tol if rng.random() < cfg.frac_zero_tol else cfg.gen_tol
+                measured = f.true_tol * cfg.tol_safety
+                if cfg.tol_est_noise > 0.0:
+                    measured *= math.exp(rng.gauss(0.0, cfg.tol_est_noise))
+                if cfg.policy == "occ": f.policy = "occ"
+                # occ_value: OCC decision rule (commit-any-fresh, all losers
+                # rerun, no fork/authority) on the VALUE predicate. Isolates the
+                # staleness-predicate win from the routing/arbitration win.
+                elif cfg.policy == "occ_value":
+                    f.policy, f.materiality = "occ_value", cfg.global_materiality
+                elif cfg.policy == "cascade": f.policy, f.materiality = "cascade", cfg.global_materiality
+                else:
+                    if measured < cfg.route_threshold: f.policy = "occ"
+                    else: f.policy, f.materiality = "cascade", measured
+            F[fid] = f
+    return F
+
+def resolve(f, grp, F, cfg, rng):
+    if f.policy == "occ":
+        fresh = [w for w in grp if not rev_stale(w, F)]
+        if fresh: return True, len(grp) - 1, 0, "OCC_COMMIT"
+        return False, len(grp), 0, "OCC_ALLABORT"
+    if f.policy == "occ_value":
+        # value predicate + OCC accounting: commit one fresh, ALL losers rerun
+        # (no free adoption), no fork/authority. Can leak, because a flat global
+        # materiality has no idea of this field's true tolerance.
+        fresh = [w for w in grp if drift(w, F) <= f.materiality]
+        if not fresh: return False, len(grp), 0, "OCC_ALLABORT"
+        silent = 1 if drift(fresh[0], F) > f.true_tol else 0
+        return True, len(grp) - 1, silent, "OCC_COMMIT"
+    m = f.materiality
+    fresh = [w for w in grp if drift(w, F) <= m]; n_stale = len(grp) - len(fresh)
+    if not fresh: return False, len(grp), 0, "RECOMPUTE"
+    redo = n_stale + sum(1 for _ in range(len(fresh) - 1) if rng.random() < cfg.fresh_loser_redo_prob)
+    bt = min(w.tier for w in fresh); top = [w for w in fresh if w.tier == bt]
+    if len(top) > 1:
+        bc = max(w.conf for w in top); top = [w for w in top if w.conf == bc]
+    if len(top) > 1: return True, redo, 0, "FORK"
+    silent = 1 if drift(top[0], F) > f.true_tol else 0
+    return True, redo, silent, "WINNER"
+
+def run(cfg):
+    rng = random.Random(cfg.seed); F = build(cfg, rng)
+    src = [f for f in F.values() if f.level == 0]; der = [f for f in F.values() if f.level > 0]
+    topo = sorted(F.values(), key=lambda f: f.level); pending, since, M = {}, {}, Counter()
+    for r in range(cfg.rounds):
+        for f in src:
+            if rng.random() < cfg.source_write_prob: bump(f, rng, cfg)
+        for f in der:
+            if f.id in pending: continue
+            if rng.random() < cfg.contention_prob:
+                grp = [Write(2, rng.choice(cfg.conf_levels),
+                             {d: F[d].rev for d in f.deps}, {d: F[d].value for d in f.deps})
+                       for _ in range(rng.randint(*cfg.width))]
+                pending[f.id] = grp; since[f.id] = r
+        for f in topo:
+            g = pending.get(f.id)
+            if g is None or r - since[f.id] < cfg.lag: continue
+            committed, redo, silent, arm = resolve(f, g, F, cfg, rng)
+            M["conflicts"] += 1; M["recomputes"] += redo; M["silent_errors"] += silent; M[arm] += 1
+            if committed: M["commits"] += 1; bump(f, rng, cfg)   # keeps contending; no freeze
+            del pending[f.id]; del since[f.id]
+    return M
+
+def rep(label, M):
+    c = M["conflicts"] or 1; cm = M["commits"] or 1
+    print(f"  {label:<28} {M['recomputes']/c:4.2f} recompute/conflict   "
+          f"{M['recomputes']/cm:5.2f} recompute/commit   "
+          f"silent_err {M['silent_errors']:>4}   conflicts {M['conflicts']:>6}")
+
+def main():
+    print("=" * 104)
+    print("POLICY HEAD-TO-HEAD (lag=4; 30% price-like tol~0.01, 70% estimate-like tol~0.25)")
+    print("=" * 104)
+    print("\n[10] pure OCC(rev)  vs  OCC(value)  vs  pure CASCADE(0.20)  vs  HYBRID(routed)")
+    rep("pure OCC (rev-staleness)", run(Config(policy="occ")))
+    rep("OCC (value-staleness 0.20)", run(Config(policy="occ_value", global_materiality=0.20)))
+    rep("pure CASCADE (global 0.20)", run(Config(policy="cascade", global_materiality=0.20)))
+    rep("HYBRID (measured tol)", run(Config(policy="hybrid")))
+    print("     OCC(value) vs OCC(rev): the throughput gain that is JUST the predicate,")
+    print("     not the routing. OCC(value) silent_err > 0: the predicate alone is unsafe.")
+
+    print("\n[10b] HYBRID under NOISY (imperfect) tolerance measurement, tol_safety=1")
+    print("     the safety=1 zero-leak is a perfect-knowledge artifact; noise leaks:")
+    for nz in (0.0, 0.5, 1.0):
+        rep(f"hybrid tol_est_noise={nz:.1f}", run(Config(policy="hybrid", tol_est_noise=nz)))
+
+    print("\n[11] survives the 'fresh loser adopts winner free' assumption being switched off?")
+    for p in (0.0, 0.5, 1.0):
+        rep(f"hybrid redo_prob={p:.1f}", run(Config(policy="hybrid", fresh_loser_redo_prob=p)))
+
+    print("\n[12] over-estimating tolerance: PURE CASCADE (bites hard) vs HYBRID (only cascade-routed fields)")
+    for s in (1.0, 2.0, 5.0):
+        rep(f"cascade tol_safety={s:.0f}", run(Config(policy="cascade", global_materiality=0.20 * s)))
+    for s in (1.0, 2.0, 5.0):
+        rep(f"hybrid  tol_safety={s:.0f}", run(Config(policy="hybrid", tol_safety=s)))
+    print("     Measure tolerance conservatively (safety<=1) -> silent_err stays 0.")
+    print("=" * 104)
+
+if __name__ == "__main__":
+    main()

cascade/cascade_sim.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+cascade_sim.py — go/no-go instrumentation for the read-set-validated,
+provenance-weighted resolution cascade (the "agent-mesh" thesis).
+
+It simulates concurrent agent writes over a configurable dependency DAG and
+classifies every conflict-resolution event into one of three arms:
+
+  FRESH_WINNER  a live (non-stale) write wins on authority->confidence.
+                Fully automatic, no re-run, no human. THIS is the value:
+                the case where you beat OCC (no retry) and CodeCRDT (no LLM).
+
+  FORK          two+ fresh writes tie on (authority, confidence). Lossless:
+                you defer to a human/high-tier agent instead of silently
+                dropping. Better than silent corruption, but not hands-off.
+
+  RECOMPUTE     every competing write is premise-stale (all-stale). There is
+                no correct value to pick -> you must re-run. Here you are NO
+                BETTER than S-Bus OCC. This arm is the thesis-eroder.
+
+Decision rule of thumb:
+  - high FRESH_WINNER across realistic churn      -> strong GO
+  - RECOMPUTE dominates once churn is realistic   -> "just use OCC", NO-GO
+  - FORK meaningful only if confidence is coarse  -> design implication
+
+The resolve() function below mirrors the Rust resolve_field() exactly:
+staleness gate -> authority tier -> confidence -> fork-on-tie.
+"""
+
+from __future__ import annotations
+import random
+from dataclasses import dataclass, field
+from collections import Counter
+from typing import Optional
+
+
+# ----------------------------- data model -----------------------------------
+
+@dataclass
+class Field:
+    id: str
+    level: int
+    deps: list[str]
+    rev: int = 0            # monotonic per-field revision, bumped on commit
+    value: float = 1.0      # semantic content; perturbed on every commit/churn
+    forked: bool = False
+
+
+@dataclass
+class Write:
+    field_id: str
+    agent_id: int
+    authority_tier: int     # lower = more authoritative (Tier 0 = human/verified)
+    confidence: float
+    read_set: dict[str, int]     # dep_id -> dep.rev observed at read time
+    read_vals: dict[str, float]  # dep_id -> dep.value observed at read time
+    issued_round: int
+
+
+# ----------------------------- config ----------------------------------------
+
+@dataclass
+class Config:
+    # DAG shape
+    n_levels: int = 3
+    fields_per_level: int = 6
+    deps_per_field: int = 3          # read-set size for derived fields
+
+    # agents / authority
+    n_agents: int = 8
+    # P(tier). Tier 0 = human/verified source, Tier 1 = analyst, Tier 2 = swarm.
+    tier_probs: tuple[float, float, float] = (0.0, 0.0, 1.0)  # homogeneous swarm
+
+    # confidence: a coarse discrete scale (realistic for LLM/scraper self-report).
+    # Set continuous=True to make exact ties vanish (fork arm collapses).
+    confidence_levels: tuple[float, ...] = (0.5, 0.7, 0.85, 0.95, 0.99)
+    continuous_confidence: bool = False
+
+    # dynamics
+    rounds: int = 4000
+    source_write_prob: float = 0.25  # P(a source field churns each round)
+    contention_prob: float = 0.30    # P(a derived field draws concurrent writes/round)
+    contention_width: tuple[int, int] = (2, 3)  # inclusive range of concurrent writers
+    resolution_lag: int = 1          # rounds between read and resolve (time pressure)
+
+    # --- staleness model ---------------------------------------------------
+    # rev-staleness (default): a write is stale iff ANY dependency's rev moved.
+    #   This is the harsh upper bound — it flags "HQ city updated" as
+    #   invalidating a revenue estimate that never touched the HQ field's value.
+    # semantic-staleness: a write is stale iff a dependency's VALUE moved past
+    #   `materiality` (relative). A rev can advance while the value drifts
+    #   below threshold -> the write survives. This is CoAgent's "did the
+    #   conflict actually invalidate my premise" test, made deterministic.
+    semantic_staleness: bool = False
+    materiality: float = 0.10        # relative value move that counts as stale
+    value_drift: float = 0.08        # std-dev of relative value move per event
+
+    seed: int = 0
+
+
+# ----------------------------- core resolve ----------------------------------
+# Mirrors Rust resolve_field(). Pure function of the competing writes + the
+# already-resolved upstream revs (resolution happens in topological order, so
+# every dependency is at its winning rev before this is called).
+
+FRESH_WINNER = "FRESH_WINNER"
+FORK = "FORK"
+RECOMPUTE = "RECOMPUTE"
+
+
+def is_stale(w: Write, fields: dict[str, Field], cfg: Config) -> bool:
+    if not cfg.semantic_staleness:
+        # rev-staleness: stale iff any dependency advanced past the recorded rev
+        return any(fields[dep].rev > seen for dep, seen in w.read_set.items())
+    # semantic-staleness: stale iff any dependency's VALUE moved past materiality
+    for dep, seen_val in w.read_vals.items():
+        now = fields[dep].value
+        base = abs(seen_val) or 1.0
+        if abs(now - seen_val) / base > cfg.materiality:
+            return True
+    return False
+
+
+def resolve(writes: list[Write], fields: dict[str, Field],
+            cfg: Config) -> tuple[str, Optional[Write]]:
+    fresh = [w for w in writes if not is_stale(w, fields, cfg)]
+
+    if len(fresh) == 0:
+        return RECOMPUTE, None
+    if len(fresh) == 1:
+        return FRESH_WINNER, fresh[0]
+
+    # authority: lowest tier number wins
+    best_tier = min(w.authority_tier for w in fresh)
+    top = [w for w in fresh if w.authority_tier == best_tier]
+    if len(top) == 1:
+        return FRESH_WINNER, top[0]
+
+    # confidence: highest wins
+    best_conf = max(w.confidence for w in top)
+    winners = [w for w in top if w.confidence == best_conf]
+    if len(winners) == 1:
+        return FRESH_WINNER, winners[0]
+
+    # exact tie on (authority, confidence) -> lossless fork
+    return FORK, None
+
+
+# ----------------------------- simulation ------------------------------------
+
+def build_dag(cfg: Config, rng: random.Random) -> dict[str, Field]:
+    fields: dict[str, Field] = {}
+    by_level: list[list[str]] = []
+    for lvl in range(cfg.n_levels):
+        ids = [f"L{lvl}_{i}" for i in range(cfg.fields_per_level)]
+        by_level.append(ids)
+        for fid in ids:
+            if lvl == 0:
+                deps: list[str] = []
+            else:
+                pool = [x for prev in by_level[:lvl] for x in prev]
+                k = min(cfg.deps_per_field, len(pool))
+                deps = rng.sample(pool, k)
+            fields[fid] = Field(id=fid, level=lvl, deps=deps)
+    return fields
+
+
+def draw_tier(cfg: Config, rng: random.Random) -> int:
+    r, acc = rng.random(), 0.0
+    for tier, p in enumerate(cfg.tier_probs):
+        acc += p
+        if r <= acc:
+            return tier
+    return len(cfg.tier_probs) - 1
+
+
+def draw_conf(cfg: Config, rng: random.Random) -> float:
+    if cfg.continuous_confidence:
+        return rng.random()
+    return rng.choice(cfg.confidence_levels)
+
+
+def perturb(f: Field, cfg: Config, rng: random.Random) -> None:
+    # a commit/churn moves the field's value by a random relative amount.
+    # some events move it a lot (material), some barely (immaterial) — which
+    # is exactly what semantic-staleness gets to distinguish and rev-staleness
+    # cannot. Multiplicative so value never hits 0 (read_vals stay well-defined).
+    f.value *= (1.0 + rng.gauss(0.0, cfg.value_drift))
+
+
+def run(cfg: Config) -> Counter:
+    rng = random.Random(cfg.seed)
+    fields = build_dag(cfg, rng)
+    sources = [f for f in fields.values() if f.level == 0]
+    derived = [f for f in fields.values() if f.level > 0]
+    topo = sorted(fields.values(), key=lambda f: f.level)
+
+    pending: dict[str, list[Write]] = {}   # field_id -> concurrent writes
+    pending_since: dict[str, int] = {}
+    arms: Counter = Counter()
+
+    for r in range(cfg.rounds):
+        # (a) source churn — single accepted write, bumps rev (not a conflict)
+        for f in sources:
+            if rng.random() < cfg.source_write_prob:
+                f.rev += 1
+                perturb(f, cfg, rng)
+
+        # (b) issue contention on derived fields not already contended
+        for f in derived:
+            if f.id in pending or f.forked:
+                continue
+            if rng.random() < cfg.contention_prob:
+                w = rng.randint(*cfg.contention_width)
+                writes = []
+                for _ in range(w):
+                    read_set = {d: fields[d].rev for d in f.deps}
+                    read_vals = {d: fields[d].value for d in f.deps}
+                    writes.append(Write(
+                        field_id=f.id,
+                        agent_id=rng.randrange(cfg.n_agents),
+                        authority_tier=draw_tier(cfg, rng),
+                        confidence=draw_conf(cfg, rng),
+                        read_set=read_set,
+                        read_vals=read_vals,
+                        issued_round=r,
+                    ))
+                pending[f.id] = writes
+                pending_since[f.id] = r
+
+        # (c) resolve matured groups in topological order (upstream first, so an
+        #     upstream commit this round can invalidate a downstream group)
+        for f in topo:
+            grp = pending.get(f.id)
+            if grp is None:
+                continue
+            if r - pending_since[f.id] < cfg.resolution_lag:
+                continue
+            arm, winner = resolve(grp, fields, cfg)
+            arms[arm] += 1
+            if arm == FRESH_WINNER:
+                f.rev += 1                      # commit winner, bump rev (cascades)
+                perturb(f, cfg, rng)            # ...and move value (may be immaterial)
+            elif arm == FORK:
+                f.rev += 1
+                perturb(f, cfg, rng)
+                f.forked = True                 # deferred; freeze for this run
+            # RECOMPUTE: nothing committed (losers would re-run)
+            del pending[f.id]
+            del pending_since[f.id]
+
+    return arms
+
+
+def summarize(arms: Counter) -> dict[str, float]:
+    total = sum(arms.values()) or 1
+    return {k: 100.0 * arms.get(k, 0) / total for k in (FRESH_WINNER, FORK, RECOMPUTE)}
+
+
+def pct_line(label: str, arms: Counter) -> str:
+    s = summarize(arms)
+    total = sum(arms.values())
+    return (f"{label:<28} "
+            f"winner {s[FRESH_WINNER]:5.1f}%   "
+            f"fork {s[FORK]:5.1f}%   "
+            f"recompute {s[RECOMPUTE]:5.1f}%   "
+            f"(n={total})")
+
+
+# ----------------------------- experiments -----------------------------------
+
+def main() -> None:
+    print("=" * 92)
+    print("CASCADE GO/NO-GO  —  resolution-arm distribution")
+    print("winner = automatic win (beats OCC+CodeCRDT) | fork = lossless defer | "
+          "recompute = no better than OCC")
+    print("=" * 92)
+
+    base = Config()
+    print("\n[1] BASELINE  (homogeneous Tier-2 swarm, coarse confidence, lag=1)")
+    print("    " + pct_line("baseline", run(base)))
+
+    print("\n[2] CHURN / TIME-PRESSURE SWEEP  (resolution_lag = rounds between read and resolve)")
+    print("    higher lag = more upstream churn lands in the read->resolve window")
+    for lag in (0, 1, 2, 4, 8):
+        cfg = Config(resolution_lag=lag)
+        print("    " + pct_line(f"lag={lag}", run(cfg)))
+
+    print("\n[3] SOURCE-CHURN SWEEP  (P a source field changes each round; lag=2)")
+    for p in (0.05, 0.15, 0.30, 0.50, 0.75):
+        cfg = Config(source_write_prob=p, resolution_lag=2)
+        print("    " + pct_line(f"source_write_prob={p:.2f}", run(cfg)))
+
+    print("\n[4] CONFIDENCE GRANULARITY  (does the FORK arm survive real-valued confidence?)")
+    print("    " + pct_line("coarse 5-level", run(Config())))
+    print("    " + pct_line("continuous float", run(Config(continuous_confidence=True)))
+          )
+
+    print("\n[5] AUTHORITY DIVERSITY  (homogeneous swarm vs. mixed tiers w/ occasional human)")
+    print("    " + pct_line("homogeneous (all Tier2)", run(Config(tier_probs=(0.0, 0.0, 1.0)))))
+    print("    " + pct_line("some analysts (T1/T2)", run(Config(tier_probs=(0.0, 0.35, 0.65)))))
+    print("    " + pct_line("rare human (T0/T1/T2)", run(Config(tier_probs=(0.1, 0.3, 0.6)))))
+
+    print("\n[6] DEPENDENCY WIDTH  (read-set size; more deps = more staleness surface, lag=2)")
+    for d in (1, 2, 4, 6):
+        cfg = Config(deps_per_field=d, resolution_lag=2)
+        print("    " + pct_line(f"deps_per_field={d}", run(cfg)))
+
+    print("\n[7] SEMANTIC STALENESS  (does 'value moved' beat 'rev moved'? the thesis test)")
+    print("    rev-staleness flags ANY upstream change; semantic clears immaterial ones.")
+    print("    -- materiality sweep (lag=4, where rev-staleness had 94% recompute) --")
+    print("    " + pct_line("rev-staleness (baseline)",
+                            run(Config(resolution_lag=4))))
+    for m in (0.05, 0.10, 0.20, 0.40):
+        cfg = Config(resolution_lag=4, semantic_staleness=True, materiality=m)
+        print("    " + pct_line(f"semantic  materiality={m:.2f}", run(cfg)))
+    print("    -- same lag sweep, semantic mode (compare to [2]) --")
+    for lag in (0, 1, 2, 4, 8):
+        cfg = Config(resolution_lag=lag, semantic_staleness=True, materiality=0.20)
+        print("    " + pct_line(f"semantic lag={lag}", run(cfg)))
+
+    print("\n" + "=" * 92)
+    print("Read the FRESH_WINNER column against your expected deployment churn.")
+    print("If winner stays high where your real churn lives  -> GO.")
+    print("If recompute swamps it there                      -> the DAG machinery")
+    print("buys little over plain OCC; ship OCC instead.")
+    print("=" * 92)
+
+
+if __name__ == "__main__":
+    main()

cascade/server.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+"""
+server.py — MCP server that wraps cascade_routing.py as a concurrency
+controller for AI agents. Two main tools:
+
+  read_state(fields, agent_id)
+      Returns current value+rev of the requested fields and secretly logs
+      them as that agent's read-set (the rev/value snapshot the agent saw).
+
+  propose_update(field, proposed_value, confidence, authority_tier,
+                 tolerance, agent_id, expected_writers)
+      Records the agent's proposed write against their logged read-set. When
+      the batch for `field` reaches `expected_writers`, runs the hybrid
+      resolve_field router (cr.resolve) on the whole batch, commits/bumps on
+      a winning arm, and returns the outcome. Earlier calls in the batch
+      return {"status": "pending"}; the final call returns the full result.
+
+A configure tool builds the dependency DAG with per-field tolerance/policy
+(mirrors cr.build). The resolver is called directly on cr.resolve/cr.bump so
+outcomes are identical to in-process simulation.
+
+The tool business logic lives in async *_impl functions so it can be unit-
+tested in-process without the stdio transport; the @mcp decorators are thin
+adapters that JSON-(de)serialize and call the impls.
+
+Run as a stdio MCP server:  python -m cascade.server
+"""
+from __future__ import annotations
+import json
+import math
+import os
+import random
+import sys
+from dataclasses import asdict, replace
+from typing import Any
+
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from cascade import cascade_routing as cr
+
+
+# ----------------------------- shared state ----------------------------------
+# Module-global so the stdio server and in-process tests share one engine.
+
+class CascadeState:
+    """Holds the field store, per-agent read-set log, and pending batches."""
+
+    def __init__(self) -> None:
+        self.fields: dict[str, cr.Field] = {}
+        # (agent_id, field_id_being_written) -> {dep_id: rev}
+        self.read_rev: dict[tuple[str, str], dict[str, int]] = {}
+        # (agent_id, field_id_being_written) -> {dep_id: value}
+        self.read_val: dict[tuple[str, str], dict[str, float]] = {}
+        self.pending: dict[str, list[cr.Write]] = {}
+        # regime-level config (set by configure)
+        self.tol_safety: float = 1.0
+        self.route_threshold: float = 0.05
+        self.value_drift: float = 0.08
+        self.fresh_loser_redo_prob: float = 0.0
+        self.n_levels = 3
+        self.fields_per_level = 6
+        self.deps_per_field = 3
+        self.frac_zero_tol = 0.30
+        self.zero_tol = 0.01
+        self.gen_tol = 0.25
+        # policy_mode set by configure; per-write re-routing only happens
+        # in "hybrid" mode (mirrors cr.build). "occ" and "cascade" fix the
+        # field's policy at configure time and propose_update must NOT clobber it.
+        self.policy_mode: str = "hybrid"
+        self.global_materiality: float = 0.20
+        # multiplicative log-normal noise on tolerance ESTIMATE (mirrors
+        # cr.Config.tol_est_noise). >0 -> hybrid over-estimates on ~half its
+        # fields even at tol_safety=1 -> silent errors (perfect-knowledge
+        # artifact test).
+        self.tol_est_noise: float = 0.0
+        self.rng: random.Random = random.Random(0)
+
+    def reset(self) -> None:
+        self.fields.clear()
+        self.read_rev.clear()
+        self.read_val.clear()
+        self.pending.clear()
+
+
+state = CascadeState()
+
+
+# ----------------------------- tool implementations --------------------------
+# Pure async functions: take parsed python args, return python dicts.
+# The MCP decorators below adapt these to JSON wire types.
+
+async def configure_impl(
+    n_levels: int, fields_per_level: int, deps_per_field: int,
+    frac_zero_tol: float, zero_tol: float, gen_tol: float,
+    tol_safety: float, route_threshold: float, value_drift: float,
+    fresh_loser_redo_prob: float, seed: int,
+    policy_mode: str = "hybrid", global_materiality: float = 0.20,
+    tol_est_noise: float = 0.0,
+) -> dict:
+    """Build the DAG exactly like cr.build, then store regime config."""
+    state.rng = random.Random(seed)
+    state.n_levels = n_levels
+    state.fields_per_level = fields_per_level
+    state.deps_per_field = deps_per_field
+    state.frac_zero_tol = frac_zero_tol
+    state.zero_tol = zero_tol
+    state.gen_tol = gen_tol
+    state.tol_safety = tol_safety
+    state.route_threshold = route_threshold
+    state.value_drift = value_drift
+    state.fresh_loser_redo_prob = fresh_loser_redo_prob
+    state.policy_mode = policy_mode
+    state.global_materiality = global_materiality
+    state.tol_est_noise = tol_est_noise
+    state.reset()
+    # build DAG (mirrors cr.build)
+    by: list[list[str]] = []
+    for lvl in range(n_levels):
+        ids = [f"L{lvl}_{i}" for i in range(fields_per_level)]
+        by.append(ids)
+        for fid in ids:
+            if lvl == 0:
+                deps: list[str] = []
+            else:
+                pool = [x for p in by[:lvl] for x in p]
+                deps = state.rng.sample(pool, min(deps_per_field, len(pool)))
+            f = cr.Field(id=fid, level=lvl, deps=deps)
+            if lvl > 0:
+                f.true_tol = zero_tol if state.rng.random() < frac_zero_tol else gen_tol
+                measured = f.true_tol * tol_safety
+                if tol_est_noise > 0.0:
+                    measured *= math.exp(state.rng.gauss(0.0, tol_est_noise))
+                if policy_mode == "occ":
+                    f.policy = "occ"
+                elif policy_mode == "occ_value":
+                    f.policy = "occ_value"
+                    f.materiality = global_materiality
+                elif policy_mode == "cascade":
+                    f.policy = "cascade"
+                    f.materiality = global_materiality
+                else:  # hybrid
+                    if measured < route_threshold:
+                        f.policy = "occ"
+                    else:
+                        f.policy = "cascade"
+                        f.materiality = measured
+            state.fields[fid] = f
+    return {"status": "configured", "fields": list(state.fields.keys())}
+
+
+async def read_state_impl(fields: list[str], agent_id: str,
+                           write_field: str = "") -> dict:
+    """Return current value+rev of requested fields; secretly log them as the
+    caller's read-set keyed by (agent_id, write_field). write_field is the
+    field the agent intends to propose later (its deps are what's read)."""
+    snapshot = {}
+    log_rev: dict[str, int] = {}
+    log_val: dict[str, float] = {}
+    for fid in fields:
+        f = state.fields[fid]
+        snapshot[fid] = {"rev": f.rev, "value": f.value}
+        log_rev[fid] = f.rev
+        log_val[fid] = f.value
+    if write_field:
+        state.read_rev[(agent_id, write_field)] = log_rev
+        state.read_val[(agent_id, write_field)] = log_val
+    return {"fields": snapshot}
+
+
+async def churn_impl(field: str) -> dict:
+    """Source-field churn: bump rev+value (mirrors the sim's source churn)."""
+    f = state.fields[field]
+    f.rev += 1
+    f.value *= (1.0 + state.rng.gauss(0.0, state.value_drift))
+    return {"field": field, "rev": f.rev, "value": f.value}
+
+
+async def propose_update_impl(
+    field: str, proposed_value: Any, confidence: float,
+    authority_tier: int, tolerance: float, agent_id: str,
+    expected_writers: int,
+) -> dict:
+    """Record a proposed write. When the batch reaches expected_writers, run
+    cr.resolve on the whole batch and return the outcome. Uses `tolerance` as
+    the field's true_tol for this write and re-derives policy/materiality from
+    it (mirrors cr.build's hybrid branch), so callers passing the field's
+    constant true_tol reproduce the sim exactly."""
+    f = state.fields[field]
+    # look up the agent's logged read-set for this field
+    read_rev = state.read_rev.get((agent_id, field), {})
+    read_val = state.read_val.get((agent_id, field), {})
+    # if no logged read-set, snapshot current (agent didn't call read_state)
+    if not read_rev:
+        read_rev = {d: state.fields[d].rev for d in f.deps}
+        read_val = {d: state.fields[d].value for d in f.deps}
+    w = cr.Write(tier=authority_tier, conf=confidence,
+                 read_rev=dict(read_rev), read_val=dict(read_val))
+    state.pending.setdefault(field, []).append(w)
+    batch = state.pending[field]
+    if len(batch) < expected_writers:
+        return {"status": "pending", "field": field,
+                "received": len(batch), "expected": expected_writers}
+    # batch complete -> resolve
+    # Set the field's true_tol from the caller-declared tolerance. Re-derive
+    # routing ONLY in hybrid mode AND only if the caller's tolerance differs
+    # from what configure_impl already set (mirrors cr.build's hybrid branch).
+    # In occ/cascade modes the policy/materiality were fixed at configure time
+    # and must NOT be clobbered per-write. Re-deriving when tolerance is
+    # unchanged would also wipe any tol_est_noise applied at build time.
+    if abs(f.true_tol - tolerance) > 1e-12:
+        f.true_tol = tolerance
+        if state.policy_mode == "hybrid":
+            measured = tolerance * state.tol_safety
+            if state.tol_est_noise > 0.0:
+                measured *= math.exp(state.rng.gauss(0.0, state.tol_est_noise))
+            if measured < state.route_threshold:
+                f.policy = "occ"
+            else:
+                f.policy = "cascade"
+                f.materiality = measured
+    cfg = cr.Config(value_drift=state.value_drift,
+                    fresh_loser_redo_prob=state.fresh_loser_redo_prob,
+                    tol_safety=state.tol_safety,
+                    tol_est_noise=state.tol_est_noise,
+                    route_threshold=state.route_threshold)
+    committed, redo, silent, arm = cr.resolve(f, batch, state.fields, cfg, state.rng)
+    # staleness accounting at resolve time (for the CSV). occ uses rev-stale;
+    # occ_value, cascade, and hybrid all use the value-predicate drift.
+    if f.policy == "occ":
+        n_stale = sum(1 for ww in batch if cr.rev_stale(ww, state.fields))
+    else:
+        n_stale = sum(1 for ww in batch if cr.drift(ww, state.fields) > f.materiality)
+    # winner tier/conf
+    if arm in ("WINNER", "FORK", "OCC_COMMIT"):
+        fresh = [ww for ww in batch
+                 if (not cr.rev_stale(ww, state.fields) if f.policy == "occ"
+                      else cr.drift(ww, state.fields) <= f.materiality)]
+        bt = min(ww.tier for ww in fresh)
+        top = [ww for ww in fresh if ww.tier == bt]
+        bc = max(ww.conf for ww in top)
+        top = [ww for ww in top if ww.conf == bc]
+        win_tier = top[0].tier
+        top_conf = top[0].conf
+    else:
+        win_tier = -1
+        top_conf = -1.0
+    if committed:
+        cr.bump(f, state.rng, cfg)
+    del state.pending[field]
+    return {
+        "status": "resolved", "field": field, "arm": arm,
+        "recomputes": redo, "silent_error": silent,
+        "committed": committed, "n_writers": len(batch), "n_stale": n_stale,
+        "win_tier": win_tier, "top_confidence": top_conf,
+    }
+
+
+async def get_field_impl(field: str) -> dict:
+    """Inspect a field's current state (for tests/debugging)."""
+    f = state.fields[field]
+    return {"id": f.id, "level": f.level, "deps": f.deps, "rev": f.rev,
+            "value": f.value, "true_tol": f.true_tol,
+            "policy": f.policy, "materiality": f.materiality}
+
+
+# ----------------------------- MCP server wiring -----------------------------
+
+server = Server("cascade-routing-controller")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="configure",
+            description="Build the dependency DAG and set regime parameters.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "n_levels": {"type": "integer"},
+                    "fields_per_level": {"type": "integer"},
+                    "deps_per_field": {"type": "integer"},
+                    "frac_zero_tol": {"type": "number"},
+                    "zero_tol": {"type": "number"},
+                    "gen_tol": {"type": "number"},
+                    "tol_safety": {"type": "number"},
+                    "route_threshold": {"type": "number"},
+                    "value_drift": {"type": "number"},
+                    "fresh_loser_redo_prob": {"type": "number"},
+                    "seed": {"type": "integer"},
+                    "policy_mode": {"type": "string"},
+                    "global_materiality": {"type": "number"},
+                },
+                "required": ["n_levels", "fields_per_level", "deps_per_field",
+                             "frac_zero_tol", "zero_tol", "gen_tol",
+                             "tol_safety", "route_threshold", "value_drift",
+                             "fresh_loser_redo_prob", "seed"],
+            },
+        ),
+        types.Tool(
+            name="read_state",
+            description="Read current value+rev of fields and log them as the "
+                        "caller's read-set (the premise snapshot for a later write).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "fields": {"type": "array", "items": {"type": "string"}},
+                    "agent_id": {"type": "string"},
+                    "write_field": {"type": "string"},
+                },
+                "required": ["fields", "agent_id", "write_field"],
+            },
+        ),
+        types.Tool(
+            name="propose_update",
+            description="Propose a write. When the batch for `field` reaches "
+                        "`expected_writers`, runs the hybrid resolve_field router.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "field": {"type": "string"},
+                    "proposed_value": {},
+                    "confidence": {"type": "number"},
+                    "authority_tier": {"type": "integer"},
+                    "tolerance": {"type": "number"},
+                    "agent_id": {"type": "string"},
+                    "expected_writers": {"type": "integer"},
+                },
+                "required": ["field", "proposed_value", "confidence",
+                             "authority_tier", "tolerance", "agent_id",
+                             "expected_writers"],
+            },
+        ),
+        types.Tool(
+            name="churn",
+            description="Bump a source field's rev+value (simulates upstream churn).",
+            inputSchema={
+                "type": "object",
+                "properties": {"field": {"type": "string"}},
+                "required": ["field"],
+            },
+        ),
+        types.Tool(
+            name="get_field",
+            description="Inspect a field's current state.",
+            inputSchema={
+                "type": "object",
+                "properties": {"field": {"type": "string"}},
+                "required": ["field"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
+    if name == "configure":
+        r = await configure_impl(**arguments)
+    elif name == "read_state":
+        r = await read_state_impl(**arguments)
+    elif name == "propose_update":
+        r = await propose_update_impl(**arguments)
+    elif name == "churn":
+        r = await churn_impl(**arguments)
+    elif name == "get_field":
+        r = await get_field_impl(**arguments)
+    else:
+        raise ValueError(f"unknown tool: {name}")
+    return [types.TextContent(type="text", text=json.dumps(r, default=str))]
+
+
+async def main() -> None:
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+def cli() -> None:
+    """Synchronous entry point for the ``cascade-mcp`` console script."""
+    import asyncio
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    cli()

cascade_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: cascade-mcp
+Version: 0.1.0
+Summary: Cascade-resolution routing for concurrent multi-agent writes, exposed as an MCP server.
+Project-URL: Homepage, https://github.com/clemente-turrubiates/cascade-mcp
+Project-URL: Repository, https://github.com/clemente-turrubiates/cascade-mcp
+Author: Pedro Clemente-Turrubiates
+License: MIT License
+        
+        Copyright (c) 2026 Pedro Clemente-Turrubiates
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,conflict-resolution,mcp,model-context-protocol,occ,routing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Description-Content-Type: text/markdown
+
+# cascade-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/cascade-mcp.svg)](https://pypi.org/project/cascade-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/cascade-mcp.svg)](https://pypi.org/project/cascade-mcp/)
+[![CI](https://github.com/clemente-turrubiates/cascade-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/clemente-turrubiates/cascade-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Cascade-resolution routing for concurrent multi-agent writes — a resolution
+router that decides, per conflict, whether a write **wins**, **forks** to a
+human, or must be **recomputed**, plus an MCP server that exposes the router as
+tools and a stress-test suite that proves the behavior can't be cherry-picked.
+
+## What's here
+
+The core question: when many agents write to the same field over a dependency
+DAG, how do you resolve conflicts without either silently committing wrong
+values (pure cascade) or overpaying in wasted re-runs (pure OCC)? The **hybrid**
+policy routes zero-tolerance fields to OCC and tolerant fields to a
+provenance-weighted cascade. Every conflict lands in one of a few arms:
+
+- **WINNER** — a live (non-stale) write wins on authority → confidence. No
+  re-run, no human. This is the win over OCC.
+- **FORK** — two+ fresh writes tie; defer to a human/high-tier agent instead of
+  silently dropping one.
+- **RECOMPUTE** — every competing write is premise-stale; there's no correct
+  value to pick, so re-run. Here you're no better than OCC.
+
+## Layout
+
+```
+cascade/                 importable package
+  cascade_routing.py     core resolution router (OCC vs cascade vs hybrid)
+  server.py              MCP stdio server wrapping the router as tools
+  cascade_sim.py         standalone go/no-go regime simulator
+scripts/                 data-generation / audit utilities
+  gen_agent_logs.py      emit agent_logs.csv across the regime × policy grid
+  audit_cherrypick.py    adversarial read of agent_logs.csv
+  validate_logs.py       quick sanity checks on a generated CSV
+tests/                   verification suite
+  test_agent_logs.py     43-check self-consistency + usability suite over the CSV
+  test_mcp_wrapper.py    routes the regime grid through the MCP wrapper and
+                         re-runs the suite to prove the wrapper preserves behavior
+```
+
+Large simulation outputs (`agent_logs.csv`, `agent_logs_mcp.csv`, ~900 MB each)
+are regenerable and are gitignored.
+
+## Requirements
+
+- Python ≥ 3.10 (developed on 3.13)
+- [`mcp`](https://pypi.org/project/mcp/) — installed automatically as a dependency
+
+## Install & attach to an MCP client
+
+Once published to PyPI, no clone or virtualenv is needed — [`uvx`](https://docs.astral.sh/uv/)
+runs the server in an ephemeral environment:
+
+```
+uvx cascade-mcp
+```
+
+To attach the router to **Claude Desktop** or **Cursor**, add this to your
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cascade": {
+      "command": "uvx",
+      "args": ["cascade-mcp"]
+    }
+  }
+}
+```
+
+The MCP server exposes five tools: `configure`, `read_state`, `propose_update`,
+`churn`, `get_field`.
+
+## Usage (from source)
+
+Clone the repo and run everything **from the repo root**.
+
+Run the MCP server (stdio):
+
+```
+python -m cascade.server
+```
+
+Run the standalone simulator:
+
+```
+python -m cascade.cascade_sim
+```
+
+Generate the stress-test CSV (writes UTF-8 — pipe via a POSIX shell, **not**
+PowerShell `>`, which re-encodes to UTF-16 and corrupts the file):
+
+```
+python scripts/gen_agent_logs.py > agent_logs.csv
+```
+
+Verify the generated CSV:
+
+```
+python -m tests.test_agent_logs        # 43-check suite
+python scripts/audit_cherrypick.py     # adversarial cross-checks
+```
+
+Verify the MCP wrapper preserves the router's behavior end-to-end (wire-protocol
+smoke test → regime grid through the wrapper → re-run the suite):
+
+```
+python -m tests.test_mcp_wrapper
+```

cascade_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cascade/__init__.py,sha256=g3tK6_JLleAXkdJ8CZAOzJeY6MqaeguI7fL3nO6oBHU,284
+cascade/cascade_routing.py,sha256=BgP6NV4YA19-u1ky5Q55Y1vLKu1srNO54_Eewj3d2MM,8357
+cascade/cascade_sim.py,sha256=C3ReNNQJ7RBaqnHN0jLjrWkd3ARznvPLJHfZZom4kcE,13647
+cascade/server.py,sha256=o5XXmxrBnDiDrMnJ8Qby_xE4C3mUyWcc1VPqoy9DDgY,16056
+cascade_mcp-0.1.0.dist-info/METADATA,sha256=AxSnfVFlUy4DDqeHJjtbpPPt6-371yuVNkQilK0g91I,5909
+cascade_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cascade_mcp-0.1.0.dist-info/entry_points.txt,sha256=JjoVpF8tLyfqtSkcvCLCAES5RLeXd3l00fkkv3KQlLI,51
+cascade_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=BT6a36j8u_AQmHmhEU7Md6yreS5_E6MqZf5digarpFY,1083
+cascade_mcp-0.1.0.dist-info/RECORD,,

cascade_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cascade_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cascade-mcp = cascade.server:cli

cascade_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Clemente-Turrubiates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.