//! Organizational topologies for agentic systems — pure, offline modeling.
//!
//! A [`TopologyGraph`] describes *who talks to whom and who decides* in a
//! system of agents (claws). It is a description only: execution semantics
//! (and the §15 safety gates) live in the orchestrator, never here.
//!
//! This crate is dependency-light (serde + thiserror) and has no I/O, so it
//! doubles as a reusable library for benchmarking/topology research.
//!
//! Modules:
//! - [`kind`]      — the curated [`TopologyKind`] taxonomy.
//! - [`graph`]     — the [`TopologyGraph`] data model + validation.
//! - [`adapter`]   — normalize a loose JSON/YAML spec into a graph.
//! - [`classifier`]— infer a topology kind from a graph's structure.
//! - [`heuristics`]— per-kind role distributions / optimization weights.

mod adapter;
mod builders;
mod classifier;
mod graph;
mod heuristics;
mod kind;

pub use adapter::{from_json, to_json};
pub use builders::build;
pub use classifier::{classify, Classification, GraphMetrics};
pub use graph::{Edge, EdgeKind, Node, TopologyGraph};
pub use heuristics::{heuristics, Heuristics};
pub use kind::{ExecutionPattern, TopologyKind};

/// Errors produced while building or validating a topology.
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum TopologyError {
    /// The graph has no nodes.
    #[error("topology has no nodes")]
    Empty,
    /// An edge references a node id that does not exist.
    #[error("edge references unknown node: {0}")]
    UnknownNode(String),
    /// Two nodes share an id.
    #[error("duplicate node id: {0}")]
    DuplicateNode(String),
    /// The input spec could not be parsed.
    #[error("invalid spec: {0}")]
    Spec(String),
}