# 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.