From d7bbdc8e866a2736d68969b7f4eccecd621ffd6f Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 3 Apr 2026 03:43:53 +0000
Subject: [PATCH] =?UTF-8?q?=E2=9A=A1=20Bolt:=20Fix=20task=20serialization?=
 =?UTF-8?q?=20in=20scanners=20for=20true=20parallelism?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Changed `CacheScanner` and `NodeModulesScanner` from `actor` to `struct`
- Updated docstrings to reflect the thread-safety architecture
- By avoiding actor isolation for these stateless components, their `withTaskGroup` implementations can now execute parallel filesystem scanning across multiple threads without being serialized to the actor's context.

Co-authored-by: acebytes <2820910+acebytes@users.noreply.github.com>
---
 .jules/bolt.md                                    | 3 +++
 Sources/Cacheout/Scanner/CacheScanner.swift       | 8 ++++----
 Sources/Cacheout/Scanner/NodeModulesScanner.swift | 4 ++--
 3 files changed, 9 insertions(+), 6 deletions(-)
 create mode 100644 .jules/bolt.md

diff --git a/.jules/bolt.md b/.jules/bolt.md
new file mode 100644
index 0000000..4e04aea
--- /dev/null
+++ b/.jules/bolt.md
@@ -0,0 +1,3 @@
+## 2024-05-19 - Unblocking parallel tasks by avoiding actor isolation for sync I/O
+**Learning:** In Swift structured concurrency, using an `actor` to manage a `withTaskGroup` where tasks invoke synchronous, blocking I/O (like `FileManager` operations) directly on the actor inadvertently serializes the tasks, preventing parallelism.
+**Action:** For stateless components interacting with thread-safe dependencies, use `struct`s or `nonisolated` methods to allow tasks to execute concurrently across threads.
\ No newline at end of file
diff --git a/Sources/Cacheout/Scanner/CacheScanner.swift b/Sources/Cacheout/Scanner/CacheScanner.swift
index 3ce3e9c..e13fa7b 100644
--- a/Sources/Cacheout/Scanner/CacheScanner.swift
+++ b/Sources/Cacheout/Scanner/CacheScanner.swift
@@ -1,13 +1,13 @@
 /// # CacheScanner — Parallel Cache Category Scanner
 ///
-/// An `actor` that scans all registered cache categories concurrently using
+/// A `struct` that scans all registered cache categories concurrently using
 /// Swift's structured concurrency (`TaskGroup`). Each category is scanned in
 /// its own child task for maximum parallelism.
 ///
 /// ## Thread Safety
 ///
-/// Uses the `actor` isolation model to ensure thread-safe access to internal state.
-/// All public methods are `async` and can be called from any concurrency context.
+/// Being a stateless struct, all public methods are `async` and execute
+/// without actor isolation, enabling true parallelism across threads.
 ///
 /// ## Disk Size Calculation
 ///
@@ -26,7 +26,7 @@
 
 import Foundation
 
-actor CacheScanner {
+struct CacheScanner {
     private let fileManager = FileManager.default
 
     func scanAll(_ categories: [CacheCategory]) async -> [ScanResult] {
diff --git a/Sources/Cacheout/Scanner/NodeModulesScanner.swift b/Sources/Cacheout/Scanner/NodeModulesScanner.swift
index 3ed4d8c..2dce2ce 100644
--- a/Sources/Cacheout/Scanner/NodeModulesScanner.swift
+++ b/Sources/Cacheout/Scanner/NodeModulesScanner.swift
@@ -1,6 +1,6 @@
 /// # NodeModulesScanner — Recursive node_modules Finder
 ///
-/// An `actor` that recursively searches common developer project directories
+/// A `struct` that recursively searches common developer project directories
 /// for `node_modules` folders. Designed to find abandoned or stale dependencies
 /// that consume significant disk space.
 ///
@@ -28,7 +28,7 @@
 
 import Foundation
 
-actor NodeModulesScanner {
+struct NodeModulesScanner {
     private let fileManager = FileManager.default
 
     /// Common directories where developers keep projects