taski 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ad85c90c371fc1ea2f61e1d7e9817c7a9cc3fa9f258be2bf1154ced5f4c0349
-  data.tar.gz: a56399d990f0a3ecfddff0f24b5a45c8319ea88e58299a3d3a22a2336295f5cc
+  metadata.gz: 7c7ea0740de2f0d1fcf24a72fe5b32e75128fa4d793718b3ac12a2c041c37628
+  data.tar.gz: 8fb45c4d390a98709d934f4b59f14a613d689ed7538df630cb4328bc405b2803
 SHA512:
-  metadata.gz: f6969545ce4924434c3e031dca9fff39a974dfd53ee73fb610979cdc3fd09842f50b8871efec23a79dd40d1985bb97c92b651744655a38a12edbdeb9c0f05daa
-  data.tar.gz: 94a9f76f2da179d4b202b788f3abf27531b8a1df4ccd186eb84a5c695dfcbca3c78f75f2350ba052dcb98b68da7427e60b0a493e67340c1d04440278b4c3ab7f
+  metadata.gz: 7cba0b749c9f5b5e76f990731017d18c550407215f851877129d2c6b1c9872fccfb3d0e088b01db19a92064f92592971a085ca9eecca3bcd8742e44b7374a9e5
+  data.tar.gz: 211b4d9ed455e19688bbb29acc7beb5043150703e144bb38f973b68f6bbf5fb3aa942c7fd2d77faa4332df243cb5f0d50e4a06813c7786b7c954f5a8eb674900

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-02-16
+
+### Changed
+- Replace raw arrays and hashes with FiberProtocol Data classes for typed protocol messages ([#175](https://github.com/ahogappa/taski/pull/175))
+- Add AST-guided start_dep speculative parallel execution for improved performance ([#175](https://github.com/ahogappa/taski/pull/175))
+- Add TaskProxy for lazy dependency resolution with unsafe proxy usage detection ([#175](https://github.com/ahogappa/taski/pull/175))
+- Remove static-graph-based task scheduling from Executor in favor of Fiber pull model ([#176](https://github.com/ahogappa/taski/pull/176))
+- Replace inline `Class.new(Taski::Task)` with named fixture classes in tests ([#174](https://github.com/ahogappa/taski/pull/174))
+- Add custom export methods section to README ([#172](https://github.com/ahogappa/taski/pull/172))
+
+### Fixed
+- Fix data race on `@next_thread_index` in enqueue/enqueue_clean ([#175](https://github.com/ahogappa/taski/pull/175))
+
 ## [0.9.0] - 2026-02-08
 
 ### Added

data/README.md

@@ -15,6 +15,7 @@
 - **Exports API**: Simple value sharing between tasks
 - **Real-time Progress**: Visual feedback with parallel task progress display
 - **Fiber-Based Execution**: Lightweight Fiber-based dependency resolution for efficient parallel execution
+- **Lazy Dependency Resolution**: Dependencies return lightweight proxies that defer resolution until the value is actually used, enabling better parallelism
 
 ## Quick Start
 
@@ -77,6 +78,46 @@ class Server < Taski::Task
 end
 ```
 
+### Custom Export Methods
+
+By default, `exports` generates a reader that returns the instance variable (e.g., `exports :value` reads `@value`). You can override this by defining your own instance method with the same name:
+
+**Fixed values** — no computation needed in `run`:
+
+```ruby
+class Config < Taski::Task
+  exports :timeout
+
+  def timeout
+    30
+  end
+
+  def run; end
+end
+
+Config.timeout  # => 30
+```
+
+**Shared logic between `run` and `clean`** — the method works as both an export and a regular instance method:
+
+```ruby
+class DatabaseSetup < Taski::Task
+  exports :connection
+
+  def connection
+    @connection ||= Database.connect
+  end
+
+  def run
+    connection.setup_schema
+  end
+
+  def clean
+    connection.close
+  end
+end
+```
+
 ### Conditional Logic - Runtime Selection
 
 Use `if` statements to switch behavior based on environment:
@@ -230,6 +271,8 @@ RandomTask.value  # => 99 (different value - fresh execution)
 DoubleConsumer.run  # RandomTask runs once, both accesses get same value
 ```
 
+When a task accesses a dependency (e.g., `SomeDep.value`), the result may be a lightweight proxy. The actual resolution is deferred until the value is used, allowing independent dependencies to execute in parallel transparently. This is automatic and requires no changes to your task code. Dependencies used in conditions or as arguments are automatically resolved synchronously for safety.
+
 ### Error Handling
 
 When a task fails, Taski wraps the error with task-specific context. Each task class automatically gets a `::Error` subclass for targeted rescue:

data/docs/GUIDE.md

@@ -7,6 +7,7 @@ This guide provides detailed documentation beyond the basics covered in the READ
 - [Error Handling](#error-handling)
 - [Lifecycle Management](#lifecycle-management)
 - [Progress Display](#progress-display)
+- [Lazy Dependency Resolution](#lazy-dependency-resolution)
 - [Debugging](#debugging)
 
 ---
@@ -354,6 +355,44 @@ ruby build.rb > build.log 2>&1
 
 ---
 
+## Lazy Dependency Resolution
+
+### How It Works
+
+When a task accesses a dependency's exported value (e.g., `DepTask.value`), Taski may return a lightweight **proxy object** instead of the actual value. This proxy defers dependency resolution until you call a method on it, at which point it transparently resolves the real value and forwards the method call.
+
+```ruby
+class FetchData < Taski::Task
+  exports :data
+  def run
+    @data = expensive_api_call
+  end
+end
+
+class ProcessData < Taski::Task
+  exports :result
+  def run
+    raw = FetchData.data       # May return a proxy (no blocking yet)
+    setup_environment          # Task continues while FetchData runs
+    @result = raw.transform    # Proxy resolves here — blocks if needed
+  end
+end
+```
+
+From the user's perspective, the proxy is completely transparent — it behaves exactly like the real value.
+
+### Why It Matters
+
+Proxy-based resolution enables better parallelism. A task can continue executing setup logic while its dependencies are still running, only blocking when the dependency value is actually used. This can significantly reduce total execution time when tasks have independent setup work before they need their dependencies.
+
+### Automatic Safety
+
+Taski uses static analysis (Prism AST parsing) to determine when proxy resolution is safe. Dependencies used in positions where the proxy could cause issues — such as conditions (`if dep_value`), method arguments, or other contexts where truthiness or identity matters — are automatically resolved synchronously instead of returning a proxy.
+
+You do not need to think about this in normal usage. The static analyzer examines your task's `run` method and only enables proxy resolution for dependency accesses that are confirmed safe (e.g., simple assignments like `x = Dep.value` followed by method calls on `x`).
+
+---
+
 ## Debugging
 
 ### Structured Logging
@@ -390,4 +429,4 @@ end
 
 **Static Analysis Requirements**
 
-Tasks must be defined in source files (not dynamically with `Class.new`) because static analysis uses Prism AST parsing which requires actual source files.
+Tasks must be defined in source files (not dynamically with `Class.new`) because static analysis uses Prism AST parsing which requires actual source files. Static analysis is used for dependency tree visualization, circular dependency detection, and optimizing dependency resolution (determining when lazy proxy resolution is safe vs. when synchronous resolution is required).

data/lib/taski/execution/executor.rb

@@ -5,8 +5,12 @@ require "etc"
 module Taski
   module Execution
     # Orchestrates run (Fiber-based) and clean (direct) phases of task execution.
-    # Delegates to Scheduler (dependency order), WorkerPool (worker threads),
-    # and ExecutionFacade (observer notifications).
+    # Delegates to Scheduler (state tracking / advisory proposals),
+    # WorkerPool (worker threads), and ExecutionFacade (observer notifications).
+    #
+    # Task execution is driven by the Fiber pull model — tasks start only when
+    # requested via Fiber.yield FiberProtocol::NeedDep. Scheduler may propose tasks,
+    # but Executor/Wrapper can reject proposals not backed by actual Fiber requests.
     class Executor
       class << self
         def execute(root_task_class, registry:, execution_facade:)
@@ -43,8 +47,6 @@ module Taski
 
           @worker_pool.start
 
-          pre_start_leaf_tasks
-
           enqueue_root_if_needed(root_task_class)
 
           run_main_loop(root_task_class)
@@ -83,10 +85,6 @@ module Taski
 
       # Run phase
 
-      def pre_start_leaf_tasks
-        @scheduler.next_ready_tasks.each { |task_class| enqueue_for_execution(task_class) }
-      end
-
       def enqueue_root_if_needed(root_task_class)
         return unless @scheduler.pending?(root_task_class)
 
@@ -98,24 +96,30 @@ module Taski
           break if @registry.abort_requested? && !@scheduler.running_tasks?
 
           event = @completion_queue.pop
-          handle_completion(event)
+          case event
+          in FiberProtocol::StartDepNotify => notify
+            @scheduler.mark_running(notify.task_class)
+          in FiberProtocol::TaskCompleted | FiberProtocol::TaskFailed
+            handle_completion(event)
+          else
+            raise "[BUG] unexpected completion queue event: #{event.inspect}"
+          end
         end
       end
 
       def handle_completion(event)
-        task_class = event[:task_class]
+        task_class = event.task_class
         Taski::Logging.debug(Taski::Logging::Events::EXECUTOR_TASK_COMPLETED, task: task_class.name)
 
-        if event[:error]
-          @scheduler.mark_failed(task_class)
-          log_error_detail(task_class, event[:error])
-          skip_pending_dependents(task_class)
-        else
+        case event
+        in FiberProtocol::TaskFailed => failed
+          @scheduler.mark_failed(failed.task_class)
+          log_error_detail(failed.task_class, failed.error)
+          skip_pending_dependents(failed.task_class)
+        in FiberProtocol::TaskCompleted
           @scheduler.mark_completed(task_class)
-        end
-
-        @scheduler.next_ready_tasks.each do |ready_class|
-          enqueue_for_execution(ready_class)
+        else
+          raise "[BUG] unexpected run completion event: #{event.inspect}"
         end
       end
 
@@ -192,13 +196,18 @@ module Taski
       end
 
       def handle_clean_completion(event)
-        task_class = event[:task_class]
+        task_class = event.task_class
         Taski::Logging.debug(Taski::Logging::Events::EXECUTOR_CLEAN_COMPLETED, task: task_class.name)
-        if event[:error]
-          @scheduler.mark_clean_failed(task_class)
-        else
+
+        case event
+        in FiberProtocol::CleanFailed => failed
+          @scheduler.mark_clean_failed(failed.task_class)
+        in FiberProtocol::CleanCompleted
           @scheduler.mark_clean_completed(task_class)
+        else
+          raise "[BUG] unexpected clean completion event: #{event.inspect}"
         end
+
         enqueue_ready_clean_tasks
       end
 

data/lib/taski/execution/fiber_protocol.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Taski
+  module Execution
+    module FiberProtocol
+      # === Fiber yields (task -> worker pool) ===
+      StartDep = Data.define(:task_class)
+      NeedDep = Data.define(:task_class, :method)
+
+      # === Fiber resume error signal (worker pool -> task) ===
+      DepError = Data.define(:error)
+
+      # === Completion queue events (worker pool -> executor) ===
+      StartDepNotify = Data.define(:task_class)
+      TaskCompleted = Data.define(:task_class, :wrapper)
+      TaskFailed = Data.define(:task_class, :wrapper, :error)
+      CleanCompleted = Data.define(:task_class, :wrapper)
+      CleanFailed = Data.define(:task_class, :wrapper, :error)
+
+      # === Worker thread commands (pool -> worker thread) ===
+      Execute = Data.define(:task_class, :wrapper)
+      ExecuteClean = Data.define(:task_class, :wrapper)
+      Resume = Data.define(:fiber, :value)
+      ResumeError = Data.define(:fiber, :error)
+    end
+  end
+end

data/lib/taski/execution/task_wrapper.rb

@@ -297,13 +297,13 @@ module Taski
       def notify_fiber_waiters_completed(waiters)
         waiters.each do |thread_queue, fiber, method|
           value = @task.public_send(method)
-          thread_queue.push([:resume, fiber, value])
+          thread_queue.push(FiberProtocol::Resume.new(fiber, value))
         end
       end
 
       def notify_fiber_waiters_failed(waiters, error)
         waiters.each do |thread_queue, fiber, _method|
-          thread_queue.push([:resume_error, fiber, error])
+          thread_queue.push(FiberProtocol::ResumeError.new(fiber, error))
         end
       end
     end

data/lib/taski/execution/worker_pool.rb

@@ -10,19 +10,22 @@ module Taski
 
     # WorkerPool manages N threads, each with its own command Queue.
     # Tasks are executed within Fibers on worker threads.
-    # When a Fiber yields [:need_dep, dep_class, method], the worker
-    # resolves the dependency via TaskWrapper#request_value:
     #
-    # - :completed → resume Fiber immediately with the value
-    # - :wait → park the Fiber (it will be resumed later via the thread's queue)
-    # - :start → start the dependency as a nested Fiber on the same thread
+    # Fiber protocol supports two yield types (FiberProtocol Data classes):
+    # - StartDep(task_class)          → non-blocking. Starts dep on another
+    #   thread and resumes the Fiber immediately. Used for speculative prestart.
+    # - NeedDep(task_class, method)   → blocking. Resolves dependency via
+    #   TaskWrapper#request_value:
+    #   - :completed → resume Fiber immediately with the value
+    #   - :wait → park the Fiber (it will be resumed later via the thread's queue)
+    #   - :start → start the dependency as a nested Fiber on the same thread
     #
-    # Worker threads process these commands:
-    # - [:execute, task_class, wrapper]       → create and drive a new Fiber
-    # - [:execute_clean, task_class, wrapper] → run clean directly (no Fiber)
-    # - [:resume, fiber, value]               → resume a parked Fiber with a value
-    # - [:resume_error, fiber, error]         → resume a parked Fiber with an error
-    # - :shutdown                             → exit the worker loop
+    # Worker threads process these commands (FiberProtocol Data classes):
+    # - Execute(task_class, wrapper)       → create and drive a new Fiber
+    # - ExecuteClean(task_class, wrapper)  → run clean directly (no Fiber)
+    # - Resume(fiber, value)               → resume a parked Fiber with a value
+    # - ResumeError(fiber, error)          → resume a parked Fiber with an error
+    # - :shutdown                          → exit the worker loop
     class WorkerPool
       attr_reader :worker_count
 
@@ -38,6 +41,7 @@ module Taski
         @fiber_contexts = {}
         @task_start_times_mutex = Mutex.new
         @task_start_times = {}
+        @enqueue_mutex = Mutex.new
       end
 
       def start
@@ -52,17 +56,21 @@ module Taski
 
       # Round-robins across worker threads.
       def enqueue(task_class, wrapper)
-        queue = @thread_queues[@next_thread_index % @worker_count]
-        @next_thread_index += 1
-        queue.push([:execute, task_class, wrapper])
-        Taski::Logging.debug(Taski::Logging::Events::WORKER_POOL_ENQUEUED, task: task_class.name, thread_index: (@next_thread_index - 1) % @worker_count)
+        @enqueue_mutex.synchronize do
+          queue = @thread_queues[@next_thread_index % @worker_count]
+          @next_thread_index += 1
+          queue.push(FiberProtocol::Execute.new(task_class, wrapper))
+          Taski::Logging.debug(Taski::Logging::Events::WORKER_POOL_ENQUEUED, task: task_class.name, thread_index: (@next_thread_index - 1) % @worker_count)
+        end
       end
 
       # Clean tasks run directly without Fiber wrapping.
       def enqueue_clean(task_class, wrapper)
-        queue = @thread_queues[@next_thread_index % @worker_count]
-        @next_thread_index += 1
-        queue.push([:execute_clean, task_class, wrapper])
+        @enqueue_mutex.synchronize do
+          queue = @thread_queues[@next_thread_index % @worker_count]
+          @next_thread_index += 1
+          queue.push(FiberProtocol::ExecuteClean.new(task_class, wrapper))
+        end
       end
 
       def shutdown
@@ -77,19 +85,17 @@ module Taski
           cmd = queue.pop
           break if cmd == :shutdown
 
-          case cmd[0]
-          when :execute
-            _, task_class, wrapper = cmd
-            drive_fiber(task_class, wrapper, queue)
-          when :resume
-            _, fiber, value = cmd
-            resume_fiber(fiber, value, queue)
-          when :resume_error
-            _, fiber, error = cmd
-            resume_fiber_with_error(fiber, error, queue)
-          when :execute_clean
-            _, task_class, wrapper = cmd
-            execute_clean_task(task_class, wrapper)
+          case cmd
+          in FiberProtocol::Execute => exec
+            drive_fiber(exec.task_class, exec.wrapper, queue)
+          in FiberProtocol::Resume => res
+            resume_fiber(res.fiber, res.value, queue)
+          in FiberProtocol::ResumeError => err
+            resume_fiber_with_error(err.fiber, err.error, queue)
+          in FiberProtocol::ExecuteClean => clean
+            execute_clean_task(clean.task_class, clean.wrapper)
+          else
+            raise "[BUG] unexpected worker command: #{cmd.inspect}"
           end
         end
       end
@@ -99,9 +105,16 @@ module Taski
       def drive_fiber(task_class, wrapper, queue)
         return if @registry.abort_requested?
 
+        analysis = Taski::StaticAnalysis::StartDepAnalyzer.analyze(task_class)
         fiber = Fiber.new do
           setup_run_thread_locals
-          wrapper.task.run
+          Thread.current[:taski_start_deps] = analysis.start_deps
+          (analysis.start_deps | analysis.sync_deps).each { |dep_class| Fiber.yield(FiberProtocol::StartDep.new(dep_class)) }
+          run_result = wrapper.task.run
+          resolve_proxy_exports(wrapper)
+          run_result
+        ensure
+          Thread.current[:taski_start_deps] = nil
         end
 
         now = Time.now
@@ -120,12 +133,16 @@ module Taski
         result = fiber.resume(resume_value)
 
         while fiber.alive?
-          if result.is_a?(Array) && result[0] == :need_dep
-            _, dep_class, method = result
-            handle_dependency(dep_class, method, fiber, task_class, wrapper, queue)
+          case result
+          in FiberProtocol::StartDep => start_dep
+            handle_start_dep(start_dep.task_class)
+            result = fiber.resume
+            next
+          in FiberProtocol::NeedDep => need_dep
+            handle_dependency(need_dep.task_class, need_dep.method, fiber, task_class, wrapper, queue)
             return # Fiber is either continuing or parked
           else
-            break
+            break # task.run returned a non-protocol value (normal completion)
           end
         end
 
@@ -142,12 +159,13 @@ module Taski
         when :completed
           drive_fiber_loop(fiber, task_class, wrapper, queue, status[1])
         when :failed
-          drive_fiber_loop(fiber, task_class, wrapper, queue, [:_taski_error, status[1]])
+          drive_fiber_loop(fiber, task_class, wrapper, queue, FiberProtocol::DepError.new(status[1]))
         when :wait
           store_fiber_context(fiber, task_class, wrapper)
         when :start
           store_fiber_context(fiber, task_class, wrapper)
-          start_dependency(dep_class, dep_wrapper, queue)
+          # dep_wrapper is already RUNNING (set atomically by request_value)
+          drive_fiber(dep_class, dep_wrapper, queue)
         end
       end
 
@@ -155,29 +173,52 @@ module Taski
       # Restores fiber context before resuming since teardown_thread_locals
       # cleared thread-local state when the fiber was parked.
       def resume_fiber(fiber, value, queue)
-        context = get_fiber_context(fiber)
-        return unless context
-
-        task_class, wrapper = context
-        setup_run_thread_locals
-        start_output_capture(task_class)
-        drive_fiber_loop(fiber, task_class, wrapper, queue, value)
+        resume_fiber_with_value(fiber, value, queue)
       end
 
       def resume_fiber_with_error(fiber, error, queue)
+        resume_fiber_with_value(fiber, FiberProtocol::DepError.new(error), queue)
+      end
+
+      def resume_fiber_with_value(fiber, resume_value, queue)
         context = get_fiber_context(fiber)
         return unless context
 
         task_class, wrapper = context
         setup_run_thread_locals
         start_output_capture(task_class)
-        drive_fiber_loop(fiber, task_class, wrapper, queue, [:_taski_error, error])
+        drive_fiber_loop(fiber, task_class, wrapper, queue, resume_value)
       end
 
-      # Start a dependency task as a new Fiber on this thread.
-      # The wrapper is already RUNNING (set atomically by request_value).
-      def start_dependency(dep_class, dep_wrapper, queue)
-        drive_fiber(dep_class, dep_wrapper, queue)
+      # Handle :start_dep — speculatively start a dependency on another thread.
+      # Non-blocking: the calling Fiber is resumed immediately after enqueueing.
+      # Uses mark_running to prevent duplicate starts.
+      def handle_start_dep(dep_class)
+        dep_wrapper = @registry.create_wrapper(dep_class, execution_facade: @execution_facade)
+        return unless dep_wrapper.mark_running
+
+        # Notify Executor so Scheduler can track the running state.
+        # Must be pushed before the execute command to guarantee ordering.
+        @completion_queue.push(FiberProtocol::StartDepNotify.new(dep_class))
+
+        @enqueue_mutex.synchronize do
+          target_queue = @thread_queues[@next_thread_index % @worker_count]
+          @next_thread_index += 1
+          target_queue.push(FiberProtocol::Execute.new(dep_class, dep_wrapper))
+        end
+      end
+
+      # Resolve any TaskProxy instances stored in exported ivars.
+      # After task.run, proxies assigned to @value etc. must be resolved
+      # while still inside the Fiber context so Fiber.yield works.
+      def resolve_proxy_exports(wrapper)
+        wrapper.task.class.exported_methods.each do |method|
+          ivar = :"@#{method}"
+          val = wrapper.task.instance_variable_get(ivar)
+          next unless val.respond_to?(:__taski_proxy_resolve__)
+          resolved = val.__taski_proxy_resolve__
+          wrapper.task.instance_variable_set(ivar, resolved)
+        end
       end
 
       def complete_task(task_class, wrapper, result)
@@ -185,7 +226,7 @@ module Taski
         duration = task_duration_ms(task_class)
         Taski::Logging.info(Taski::Logging::Events::TASK_COMPLETED, task: task_class.name, duration_ms: duration)
         wrapper.mark_completed(result)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper})
+        @completion_queue.push(FiberProtocol::TaskCompleted.new(task_class, wrapper))
         teardown_thread_locals
       end
 
@@ -195,7 +236,7 @@ module Taski
         duration = task_duration_ms(task_class)
         Taski::Logging.error(Taski::Logging::Events::TASK_FAILED, task: task_class.name, duration_ms: duration)
         wrapper.mark_failed(error)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper, error: error})
+        @completion_queue.push(FiberProtocol::TaskFailed.new(task_class, wrapper, error))
         teardown_thread_locals
       end
 
@@ -213,13 +254,13 @@ module Taski
         duration = ((Time.now - clean_start) * 1000).round(1)
         Taski::Logging.debug(Taski::Logging::Events::TASK_CLEAN_COMPLETED, task: task_class.name, duration_ms: duration)
         wrapper.mark_clean_completed(result)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper, clean: true})
+        @completion_queue.push(FiberProtocol::CleanCompleted.new(task_class, wrapper))
       rescue => e
         @registry.request_abort! if e.is_a?(Taski::TaskAbortException)
         duration = ((Time.now - clean_start) * 1000).round(1) if clean_start
         Taski::Logging.warn(Taski::Logging::Events::TASK_CLEAN_FAILED, task: task_class.name, duration_ms: duration)
         wrapper.mark_clean_failed(e)
-        @completion_queue.push({task_class: task_class, wrapper: wrapper, error: e, clean: true})
+        @completion_queue.push(FiberProtocol::CleanFailed.new(task_class, wrapper, e))
       ensure
         stop_output_capture
         teardown_thread_locals

data/lib/taski/static_analysis/start_dep_analyzer.rb

@@ -0,0 +1,400 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Taski
+  module StaticAnalysis
+    # Analyzes a task's run method AST to find dependencies that are safe
+    # to speculatively pre-start (start_dep). Uses a whitelist approach:
+    # only confirmed patterns are collected; unknown patterns cause the
+    # analyzer to stop (returning what was collected so far up to that point).
+    #
+    # Currently handles variable assignment patterns only:
+    #   a = Dep.value        (LocalVariableWriteNode)
+    #   @a = Dep.value       (InstanceVariableWriteNode)
+    #
+    # This is a performance optimization only — if analysis fails or returns
+    # empty, tasks still work correctly via lazy Fiber pull (need_dep).
+    class StartDepAnalyzer
+      DepInfo = Data.define(:klass, :method_name)
+      AnalysisResult = Data.define(:start_deps, :sync_deps)
+
+      # AST node types that are known safe (not dependencies, won't stop scanning)
+      SAFE_TYPES = Set[
+        Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode,
+        Prism::ConstantReadNode, Prism::ConstantPathNode,
+        Prism::IntegerNode, Prism::FloatNode, Prism::StringNode,
+        Prism::SymbolNode, Prism::NilNode, Prism::TrueNode, Prism::FalseNode,
+        Prism::SelfNode
+      ].freeze
+
+      @cache = {}
+      @cache_mutex = Mutex.new
+
+      class << self
+        # Analyze a task class and return deps safe to prestart.
+        # Results are cached per task class.
+        # @param task_class [Class] The task class to analyze
+        # @return [Array<DepInfo>] Deduplicated list of safe dependencies
+        def analyze(task_class)
+          @cache_mutex.synchronize do
+            return @cache[task_class] if @cache.key?(task_class)
+          end
+
+          result = new.analyze(task_class)
+
+          @cache_mutex.synchronize do
+            @cache[task_class] ||= result
+          end
+        end
+
+        # Clear cache (for testing)
+        def clear_cache!
+          @cache_mutex.synchronize { @cache.clear }
+        end
+      end
+
+      EMPTY_RESULT = AnalysisResult.new(start_deps: Set.new.freeze, sync_deps: Set.new.freeze).freeze
+
+      def initialize
+        @deps = []
+        @seen_classes = Set.new
+      end
+
+      # Analyze a task class's run method and return safe-to-prestart deps
+      # and sync_dep_classes (deps whose proxy variables are used unsafely).
+      # @param task_class [Class] The task class to analyze
+      # @return [AnalysisResult]
+      def analyze(task_class)
+        @task_class = task_class
+        @exported_ivars = Set.new(task_class.exported_methods.map { |m| :"@#{m}" })
+        source_location = task_class.instance_method(:run).source_location
+        return EMPTY_RESULT unless source_location
+
+        file_path, _line = source_location
+        parse_result = Prism.parse_file(file_path)
+
+        run_node = find_run_method(parse_result.value, task_class)
+        return EMPTY_RESULT unless run_node&.body
+
+        scan_statements(run_node.body)
+        unsafe_classes = detect_unsafe_proxy_usage(run_node.body)
+        all_dep_classes = Set.new(@deps.map(&:klass))
+        start_deps = all_dep_classes - unsafe_classes
+        sync_deps = unsafe_classes
+        AnalysisResult.new(start_deps: start_deps, sync_deps: sync_deps)
+      rescue NameError
+        EMPTY_RESULT
+      end
+
+      private
+
+      # Find the def run node inside the target class
+      def find_run_method(program_node, task_class)
+        target_name = task_class.name
+        find_run_in_tree(program_node, [], target_name)
+      end
+
+      def find_run_in_tree(node, namespace_path, target_name)
+        case node
+        when Prism::ProgramNode
+          node.statements.body.each do |child|
+            result = find_run_in_tree(child, namespace_path, target_name)
+            return result if result
+          end
+        when Prism::ModuleNode
+          name = node.constant_path.slice
+          new_path = namespace_path + [name]
+          node.body&.body&.each do |child|
+            result = find_run_in_tree(child, new_path, target_name)
+            return result if result
+          end
+        when Prism::ClassNode
+          name = node.constant_path.slice
+          new_path = namespace_path + [name]
+          full_name = new_path.join("::")
+
+          node.body&.body&.each do |child|
+            if full_name == target_name
+              return child if child.is_a?(Prism::DefNode) && child.name == :run
+            else
+              result = find_run_in_tree(child, new_path, target_name)
+              return result if result
+            end
+          end
+        when Prism::StatementsNode
+          node.body.each do |child|
+            result = find_run_in_tree(child, namespace_path, target_name)
+            return result if result
+          end
+        end
+
+        nil
+      end
+
+      # Scan statements, collecting deps. Stops at the first unknown pattern.
+      def scan_statements(node)
+        return unless node.is_a?(Prism::StatementsNode)
+        node.body.each { |stmt| break unless try_match(stmt) }
+      end
+
+      # Match a statement against known patterns.
+      # Returns true to continue scanning, false to stop.
+      def try_match(stmt)
+        case stmt
+        when Prism::LocalVariableWriteNode, Prism::InstanceVariableWriteNode
+          check_dep_call(stmt.value)
+          true
+        when *SAFE_TYPES
+          true
+        else
+          false
+        end
+      end
+
+      # Check if a node is a Task dependency call (Constant.method) and collect it.
+      def check_dep_call(node)
+        return unless node.is_a?(Prism::CallNode)
+        return unless node.receiver
+
+        case node.receiver
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          constant_name = node.receiver.slice
+          resolved = resolve_constant(constant_name)
+          if resolved.is_a?(Class) && defined?(Taski::Task) && resolved < Taski::Task
+            collect_dep(node)
+          end
+        end
+      end
+
+      # Collect a dependency, deduplicating by class
+      def collect_dep(call_node)
+        constant_name = call_node.receiver.slice
+        method_name = call_node.name
+        klass = resolve_constant(constant_name)
+        return unless klass
+
+        @deps << DepInfo.new(klass: klass, method_name: method_name) if @seen_classes.add?(klass)
+      end
+
+      # Phase 2: Detect proxy variables used in unsafe contexts.
+      # Returns a Set of dep classes whose proxy variables are used unsafely.
+      # A proxy variable is a local variable assigned from a Taski::Task dep call
+      # (e.g., `a = Dep.value`). If such a variable is later used in an unsafe
+      # context (as argument, condition, array element, etc.), the dep class is
+      # added to sync_dep_classes so it will be resolved synchronously.
+      def detect_unsafe_proxy_usage(body_node)
+        proxy_vars = build_proxy_var_map(body_node)
+
+        unsafe_classes = Set.new
+        scan_for_unsafe_usage(body_node, proxy_vars, unsafe_classes)
+        unsafe_classes
+      end
+
+      # Build mapping of { local_var_name => dep_class } from assignment statements
+      def build_proxy_var_map(body_node)
+        proxy_vars = {}
+        return proxy_vars unless body_node.is_a?(Prism::StatementsNode)
+
+        body_node.body.each do |stmt|
+          next unless stmt.is_a?(Prism::LocalVariableWriteNode)
+
+          dep_class = extract_dep_class(stmt.value)
+          proxy_vars[stmt.name] = dep_class if dep_class
+        end
+        proxy_vars
+      end
+
+      # Extract the dep class from a call node if it's a Taski::Task dep call
+      def extract_dep_class(node)
+        return nil unless node.is_a?(Prism::CallNode)
+        return nil unless node.receiver
+
+        case node.receiver
+        when Prism::ConstantReadNode, Prism::ConstantPathNode
+          constant_name = node.receiver.slice
+          resolved = resolve_constant(constant_name)
+          if resolved.is_a?(Class) && defined?(Taski::Task) && resolved < Taski::Task
+            resolved
+          end
+        end
+      end
+
+      # Recursively scan AST for unsafe proxy variable usage.
+      # Safe contexts: receiver of CallNode, string interpolation,
+      # RHS of local/ivar assignment. Everything else is unsafe.
+      def scan_for_unsafe_usage(node, proxy_vars, unsafe_classes) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        case node
+        when Prism::StatementsNode
+          node.body.each { |child| scan_for_unsafe_usage(child, proxy_vars, unsafe_classes) }
+
+        when Prism::LocalVariableWriteNode
+          if (dep_class = proxy_dep_class(node.value, proxy_vars))
+            # Reassignment or direct dep call: track the new variable name
+            proxy_vars[node.name] = dep_class
+          else
+            scan_for_unsafe_usage(node.value, proxy_vars, unsafe_classes)
+          end
+
+        when Prism::InstanceVariableWriteNode
+          if (dep_class = proxy_dep_class(node.value, proxy_vars))
+            if @exported_ivars.include?(node.name)
+              # @exported = proxy → safe (resolve_proxy_exports handles it)
+            else
+              # @non_exported = proxy → track for unsafe usage detection
+              proxy_vars[node.name] = dep_class
+            end
+          else
+            scan_for_unsafe_usage(node.value, proxy_vars, unsafe_classes)
+          end
+
+        when Prism::CallNode
+          # Receiver: proxy.foo → safe (method_missing fires)
+          if proxy_var_read?(node.receiver, proxy_vars)
+            # safe — don't flag receiver
+          elsif node.receiver
+            scan_for_unsafe_usage(node.receiver, proxy_vars, unsafe_classes)
+          end
+          # Arguments: foo(proxy) → UNSAFE
+          node.arguments&.arguments&.each do |arg|
+            if proxy_var_read?(arg, proxy_vars)
+              unsafe_classes.add(proxy_vars[arg.name])
+            else
+              scan_for_unsafe_usage(arg, proxy_vars, unsafe_classes)
+            end
+          end
+          scan_for_unsafe_usage(node.block, proxy_vars, unsafe_classes) if node.block
+
+        when Prism::IfNode
+          check_predicate_unsafe(node.predicate, proxy_vars, unsafe_classes)
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+          scan_for_unsafe_usage(node.subsequent, proxy_vars, unsafe_classes) if node.subsequent
+
+        when Prism::UnlessNode
+          check_predicate_unsafe(node.predicate, proxy_vars, unsafe_classes)
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+          scan_for_unsafe_usage(node.else_clause, proxy_vars, unsafe_classes) if node.else_clause
+
+        when Prism::WhileNode, Prism::UntilNode
+          check_predicate_unsafe(node.predicate, proxy_vars, unsafe_classes)
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+
+        when Prism::InterpolatedStringNode
+          node.parts.each do |part|
+            next unless part.is_a?(Prism::EmbeddedStatementsNode)
+
+            if part.statements&.body&.size == 1 &&
+                proxy_var_read?(part.statements.body[0], proxy_vars)
+              # safe — string interpolation calls to_s
+            else
+              scan_for_unsafe_usage(part, proxy_vars, unsafe_classes)
+            end
+          end
+
+        when Prism::EmbeddedStatementsNode
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+
+        when Prism::ArrayNode
+          node.elements.each do |elem|
+            if proxy_var_read?(elem, proxy_vars)
+              unsafe_classes.add(proxy_vars[elem.name])
+            else
+              scan_for_unsafe_usage(elem, proxy_vars, unsafe_classes)
+            end
+          end
+
+        when Prism::ElseNode
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+
+        when Prism::BeginNode
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+          scan_for_unsafe_usage(node.rescue_clause, proxy_vars, unsafe_classes) if node.rescue_clause
+          scan_for_unsafe_usage(node.ensure_clause, proxy_vars, unsafe_classes) if node.ensure_clause
+
+        when Prism::RescueNode
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+          scan_for_unsafe_usage(node.subsequent, proxy_vars, unsafe_classes) if node.subsequent
+
+        when Prism::EnsureNode
+          scan_for_unsafe_usage(node.statements, proxy_vars, unsafe_classes) if node.statements
+
+        when Prism::ParenthesesNode
+          scan_for_unsafe_usage(node.body, proxy_vars, unsafe_classes) if node.body
+
+        when Prism::LocalVariableReadNode, Prism::InstanceVariableReadNode
+          # Bare proxy variable read in unknown context → UNSAFE
+          unsafe_classes.add(proxy_vars[node.name]) if proxy_vars.key?(node.name)
+
+        else
+          # For any unhandled node type, recurse into children (safety-first)
+          if node.respond_to?(:compact_child_nodes)
+            node.compact_child_nodes.each do |child|
+              scan_for_unsafe_usage(child, proxy_vars, unsafe_classes)
+            end
+          end
+        end
+      end
+
+      # Check if a predicate node is an unsafe proxy variable read
+      def check_predicate_unsafe(predicate, proxy_vars, unsafe_classes)
+        if proxy_var_read?(predicate, proxy_vars)
+          unsafe_classes.add(proxy_vars[predicate_key(predicate)])
+        else
+          scan_for_unsafe_usage(predicate, proxy_vars, unsafe_classes)
+        end
+      end
+
+      # Return the dep class if the node reads a proxy variable (local or ivar)
+      # or is a direct dep call. Returns nil otherwise.
+      def proxy_dep_class(node, proxy_vars)
+        if proxy_var_read?(node, proxy_vars)
+          proxy_vars[predicate_key(node)]
+        else
+          extract_dep_class(node)
+        end
+      end
+
+      # Check if node is a proxy variable read (local var or ivar)
+      def proxy_var_read?(node, proxy_vars)
+        case node
+        when Prism::LocalVariableReadNode
+          proxy_vars.key?(node.name)
+        when Prism::InstanceVariableReadNode
+          proxy_vars.key?(node.name)
+        else
+          false
+        end
+      end
+
+      # Extract the proxy_vars key from a variable read node
+      def predicate_key(node)
+        node.name
+      end
+
+      # Resolve a constant name to the class, with namespace fallback.
+      def resolve_constant(constant_name)
+        Object.const_get(constant_name)
+      rescue NameError
+        resolve_with_namespace(constant_name)
+      end
+
+      def resolve_with_namespace(constant_name)
+        return nil unless @task_class
+
+        namespace_parts = @task_class.name.split("::")
+        namespace_parts.length.downto(0) do |i|
+          prefix = namespace_parts.take(i).join("::")
+          full_name = prefix.empty? ? constant_name : "#{prefix}::#{constant_name}"
+
+          begin
+            return Object.const_get(full_name)
+          rescue NameError
+            next
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/taski/task.rb

@@ -6,6 +6,7 @@ require_relative "execution/registry"
 require_relative "execution/task_wrapper"
 require_relative "progress/layout/tree"
 require_relative "progress/theme/plain"
+require_relative "task_proxy"
 
 module Taski
   # Base class for all tasks in the Taski framework.
@@ -181,12 +182,16 @@ module Taski
           registry = Taski.current_registry
           if registry
             if Thread.current[:taski_fiber_context]
-              # Fiber-based lazy resolution - yield to the worker loop
-              result = Fiber.yield([:need_dep, self, method])
-              if result.is_a?(Array) && result[0] == :_taski_error
-                raise result[1]
+              start_deps = Thread.current[:taski_start_deps]
+              if start_deps&.include?(self)
+                # Lazy resolution via proxy - safe dep confirmed by static analysis
+                TaskProxy.new(self, method)
+              else
+                # Synchronous resolution: dep not in allowlist (unknown or unsafe usage)
+                result = Fiber.yield(Taski::Execution::FiberProtocol::NeedDep.new(self, method))
+                raise result.error if result in Taski::Execution::FiberProtocol::DepError
+                result
               end
-              result
             else
               # Synchronous resolution (clean phase, outside Fiber)
               wrapper = registry.get_or_create(self) do

data/lib/taski/task_proxy.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Taski
+  # Lazy proxy that defers dependency resolution until the value is actually used.
+  # Inherits from BasicObject to minimize available methods, maximizing method_missing delegation.
+  class TaskProxy < BasicObject
+    def initialize(task_class, method)
+      @task_class = task_class
+      @method = method
+      @resolved = false
+      @value = nil
+      @error = nil
+    end
+
+    def __resolve__
+      ::Kernel.raise @error if @error
+      return @value if @resolved
+      @value = ::Fiber.yield(::Taski::Execution::FiberProtocol::NeedDep.new(@task_class, @method))
+      if @value in ::Taski::Execution::FiberProtocol::DepError
+        @error = @value.error
+        ::Kernel.raise @error
+      end
+      @resolved = true
+      @value
+    end
+
+    def __taski_proxy_resolve__
+      __resolve__
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      __resolve__.__send__(name, *args, **kwargs, &block)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      name == :__taski_proxy_resolve__ || __resolve__.respond_to?(name, include_private)
+    end
+
+    def !
+      !__resolve__
+    end
+
+    def ==(other)
+      __resolve__ == other
+    end
+
+    def !=(other)
+      __resolve__ != other
+    end
+
+    def equal?(other)
+      __resolve__.equal?(other)
+    end
+
+    def respond_to?(name, include_private = false)
+      name == :__taski_proxy_resolve__ || __resolve__.respond_to?(name, include_private)
+    end
+  end
+end

data/lib/taski/test_helper.rb

@@ -69,7 +69,7 @@ module Taski
 
         if MockRegistry.mock_for(task_class)
           wrapper.mark_completed(nil) unless wrapper.completed?
-          @completion_queue.push({task_class: task_class, wrapper: wrapper})
+          @completion_queue.push(Taski::Execution::FiberProtocol::TaskCompleted.new(task_class, wrapper))
           return
         end
 

data/lib/taski/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Taski
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 end

data/lib/taski.rb

@@ -4,6 +4,8 @@ require_relative "taski/version"
 require_relative "taski/static_analysis/analyzer"
 require_relative "taski/static_analysis/visitor"
 require_relative "taski/static_analysis/dependency_graph"
+require_relative "taski/static_analysis/start_dep_analyzer"
+require_relative "taski/execution/fiber_protocol"
 require_relative "taski/execution/registry"
 require_relative "taski/execution/task_observer"
 require_relative "taski/execution/execution_facade"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taski
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - ahogappa
@@ -84,6 +84,7 @@ files:
 - lib/taski/env.rb
 - lib/taski/execution/execution_facade.rb
 - lib/taski/execution/executor.rb
+- lib/taski/execution/fiber_protocol.rb
 - lib/taski/execution/registry.rb
 - lib/taski/execution/scheduler.rb
 - lib/taski/execution/task_observer.rb
@@ -106,8 +107,10 @@ files:
 - lib/taski/progress/theme/plain.rb
 - lib/taski/static_analysis/analyzer.rb
 - lib/taski/static_analysis/dependency_graph.rb
+- lib/taski/static_analysis/start_dep_analyzer.rb
 - lib/taski/static_analysis/visitor.rb
 - lib/taski/task.rb
+- lib/taski/task_proxy.rb
 - lib/taski/test_helper.rb
 - lib/taski/test_helper/errors.rb
 - lib/taski/test_helper/minitest.rb