refactor: remove cycle checking becuase API prevents cycles

src/cycle_prevention.rs

@@ -0,0 +1,82 @@
+//! # Compile-Time Cycle Prevention
+//!
+//! This module documents how the type system prevents cycles in the DAG.
+//! **Cycles are impossible via the public API** due to the type-state pattern.
+//!
+//! ## Why Cycles Can't Happen
+//!
+//! 1. [`crate::builder::TaskBuilder::depends_on`] **consumes** the builder (takes `self` by value)
+//! 2. It returns a [`crate::types::TaskHandle`] - an immutable, opaque reference
+//! 3. [`crate::types::TaskHandle`] has **no methods** to add or modify dependencies
+//! 4. You can only wire dependencies **once** per task
+//!
+//! ## The Catch-22
+//!
+//! To create a cycle A→B→A, you would need:
+//! - Task A to depend on Task B's handle (requires B finalized)
+//! - Task B to depend on Task A's handle (requires A finalized)
+//!
+//! But you can't finalize both before wiring them together!
+//!
+//! ## Proof by Compilation Failure
+//!
+//! The following examples demonstrate that cycles fail to compile:
+//!
+//! ### Proof 1: Self-Loop Prevention via Move Semantics
+//!
+//! ```compile_fail
+//! use dagx::*;
+//!
+//! struct TaskA;
+//! #[dagx::task]
+//! impl TaskA {
+//!     async fn run(&self, input: &i32) -> i32 {
+//!         input + 1
+//!     }
+//! }
+//!
+//! async fn self_loop() {
+//!     let dag = DagRunner::new();
+//!     let a_builder = dag.add_task(TaskA);
+//!
+//!     // ERROR: a_builder moved in the call to depends_on
+//!     // Can't use 'a_builder' as both the builder and the dependency
+//!     let a = a_builder.depends_on(&a_builder);
+//! }
+//! ```
+//!
+//! ### Proof 2: TaskHandle is Immutable
+//!
+//! ```compile_fail,E0599
+//! use dagx::*;
+//!
+//! struct NoInput;
+//! #[dagx::task]
+//! impl NoInput {
+//!     async fn run(&self) -> i32 { 42 }
+//! }
+//!
+//! async fn unit_cycle() {
+//!     let dag = DagRunner::new();
+//!     let a_builder = dag.add_task(NoInput);
+//!     let b_builder = dag.add_task(NoInput);
+//!
+//!     // We can convert to handles (unit input = no dependencies required)
+//!     let a_handle: TaskHandle<i32> = a_builder.into();
+//!     let b_handle: TaskHandle<i32> = b_builder.into();
+//!
+//!     // But TaskHandle has no methods to add dependencies!
+//!     // ERROR: no method named `depends_on` found for type `TaskHandle<i32>`
+//!     let _ = a_handle.depends_on(&b_handle);
+//! }
+//! ```
+//!
+//! ## Implications
+//!
+//! Because cycles are impossible at compile-time:
+//! - No runtime cycle detection is needed
+//! - Topological sort will always succeed
+//! - The DAG structure is guaranteed by the type system
+//!
+//! This is an example of **zero-cost abstraction** - the type system
+//! provides safety guarantees without runtime overhead.

src/error.rs

@@ -5,11 +5,6 @@
 /// Errors that can occur during DAG construction and execution
 #[derive(Debug, Clone, PartialEq)]
 pub enum DagError {
-    /// A cycle was detected in the DAG
-    CycleDetected {
-        nodes: Vec<usize>,
-        description: String,
-    },
     /// Invalid dependency: task does not exist
     InvalidDependency { task_id: usize },
     /// Type mismatch in task dependencies
@@ -24,22 +19,13 @@ pub enum DagError {
     },
     /// Result not found for task
     ResultNotFound { task_id: usize },
+    /// Attempted to run the DAG while it's already running
+    ConcurrentExecution,
 }
 
 impl std::fmt::Display for DagError {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
-            DagError::CycleDetected { nodes, description } => {
-                write!(
-                    f,
-                    "Cycle detected in DAG: {}\n\
-                     Nodes involved: {:?}\n\
-                     \n\
-                     A DAG cannot have cycles. Review your dependency graph to identify \
-                     and remove circular dependencies.",
-                    description, nodes
-                )
-            }
             DagError::InvalidDependency { task_id } => {
                 write!(
                     f,
@@ -81,6 +67,14 @@ impl std::fmt::Display for DagError {
                     task_id
                 )
             }
+            DagError::ConcurrentExecution => {
+                write!(
+                    f,
+                    "DAG is already running - concurrent execution not supported.\n\
+                     \n\
+                     Wait for the current execution to complete before starting another."
+                )
+            }
         }
     }
 }

src/error/tests.rs

@@ -44,20 +44,6 @@ fn test_dag_error_display_task_panicked() {
     assert!(display.contains("entire DAG execution is aborted"));
 }
 
-#[test]
-fn test_dag_error_display_cycle_detected() {
-    let err = DagError::CycleDetected {
-        nodes: vec![1, 2, 3, 1],
-        description: "A->B->C->A".to_string(),
-    };
-    let display = format!("{}", err);
-
-    assert!(display.contains("Cycle detected"));
-    assert!(display.contains("A->B->C->A"));
-    assert!(display.contains("[1, 2, 3, 1]"));
-    assert!(display.contains("cannot have cycles"));
-}
-
 #[test]
 fn test_dag_error_display_result_not_found() {
     let err = DagError::ResultNotFound { task_id: 7 };
@@ -68,6 +54,16 @@ fn test_dag_error_display_result_not_found() {
     assert!(display.contains("Call dag.run()"));
 }
 
+#[test]
+fn test_dag_error_display_concurrent_execution() {
+    let err = DagError::ConcurrentExecution;
+    let display = format!("{}", err);
+
+    assert!(display.contains("already running"));
+    assert!(display.contains("concurrent execution not supported"));
+    assert!(display.contains("Wait for the current execution"));
+}
+
 #[test]
 fn test_dag_error_std_error_impl() {
     // Test that DagError implements std::error::Error

src/lib.rs

@@ -5,16 +5,17 @@
 //!
 //! # Features
 //!
+//! - **Compile-time cycle prevention**: The type system makes cycles **impossible**—no runtime
+//!   cycle detection needed! See [`cycle_prevention`] module for detailed explanation and proof.
 //! - **Compile-time type safety**: Dependencies are validated at compile time through the type
 //!   system. The public API is fully type-safe with no runtime type errors. Internal execution
 //!   uses type erasure for heterogeneous task storage, but this is never exposed to users.
 //! - **Runtime-agnostic**: Works with any async runtime (Tokio, async-std, smol, Embassy, etc.)
 //! - **Type-state pattern**: The API guides you with compile-time errors if you wire dependencies
-//!   incorrectly
+//!   incorrectly. This is what prevents cycles at compile time.
 //! - **Optimal execution**: Topological scheduling with maximum safe parallelism
 //! - **Zero-cost abstractions**: Leverages generics and monomorphization for minimal overhead
-//! - **Error handling**: Result-based error handling with [`DagResult<T>`] for cycle detection
-//!   and validation
+//! - **Error handling**: Result-based error handling with [`DagResult<T>`] for validation
 //!
 //! # Quick Start
 //!
@@ -470,7 +471,8 @@
 //! dagx uses [`DagResult<T>`] (an alias for `Result<T, DagError>`) for operations that
 //! can fail:
 //!
-//! - [`DagRunner::run`] returns `DagResult<()>` and can fail if a cycle is detected
+//! - [`DagRunner::run`] returns `DagResult<()>` and can fail if tasks panic or if multiple
+//!   concurrent runs are attempted
 //! - [`DagRunner::get`] returns `DagResult<T>` and can fail if the task hasn't executed or
 //!   the handle is invalid
 //!
@@ -688,7 +690,7 @@
 //! - **INFO**: DAG execution start/completion
 //! - **DEBUG**: Task additions, dependency wiring, layer computation
 //! - **TRACE**: Individual task execution (inline vs spawned), detailed execution flow
-//! - **ERROR**: Panics, cycles, type errors
+//! - **ERROR**: Task panics, concurrent execution attempts
 //!
 //! Control log level with the `RUST_LOG` environment variable:
 //!
@@ -717,6 +719,7 @@
 
 // Module declarations
 mod builder;
+pub mod cycle_prevention;
 mod deps;
 mod error;
 mod extract;

src/runner.rs

@@ -294,11 +294,7 @@ impl DagRunner {
             #[cfg(feature = "tracing")]
             error!("DAG is already running - concurrent execution not supported");
 
-            return Err(DagError::CycleDetected {
-                nodes: vec![],
-                description: "DAG is already running - concurrent execution not supported"
-                    .to_string(),
-            });
+            return Err(DagError::ConcurrentExecution);
         }
 
         // Guard ensures lock is released on drop (even on early return or panic)
@@ -609,7 +605,6 @@ impl DagRunner {
 
         // Calculate in-degrees: for each node, count how many dependencies it has
         let edges = self.edges.lock();
-        let total_nodes = edges.len();
 
         for (&node, deps) in edges.iter() {
             let degree = deps.len();
@@ -661,31 +656,8 @@ impl DagRunner {
             }
         }
 
-        // Cycle detection: if we haven't visited all nodes, there's a cycle
-        if visited.len() != total_nodes {
-            let unvisited: Vec<_> = in_degree
-                .iter()
-                .filter(|(node, _)| !visited.contains(node))
-                .map(|(node, _)| node.0)
-                .collect();
-            let description = format!(
-                "{} node(s) could not be processed: {:?}",
-                unvisited.len(),
-                unvisited
-            );
-
-            #[cfg(feature = "tracing")]
-            error!(
-                unvisited_count = unvisited.len(),
-                unvisited_nodes = ?unvisited,
-                "cycle detected in DAG"
-            );
-
-            return Err(DagError::CycleDetected {
-                nodes: unvisited,
-                description,
-            });
-        }
+        // Cycle detection removed: cycles are impossible via the public API.
+        // See src/cycle_prevention.rs for proof that the type system prevents cycles.
 
         #[cfg(feature = "tracing")]
         debug!(layer_count = layers.len(), "topological layers computed");

src/runner/tests.rs

@@ -168,10 +168,16 @@ async fn test_concurrent_run_protection() {
 
     // The error should be about concurrent execution
     if result1.is_err() {
-        assert!(matches!(result1.unwrap_err(), crate::error::DagError::CycleDetected { ref description, .. } if description.contains("already running")));
+        assert!(matches!(
+            result1.unwrap_err(),
+            crate::error::DagError::ConcurrentExecution
+        ));
     }
     if result2.is_err() {
-        assert!(matches!(result2.unwrap_err(), crate::error::DagError::CycleDetected { ref description, .. } if description.contains("already running")));
+        assert!(matches!(
+            result2.unwrap_err(),
+            crate::error::DagError::ConcurrentExecution
+        ));
     }
 }