Address code review comments: add debug logging and fix docs

Co-authored-by: PhenX <42170+PhenX@users.noreply.github.com>

Author: Copilot

docs/graph-insert.md

@@ -39,7 +39,7 @@ await dbContext.ExecuteBulkInsertAsync(blogs, options =>
 ## Performance Considerations
 
 - Graph insert is inherently slower than flat insert due to FK propagation overhead
-- For entities with identity columns, the library uses `ExecuteBulkInsertReturnEntities` internally to retrieve generated IDs
+- For entities with identity columns, the library uses `ExecuteBulkInsertReturnEntitiesAsync` internally to retrieve generated IDs
 - Consider using client-generated keys (GUIDs with `ValueGeneratedNever()`) to avoid ID propagation overhead
 - Use `MaxGraphDepth` to limit traversal for large/deep graphs
 - Use `IncludeNavigations` or `ExcludeNavigations` to reduce the scope of insertions

src/PhenX.EntityFrameworkCore.BulkInsert/Graph/GraphBulkInsertOrchestrator.cs

@@ -226,7 +226,13 @@ private static void CopyGeneratedIds<TEntity>(
     {
         if (originalEntities.Count != insertedEntities.Count)
         {
-            // Can't reliably map back
+            // Count mismatch - this can happen if the bulk insert operation
+            // doesn't preserve order. Log a warning for debugging purposes.
+            // The graph insert will continue but FK propagation may be incomplete.
+            System.Diagnostics.Debug.WriteLine(
+                $"Warning: IncludeGraph ID propagation failed for {typeof(TEntity).Name}. " +
+                $"Original count: {originalEntities.Count}, Inserted count: {insertedEntities.Count}. " +
+                "Foreign key values may not be correctly propagated to dependent entities.");
             return;
         }
 
@@ -288,6 +294,9 @@ private async Task InsertJoinRecordsAsync(
                 var joinEntry = Activator.CreateInstance(joinEntityType);
                 if (joinEntry == null)
                 {
+                    System.Diagnostics.Debug.WriteLine(
+                        $"Warning: IncludeGraph failed to create join entry for {joinEntityType.Name}. " +
+                        "Many-to-many relationship may be incomplete.");
                     continue;
                 }
 

src/PhenX.EntityFrameworkCore.BulkInsert/Graph/GraphEntityCollector.cs

@@ -55,6 +55,8 @@ public GraphEntityCollector(DbContext context, BulkInsertOptions options)
     {
         _options = options;
         _graphMetadata = new GraphMetadata(context, options);
+        // Use ReferenceEqualityComparer to track visited entity instances by reference,
+        // not by property values, to correctly handle cycles in the object graph
         _visited = new HashSet<object>(ReferenceEqualityComparer.Instance);
         _entitiesByType = [];
         _joinRecords = [];