Operon v0.24: Why Your Agent Framework Needs a Structural Linter

1. The Problem: Framework Fragmentation

The ACG survey catalogs over forty distinct multi-agent coordination methods. Each reinvents the same set of coordination patterns — supervisor hierarchies, sequential pipelines, parallel fan-out — with different names, different APIs, and different failure characteristics. There is no shared vocabulary for the structural properties that determine whether a given agent topology will amplify errors or incur unnecessary overhead.

This matters because, as Evans et al. argue in their work on collective intelligence, intelligence is plural: different problem shapes call for different coordination patterns. We need interoperation between frameworks, not a winner-take-all consolidation. But interoperation requires a shared structural language — something that describes what a topology is, independent of which framework instantiated it.

The practical consequence is that framework authors are flying blind. A Swarms HierarchicalSwarm with eight agents and a deep delegation chain may have an error amplification bound of 6.4x, but you would never know it until it failed in production. A DeerFlow LangGraph session with twelve sequential handoffs may spend 40% of its wall-clock time on coordination overhead, but the framework has no way to warn you. These are structural properties — they follow from the topology itself, not from the prompts or models.

2. The Solution: ExternalTopology as Universal IR

Operon v0.24 introduces ExternalTopology: a single frozen dataclass that any agent framework’s configuration can be parsed into. It captures the minimal structural information needed for analysis — agent names, roles, directed edges, and metadata — without importing anything from the source framework.

@dataclass(frozen=True)
class ExternalTopology:
    source: str              # "swarms", "deerflow", "animaworks", "ralph", "aevolve"
    pattern_name: str        # e.g., "HierarchicalSwarm", "LangGraphSession"
    agents: tuple[dict, ...]  # at least "name" and "role" per agent
    edges: tuple[tuple[str, str], ...]  # directed (from, to) pairs
    metadata: dict = field(default_factory=dict)

The key function is analyze_external_topology(). It takes any ExternalTopology and applies Operon’s four epistemic theorems as a structural linter:

1. Error amplification bound — how badly can errors cascade through the topology?
2. Sequential penalty — how much wall-clock time is lost to handoff coordination?
3. Tool density — is the planning cost ratio manageable?
4. Topology classification — does the external topology match Operon’s recommendation for the detected task shape?

Here is what it looks like in practice, analyzing a Swarms HierarchicalSwarm:

from operon_ai.convergence import (
    parse_swarm_topology,
    analyze_external_topology,
)

# Parse a Swarms HierarchicalSwarm config
topology = parse_swarm_topology(
    pattern_name="HierarchicalSwarm",
    agent_specs=[
        {"name": "director", "role": "supervisor", "capabilities": ["planning"]},
        {"name": "researcher", "role": "worker", "capabilities": ["web_search"]},
        {"name": "writer", "role": "worker", "capabilities": ["text_gen"]},
        {"name": "reviewer", "role": "critic", "capabilities": ["code_review"]},
    ],
    edges=[
        ("director", "researcher"),
        ("director", "writer"),
        ("researcher", "reviewer"),
        ("writer", "reviewer"),
    ],
)

# Analyze with Operon's epistemic theorems
result = analyze_external_topology(topology)

print(f"Risk score: {result.risk_score}")        # 0.0 - 1.0
print(f"Warnings: {result.warnings}")             # structural concerns
print(f"Recommended: {result.topology_advice}")   # Operon's suggestion
print(f"Template: {result.suggested_template}")   # ready for PatternLibrary

The output is an AdapterResult containing a composite risk score, a list of structural warnings, Operon’s topology recommendation, and a PatternTemplate that can be registered directly in a PatternLibrary for reuse. Zero coupling: the adapter never imports the swarms package. It operates entirely on dicts and tuples.

3. Five Frameworks, One Abstraction

v0.24 ships adapters for five distinct agent orchestration frameworks, each representing a different coordination paradigm:

Every adapter follows the same pattern: parse the framework-specific configuration into an ExternalTopology, then call analyze_external_topology(). The analysis code does not know or care which framework produced the topology. Adding a sixth adapter is approximately 100 lines of parsing code.

The adapters also provide source-specific converters — swarm_to_template(), deerflow_to_template(), ralph_to_template(), animaworks_to_template(), aevolve_to_template() — that produce richer PatternTemplate objects with framework-specific metadata preserved. These templates can be registered in a PatternLibrary and exchanged between organisms using the social learning protocol.

4. Formal Verification: TLA+ for Agent Systems

Structural linting catches topology-level risks. But there are deeper coordination properties that static analysis cannot reach: does template exchange always respect developmental stage requirements? Can a critical period accidentally reopen? Will a non-converging organism always be halted? These are questions about all possible interleavings of concurrent operations — and they require formal verification.

What is TLA+?

TLA+ (Temporal Logic of Actions) is Leslie Lamport’s specification language for modeling concurrent and distributed systems. It lets you describe a system as a state machine — an initial state plus a set of actions that transition between states — and then state invariants and temporal properties that should hold across all reachable states. The TLC model checker exhaustively explores every possible state to verify these properties.

TLA+ is not an academic curiosity. Amazon uses it to verify AWS infrastructure protocols. Microsoft uses it for Azure Cosmos DB’s consistency guarantees. MongoDB uses it for their replication protocol. These are organizations that discovered, the hard way, that testing concurrent systems is insufficient — bugs that depend on specific interleavings of operations will slip through any finite test suite.

Why it matters for agent systems

Agent orchestration is a distributed systems problem. When organism A imports a template from organism B, that is a distributed state update involving trust scoring, stage verification, and library modification. When a watcher checks convergence while stages are still running, that is a concurrent safety check. When A-Evolve’s evolution loop accepts a mutation while another organism is reading the workspace, that is a classic read-write concurrency scenario.

Testing catches bugs in the interleavings your tests happen to exercise. TLA+ catches bugs in all interleavings — including the ones that only manifest when three organisms simultaneously attempt template exchange while one of them is mid-stage-advance. Those are the bugs that make multi-agent systems fail in production in ways nobody can reproduce.

What Operon’s specs verify

Operon ships four TLA+ specifications in the specs/ directory. Each models a specific coordination protocol and proves that its safety invariants hold for all possible interleavings.

\* From TemplateExchangeProtocol.tla -- the stage guard
Import(org, peer) ==
    /\ org # peer                                    \* No self-adoption
    /\ trust[org][peer] >= MIN_TRUST                 \* Trust guard
    /\ \E tmpl \in exported[peer] :
         /\ tmpl \notin library[org]                 \* Not already held
         /\ StageGEQ(stage[org], MinStage[tmpl])     \* Stage guard
         /\ MeetsAdoptionThreshold(peer, tmpl, trust[org][peer])
         /\ library' = [library EXCEPT ![org] = library[org] \union {tmpl}]

How TLC model checking works

TLC, the TLA+ model checker, works by exhaustive state exploration. You define a small model — say, 2 organisms, 3 templates, 5 telomere units — and TLC explores every reachable state from the initial configuration. For the TemplateExchangeProtocol with 2 organisms and 3 templates, this means exploring every possible interleaving of Export, Import, RecordOutcome, and StageAdvance actions across both organisms.

If any reachable state violates a safety invariant, TLC produces a counterexample trace: the exact sequence of actions that leads to the violation. This is invaluable for debugging — it tells you not just that something can go wrong, but exactly how.

Operon’s four specs pass TLC on their configured small models. All safety invariants and temporal properties hold for every reachable state in the explored state space.

The gap between model and reality

Honesty demands a caveat. TLA+ proves properties of the model, not the implementation. The model abstracts away timing, network failures, floating-point precision, and Python’s GIL. The TemplateExchangeProtocol spec models trust as a real number in [0, 1]; the implementation uses IEEE 754 doubles. The ConvergenceDetection spec models intervention rate as exact rational division; the implementation uses floating-point comparison.

But these abstractions are deliberate and documented. TLA+ catches design-level bugs — the kind that emerge from incorrect protocol logic, missing guards, or unanticipated action interleavings. These are exactly the bugs that make multi-agent systems fail in ways that testing never reproduces, because the failure requires a specific interleaving of concurrent operations across multiple organisms.

The specs live in specs/ in the Operon repository: TemplateExchangeProtocol.tla, DevelopmentalGating.tla, ConvergenceDetection.tla, EvolutionGating.tla.

5. Co-Design Convergence: Does the Adaptive Loop Stabilize?

The five adapters raise a composition question: when you chain them together in an adaptive assembly loop — run a topology, score its performance, select a better template, repeat — does the loop converge? Or does it oscillate forever between configurations?

This is where Zardini’s co-design theory from ETH Zurich becomes directly applicable. In the co-design framework, each adapter is a design problem (DP): a monotone map from a resource poset (inputs, constraints) to a functionality poset (outputs, capabilities). Monotonicity means: more resources yield at least as many functionalities.

from operon_ai.convergence import (
    DesignProblem,
    compose_series,
    compose_parallel,
    feedback_fixed_point,
)

# Each adapter as a design problem
swarms_dp = DesignProblem(
    name="swarms_adapter",
    evaluate_fn=lambda r: {"risk": analyze_swarms(r), "templates": r["templates"] + 1},
    feasibility_fn=lambda r: r.get("agents", 0) > 0,
)

deerflow_dp = DesignProblem(
    name="deerflow_adapter",
    evaluate_fn=lambda r: {"risk": analyze_deerflow(r), "skills": r.get("skills", 0)},
    feasibility_fn=lambda r: r.get("session") is not None,
)

# Series composition: swarms analysis feeds deerflow analysis
pipeline = compose_series(swarms_dp, deerflow_dp, name="swarms_then_deerflow")

# Feedback fixed-point: does the adaptive loop converge?
final_state, iterations, converged = feedback_fixed_point(
    pipeline,
    initial={"agents": 4, "templates": 0, "session": True, "skills": 0},
    convergence_key="risk",
    epsilon=0.01,
    max_iterations=100,
)

print(f"Converged: {converged} in {iterations} iterations")
print(f"Final risk: {final_state['risk']}")

The adaptive assembly loop (run → score → select → repeat) is feedback composition in Zardini’s framework. The monotone convergence theorem guarantees that if the scoring function is monotone and bounded, the sequence of scores approaches a limit. feedback_fixed_point() provides practical epsilon-approximate termination: when the score changes by less than epsilon between iterations, the loop halts.

6. What This Means for Framework Authors

If you are building an agent framework, Operon can serve as your structural linter. The integration model is deliberately lightweight:

• Zero coupling. Adapters operate on dicts and tuples. They never import your framework. You never import Operon at runtime. The boundary is a serialization format.
• Free structural analysis. Parse your framework’s config into an ExternalTopology, call analyze_external_topology(), and you get error amplification bounds, sequential penalty estimates, tool density ratios, and topology recommendations. These are properties your users care about but your framework probably does not compute.
• Template exchange. The PatternTemplate objects produced by adapters are interoperable. A template extracted from a Swarms workflow can be registered in a PatternLibrary and offered to organisms running DeerFlow sessions. Cross-framework collaboration patterns become possible.
• Extensibility. The ExternalTopology abstraction is intentionally minimal. Adding an adapter for a new framework is approximately 100 lines of parsing code: extract agent names, roles, and edges from your config format. The analysis pipeline is source-agnostic.

The convergence adapters also provide catalog-seeding functions — seed_library_from_swarms(), seed_library_from_deerflow(), seed_library_from_ralph() — that populate a PatternLibrary with pre-analyzed templates from each framework’s standard workflow patterns. These are ready to use as starting points for the adaptive assembly loop.

7. What’s Next

v0.24 completes the convergence adapter layer (phases C1 through C4). The roadmap continues:

• C5: Compilers. Reverse the flow — compile Operon organisms back into Swarms, DeerFlow, and Ralph configurations. organism_to_swarms(), organism_to_deerflow(), organism_to_ralph(). Currently in design.
• C6: Cross-target evaluation. Run the same organism blueprint against A-Evolve benchmarks across all five frameworks. Compare structural predictions against empirical performance.
• C7: DSPy-style prompt optimization. Use A-Evolve’s evolution loop to optimize prompts within Operon organisms, with the evolution gating spec ensuring monotonic improvement.

The convergence paper documenting the formal framework and proofs is available at article/paper2/main.pdf.

8. Closing

The agent ecosystem does not need one framework to win. It needs a shared structural language for reasoning about agent coordination — what Operon calls the “structural layer.” v0.24 is a concrete step toward that goal: five adapters proving that one abstraction works across graph-based, event-driven, and evolutionary paradigms. Four TLA+ specifications proving that the coordination protocols are safe under all interleavings. And a co-design convergence theorem proving that the adaptive assembly loop stabilizes.

The structural linter is free, the adapters are zero-coupling, and the formal specs are open. If your framework coordinates agents, Operon can tell you what will go wrong before you deploy it.

Code and release: github.com/coredipper/operon, operon-ai on PyPI, convergence docs, convergence paper