clawmates/docs/topology-platform.md

Dynamic Agentic Topologies — platform architecture

Status: Phase 0/1 (foundation). Source of truth for the topology-switching capability.

Goal

Let users build agentic systems that swap into any organizational topology, run a task across topologies on ClawMates' real §15-safe per-tenant runtime, and measure which patterns yield better results — producing both a product capability and reproducible data for a paper on large dynamic agentic topologies.

We re-implement the topology IP from ~/projects/agentorg in pure Rust (agentorg's modeling is real; its execution is largely simulated — ClawMates supplies the missing safe execution).

Curated topology set (v1)

Start with topologies that differ meaningfully in execution (governance/novel forms deferred):

Kind	Shape	Execution pattern
hierarchical	tree	orchestrator delegates down; results bubble up
flat	peers, light coord	autonomous peers, minimal coordination
pipeline	linear stages	output of stage n → input of stage n+1
swarm	broadcast + vote	parallel attempts, consensus/aggregation
mesh	dense peer-to-peer	peers exchange freely until convergence
hub_spoke	central hub	hub routes to spokes, aggregates
ring	cycle	sequential round-trips, refine each lap
star_moe	router + experts	router picks expert(s) per subtask (MoE)
market	auction	tasks bid out to agents by fit/cost
blackboard	shared memory	agents read/write a shared workspace
debate	adversarial	proposer vs critic rounds → judge
holacratic	self-org circles	circles self-assign within roles

Each kind carries heuristics (default role distribution + optimization weights), ported from agentorg agents/swarmagentic/swarm/topology_manager.py.

TopologyGraph schema (cm-topology)

• Node = a role slot: { id, role, level?, attrs } (bound to a real claw/AgentId at run time).
• Edge = a relationship: { from, to, kind } where EdgeKind ∈ {delegates_to, reports_to, pipes_to, peers_with, routes_to, bids_to, reads_writes}.
• A graph also records its declared TopologyKind. The classifier can also infer the kind from graph metrics (degree/centrality variance, density, clustering, modularity, hierarchy score, diameter) → { kind, confidence }, ported from topology_classifier.py.
• Adapter: a serde TopologySpec (JSON/YAML) normalizes into a TopologyGraph (mirrors org_adapter/normalize_topology.py).

§15 edge contract (non-negotiable)

A topology only describes who talks to whom and who decides. Execution semantics never bypass ClawMates safety: any edge whose action leaves the sandbox (email/Slack/pay/delete/etc.) routes through cm-safety (approvals + single-use secret broker + audit journal), exactly as a single claw does today. Switching topology cannot widen an agent's authority. This is the platform's moat and the paper's safety contribution.

Crate / component map

• crates/cm-topology ✅: pure, offline — kinds, graph, adapter, classifier, heuristics.
• crates/cm-orchestrator ✅ (Phase 2): executes a task across a TopologyGraph by sequencing safe turns via a generic TurnExecutor. All 12 kinds run, mapped to five execution patterns: hierarchical (also hub_spoke/star_moe/market), pipeline (also ring), swarm (also flat/holacratic), mesh (also blackboard), debate. ProviderExecutor (cm-llm) runs real tool-free turns today; a cm-runtime tool-using executor (full §15 + run_events) is the remaining adapter.
• Experiment harness ✅ (Phase 4 core, in orchestrator): compare() runs a task across N topologies; captures tokens/quality(JudgeScorer)/turns/#blocked-approvals; computes Pareto + leaderboard. Runnable via examples/topology_bench.rs.
• cm-api (next): CRUD topologies; create runs (single / workflow-of-topologies / comparison); fetch results.
• cm-db: topologies, topology_runs, run_results, pareto_snapshots.
• frontend/: ReactFlow topology builder + Pareto/leaderboard view.

agentorg → Rust port map

agentorg (Python)	ClawMates (Rust)
agents/topology_classifier.py (TopologyType, classifier)	cm-topology::kind, cm-topology::classifier
org_adapter/normalize_topology.py (OrganizationGraph, adapter)	cm-topology::graph, cm-topology::adapter
agents/swarmagentic/swarm/topology_manager.py (heuristics)	cm-topology::heuristics
swarm_templates/ (templates)	seed catalog under cm-topology (later)
benchmarks/, monitoring/pareto/	experiment harness (Phase 4)
papers/*	papers/dynamic-agentic-topologies.md

Phases & verification

• P1 cm-topology: cargo test -p cm-topology — known graphs classify to expected kinds; spec round-trips; every kind has heuristics.
• P2 runtime: one task runs under a topology on a dev tenant; every gated action still needs approval.
• P3/P4: user selects a topology/workflow and runs it; same task across ≥3 topologies → real cost/quality leaderboard + Pareto; existing e2e/§15 suites stay green.
• Paper: one command reproduces a benchmark table from logged runs.