phronomy 0.25.0 → 0.26.0

data/lib/phronomy/engine/concurrency/offload_pool.rb

@@ -13,7 +13,7 @@ module Phronomy
     # synchronous call. Phronomy deliberately does not classify the workload by
     # cause; the application decides whether a unit of work is EventLoop-safe.
     #
-    # Logical waits are different. Waiting for another Phronomy Task, Agent,
+    # Logical waits are different. Waiting for another Phronomy TaskResult, Agent,
     # Workflow, ToolInvocation, timer, or FSMSession must remain an explicit
     # EventLoop/FSMSession continuation and must not consume an OffloadPool worker.
     # See ADR-010.
@@ -22,7 +22,7 @@ module Phronomy
     #
     # 1. The total number of worker OS threads is capped.
     # 2. Queue depth is bounded (backpressure when the pool is saturated).
-    # 3. Per-operation timeouts and cancellation settle the caller-facing Task.
+    # 3. Per-operation timeouts and cancellation settle the caller-facing TaskResult.
     # 4. Operations that settle after worker execution has started are tracked as
     #    abandoned until that worker returns.
     # 5. Metrics expose active work, queue depth, cumulative abandonment,
@@ -43,7 +43,7 @@ module Phronomy
     class OffloadPool
       # Private execution record for one submitted synchronous operation.
       #
-      # Caller-facing completion is represented exclusively by {Phronomy::Task}.
+      # Caller-facing completion is represented exclusively by {Phronomy::TaskResult}.
       # This object owns only OffloadPool-specific execution state: queue timing,
       # worker-start linearization, submit timeout/cancellation, abandonment, and
       # the submitted block itself.
@@ -77,6 +77,7 @@ module Phronomy
           @submitted_at = submitted_at ||
             Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @mutex = Mutex.new
+          @timer_subscriptions = Subscriptions.new
 
           # Explicit submit cancellation is operation-wide. Deadline-only tokens are
           # promoted to cancel! by OffloadPool#submit using the Runtime timer queue.
@@ -92,19 +93,26 @@ module Phronomy
           @mutex.synchronize { @settled }
         end
 
-        # @return [Boolean] true when the submit-time deadline settled the Task
+        # Registration can race logical completion. Dispose the timer even when
+        # settlement occurred while schedule was returning.
+        def schedule(timer_queue, seconds:, &callback)
+          timer_queue.schedule(seconds: seconds, &callback)
+          @timer_subscriptions.add { timer_queue.cancel(callback) }
+        end
+
+        # @return [Boolean] true when the submit-time deadline settled the TaskResult
         # @api private
         def timed_out?
           @mutex.synchronize { @timed_out }
         end
 
-        # @return [Boolean] true when submit cancellation settled the Task
+        # @return [Boolean] true when submit cancellation settled the TaskResult
         # @api private
         def cancelled?
           @mutex.synchronize { @cancelled }
         end
 
-        # @return [Boolean] true when timeout/cancellation settled the Task after
+        # @return [Boolean] true when timeout/cancellation settled the TaskResult after
         #   worker execution had started. The worker is not forcibly interrupted.
         # @api private
         def abandoned?
@@ -117,7 +125,7 @@ module Phronomy
           @wait_time || 0.0
         end
 
-        # Settles the caller-facing Task with a submit-time timeout.
+        # Settles the caller-facing TaskResult with a submit-time timeout.
         #
         # The worker is not interrupted. If execution has already started, the
         # operation is marked abandoned and the worker's eventual result is discarded.
@@ -132,7 +140,7 @@ module Phronomy
           end
         end
 
-        # Settles the caller-facing Task because its submit cancellation token was
+        # Settles the caller-facing TaskResult because its submit cancellation token was
         # cancelled. Cancellation never injects Thread#raise into the worker.
         #
         # @return [Boolean] true when this call won settlement
@@ -201,7 +209,7 @@ module Phronomy
             complete_with_value!(@block.call)
           rescue Exception => e # rubocop:disable Lint/RescueException
             # Rescue all Exception subclasses so non-StandardError raises still
-            # settle the Task and unblock waiters.
+            # settle the TaskResult and unblock waiters.
             complete_with_error!(e)
             raise if e.is_a?(SignalException) || e.is_a?(SystemExit)
           end
@@ -280,6 +288,7 @@ module Phronomy
         end
 
         def detach_submit_cancellation
+          @timer_subscriptions.close
           return unless @cancellation_token && @cancellation_callback
 
           @cancellation_token.send(
@@ -325,20 +334,20 @@ module Phronomy
 
       # Submits synchronous off-EventLoop work to the pool.
       #
-      # Returns a {Phronomy::Task} immediately after queue admission; the block
+      # Returns a {Phronomy::TaskResult} immediately after queue admission; the block
       # runs on a worker thread. Do not submit logical waits (for example waiting
-      # for a child Agent Task) merely to make them asynchronous; those belong to
+      # for a child Agent TaskResult) merely to make them asynchronous; those belong to
       # FSMSession/EventLoop completion events.
       #
       # A submit-time +timeout+ is an operation-wide deadline measured from the
-      # start of this method, including queue wait. The timer settles the Task and
+      # start of this method, including queue wait. The timer settles the TaskResult and
       # notifies +on_complete+ without forcibly interrupting a running worker. If
       # the deadline fires before worker execution starts, the block is skipped.
       # If it fires after execution starts, the private Operation is marked
       # abandoned and the eventual worker result is discarded.
       #
       # The submit +cancellation_token+ is also operation-wide. Explicit
-      # cancellation settles the Task immediately. A token with a monotonic
+      # cancellation settles the TaskResult immediately. A token with a monotonic
       # deadline is attached to the Runtime timer queue so deadline expiry becomes
       # explicit cancellation without adding a polling Thread. Cancellation before
       # execution skips the block; cancellation after execution starts abandons
@@ -356,7 +365,7 @@ module Phronomy
       # @param on_full [Symbol] +:wait+, +:raise+, or +:timeout+
       # @param full_timeout [Numeric, nil] queue-admission timeout for +on_full: :timeout+
       # @yield block containing synchronous work
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @raise [Phronomy::ConfigurationError] when a timer is required but no
       #   timer queue provider is configured
       # @raise [Phronomy::PoolShutdownError] when the pool has been shut down
@@ -421,7 +430,7 @@ module Phronomy
 
             # Arm before queue admission so the deadline includes time spent waiting
             # for a queue slot.
-            timer_queue.schedule(seconds: remaining) { operation.fire_timeout! }
+            operation.schedule(timer_queue, seconds: remaining) { operation.fire_timeout! }
           end
 
           if cancellation_remaining
@@ -431,7 +440,7 @@ module Phronomy
               cancellation_token.cancel!
               return task
             end
-            timer_queue.schedule(seconds: remaining) { cancellation_token.cancel! }
+            operation.schedule(timer_queue, seconds: remaining) { cancellation_token.cancel! }
           end
 
           # Cancellation/timeout can race with timer registration. Do not enqueue

data/lib/phronomy/engine/concurrency/operation_binding.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Connects explicit invocation controls before operation admission. Its token
+    # is private: cancelling it never cancels the application's shared tokens.
+    # Used by Execution's Agent and Blocking adapters; it owns no worker.
+    # @api private
+    class OperationBinding
+      attr_reader :token, :scope
+
+      def initialize(invocation_context:, cancellation_token:)
+        if !invocation_context.nil? && !invocation_context.is_a?(InvocationContext)
+          raise TypeError, "invocation_context must be a Phronomy::InvocationContext or nil"
+        end
+        @scope = invocation_context&.__execution_scope
+        @token = CancellationToken.new
+        @subscriptions = Subscriptions.new
+        [invocation_context&.cancellation_token, cancellation_token].compact.uniq.each do |source|
+          @subscriptions.cancellation(source) { @token.cancel! }
+        end
+        if !@scope && invocation_context&.deadline
+          @subscriptions.after(invocation_context.deadline.remaining_seconds) { @token.cancel! }
+        end
+        @token.cancel! if @scope && !@scope.__open?
+      end
+
+      def bind(result)
+        result.__bind_execution(@scope)
+        track(result)
+      end
+
+      def track(result)
+        @subscriptions.result(result) { @subscriptions.close }
+        result
+      end
+
+      def close
+        @subscriptions.close
+      end
+    end
+  end
+end

data/lib/phronomy/engine/concurrency/physical_completion_task.rb

@@ -2,16 +2,16 @@
 
 module Phronomy
   module Concurrency
-    # Private Task specialization used when logical completion and physical
+    # Private TaskResult specialization used when logical completion and physical
     # completion are intentionally different boundaries.
     #
-    # Offload cancellation/timeout may settle the caller-facing Task while a
+    # Offload cancellation/timeout may settle the caller-facing TaskResult while a
     # worker is still executing. EventLoop supervision must observe the later
     # physical-completion boundary without adding domain-specific state to the
-    # public Phronomy::Task contract.
+    # public Phronomy::TaskResult contract.
     #
     # @api private
-    class PhysicalCompletionTask < Phronomy::Task
+    class PhysicalCompletionTask < Phronomy::TaskResult
       # @api private
       def initialize(name: nil, parent: nil)
         super
@@ -63,64 +63,6 @@ module Phronomy
         self
       end
 
-      # Preserves the physical-completion boundary across Task#map.
-      #
-      # A mapped PhysicalCompletionTask is physically complete only after both:
-      # 1. the source Task's underlying physical work is complete; and
-      # 2. the mapping callback itself has finished running.
-      #
-      # The second condition is required because Task completion callbacks may run
-      # on the OffloadPool worker that settles the source Task. Propagating the
-      # source physical signal immediately could otherwise let EventLoop declare
-      # the owning Execution quiescent while the mapping callback is still active.
-      #
-      # Logical success/failure semantics intentionally remain the same as
-      # Phronomy::Task#map.
-      #
-      # @api public
-      def map(&block)
-        raise ArgumentError, "map requires a block" unless block
-
-        mapped = self.class.deferred(name: "#{name}-mapped", parent: parent)
-        propagation_mutex = Mutex.new
-        source_physical_complete = physical_complete?
-        mapping_complete = false
-
-        mark_mapped_physical_if_ready = lambda do
-          ready = propagation_mutex.synchronize do
-            source_physical_complete && mapping_complete
-          end
-          mapped.mark_physical_complete! if ready
-        end
-
-        on_physical_complete do
-          propagation_mutex.synchronize { source_physical_complete = true }
-          mark_mapped_physical_if_ready.call
-        end
-
-        on_complete do |value, error|
-          if error
-            propagation_mutex.synchronize { mapping_complete = true }
-            mark_mapped_physical_if_ready.call
-            mapped.fail(error)
-            next
-          end
-
-          begin
-            transformed = block.call(value)
-            propagation_mutex.synchronize { mapping_complete = true }
-            mark_mapped_physical_if_ready.call
-            mapped.complete(transformed)
-          rescue => mapped_error
-            propagation_mutex.synchronize { mapping_complete = true }
-            mark_mapped_physical_if_ready.call
-            mapped.fail(mapped_error)
-          end
-        end
-
-        mapped
-      end
-
       private
 
       def deliver_physical_callback(callback)

data/lib/phronomy/engine/concurrency/result_collector.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Shared input-order fan-in and terminal arbitration. No application code or
+    # completion callback runs while this collector's lock is held.
+    # @api private
+    class ResultCollector
+      def initialize(size, &finished)
+        @mutex = Mutex.new
+        @outcomes = Array.new(size)
+        @remaining = size
+        @closed = false
+        @sources = {}.compare_by_identity
+        @subscriptions = Subscriptions.new
+        @finished = finished
+      end
+
+      def while_open
+        @mutex.synchronize { yield unless @closed }
+      end
+
+      def open?
+        @mutex.synchronize { !@closed }
+      end
+
+      def watch(index, result, &recorded)
+        subscribe = @mutex.synchronize do
+          return if @closed
+
+          first = !@sources.key?(result)
+          (@sources[result] ||= {})[index] = recorded
+          first
+        end
+        if subscribe
+          @subscriptions.result(result) { receive(result) }
+        elsif result.done?
+          receive(result)
+        end
+      end
+
+      def finish(kind)
+        snapshot = @mutex.synchronize do
+          return false if @closed
+          return false if kind == :completed && @remaining > 0
+
+          @closed = true
+          snapshot_locked
+        end
+        deliver(kind, snapshot)
+        true
+      end
+
+      private
+
+      def receive(result)
+        status, value, error = result.__snapshot
+        callbacks = []
+        snapshot = @mutex.synchronize do
+          return if @closed
+
+          @sources.fetch(result).each do |index, callback|
+            next if @outcomes[index]
+
+            @outcomes[index] = TaskResult::Outcome.new(index: index,
+              status: status, value: value, error: error)
+            @remaining -= 1
+            callbacks << callback if callback
+          end
+          if @remaining.zero?
+            @closed = true
+            snapshot_locked
+          end
+        end
+        deliver(:completed, snapshot) if snapshot
+        callbacks.each(&:call)
+      end
+
+      def snapshot_locked
+        @outcomes.each_with_index.map do |outcome, index|
+          outcome || TaskResult::Outcome.new(index: index,
+            status: :unfinished, value: nil, error: nil)
+        end.freeze
+      end
+
+      def deliver(kind, snapshot)
+        finished = @mutex.synchronize do
+          @sources.clear
+          @outcomes.clear
+          callback = @finished
+          @finished = nil
+          callback
+        end
+        @subscriptions.close
+        finished.call(kind, snapshot)
+      end
+    end
+  end
+end

data/lib/phronomy/engine/concurrency/result_composition.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Shared map/flat_map implementation, including the private physical-work
+    # boundary. Observing a result never mutates that result or its cancellation.
+    # @api private
+    class ResultComposition
+      def initialize(source, flatten:, &block)
+        @source = source
+        @scope = source.__execution_scope
+        @flatten = flatten
+        @block = block
+        physical = flatten || source.respond_to?(:on_physical_complete)
+        klass = physical ? PhysicalCompletionTask : TaskResult
+        @result = klass.deferred(name: "#{source.name}-#{flatten ? "flat-mapped" : "mapped"}",
+          parent: source.parent).__bind_execution(@scope)
+        @mutex = Mutex.new
+        @phase = :waiting
+        @source_physical = !source.respond_to?(:on_physical_complete)
+        @work_done = false
+        @inner_physical = true
+        @subscriptions = Subscriptions.new
+      end
+
+      def start
+        unless @source_physical
+          @source.on_physical_complete do
+            @mutex.synchronize { @source_physical = true }
+            finish_physical
+          end
+        end
+        @subscriptions.result(@source) { receive_source }
+        if @scope
+          @subscriptions.cancellation(@scope.__cancellation_token) { suppress }
+          suppress unless @scope.__open?
+        end
+        @result
+      end
+
+      private
+
+      def receive_source
+        status, value, error = @source.__snapshot
+        if status != :completed
+          started = @mutex.synchronize do
+            next false unless @phase == :waiting
+            @phase = :finished
+            @work_done = true
+            true
+          end
+          if started
+            finish_physical
+            propagate(status, value, error)
+            @subscriptions.close
+          end
+          return
+        end
+
+        claim = lambda do
+          @mutex.synchronize do
+            next false unless @phase == :waiting
+            @phase = :running
+            true
+          end
+        end
+        allowed = @scope ? @scope.__while_open(&claim) : claim.call
+        unless allowed
+          suppress
+          return
+        end
+
+        begin
+          transformed = @block.call(value)
+          if @flatten && !transformed.is_a?(TaskResult)
+            raise TypeError, "flat_map block must return a Phronomy::TaskResult"
+          end
+          track_inner_physical(transformed) if @flatten
+          @mutex.synchronize do
+            @work_done = true
+            @phase = :inner unless @phase == :suppressed
+          end
+          finish_physical
+          if @flatten
+            unless @result.done?
+              @subscriptions.result(transformed) do
+                propagate(*transformed.__snapshot)
+                @subscriptions.close
+              end
+            end
+          else
+            @result.complete(transformed)
+            @subscriptions.close
+          end
+        rescue => error
+          @mutex.synchronize { @work_done = true }
+          finish_physical
+          @result.fail(error)
+          @subscriptions.close
+        ensure
+          # Even an exception deliberately outside StandardError cannot leave
+          # already-finished Ruby work looking physically active.
+          @mutex.synchronize { @work_done = true }
+          finish_physical
+        end
+      end
+
+      def suppress
+        @mutex.synchronize do
+          @work_done = true if @phase == :waiting
+          @phase = :suppressed
+        end
+        finish_physical
+        @result.cancel!(@scope.__cancellation_error)
+        @subscriptions.close
+      end
+
+      def propagate(status, value, error)
+        case status
+        when :completed then @result.complete(value)
+        when :cancelled then @result.cancel!(error)
+        when :failed then @result.fail(error)
+        end
+      end
+
+      def track_inner_physical(inner)
+        return unless inner.respond_to?(:on_physical_complete)
+        return unless inner.__execution_scope.equal?(@scope)
+
+        @mutex.synchronize { @inner_physical = false }
+        inner.on_physical_complete do
+          @mutex.synchronize { @inner_physical = true }
+          finish_physical
+        end
+      end
+
+      def finish_physical
+        return unless @result.respond_to?(:mark_physical_complete!)
+
+        done = @mutex.synchronize { @source_physical && @work_done && @inner_physical }
+        @result.mark_physical_complete! if done
+      end
+    end
+  end
+end

data/lib/phronomy/engine/concurrency/subscriptions.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Disposable registrations. add also handles synchronous notification during
+    # registration: cleanup added after close is performed immediately.
+    # @api private
+    class Subscriptions
+      def initialize
+        @mutex = Mutex.new
+        @closed = false
+        @cleanup = []
+      end
+
+      def add(&cleanup)
+        dispose = @mutex.synchronize do
+          if @closed
+            true
+          else
+            @cleanup << cleanup
+            false
+          end
+        end
+        cleanup.call if dispose
+      end
+
+      def result(result, &callback)
+        result.on_complete(&callback)
+        add { result.__unsubscribe(callback) }
+      end
+
+      def cancellation(token, &callback)
+        return unless token
+
+        token.on_cancel(&callback)
+        add { token.send(:unregister_cancel_callback, callback) }
+        remaining = token.remaining_monotonic_seconds
+        if token.cancelled?
+          callback.call
+        elsif remaining
+          after(remaining, &callback)
+        end
+      end
+
+      def after(seconds, &callback)
+        if seconds <= 0
+          callback.call
+          return
+        end
+        timer = Phronomy::Runtime.instance.timer_queue
+        timer.schedule(seconds: seconds, &callback)
+        add { timer.cancel(callback) }
+      end
+
+      def close
+        cleanup = @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          current = @cleanup
+          @cleanup = []
+          current
+        end
+        cleanup.each(&:call)
+      end
+    end
+  end
+end

data/lib/phronomy/engine/event_loop.rb

@@ -114,7 +114,7 @@ module Phronomy
     end
 
     def register(fsm_session, completion: nil)
-      if current? && !completion.is_a?(Phronomy::Task)
+      if current? && !completion.is_a?(Phronomy::TaskResult)
         raise Phronomy::Error,
           "Cannot call a synchronous invocation API from an EventLoop action. " \
           "Schedule work asynchronously instead."
@@ -413,14 +413,14 @@ module Phronomy
       end
     end
 
-    # Registers a caller-facing Task that observes the authoritative terminal
+    # Registers a caller-facing TaskResult that observes the authoritative terminal
     # outcome of one logical Agent execution. Waiters are Runtime-only and are
     # never persisted or rehydrated.
     # @api private
     def register_agent_completion_waiter(execution_id, task)
       assert_event_loop_thread!
-      unless task.is_a?(Phronomy::Task)
-        raise ArgumentError, "Agent completion waiter must be a Phronomy::Task"
+      unless task.is_a?(Phronomy::TaskResult)
+        raise ArgumentError, "Agent completion waiter must be a Phronomy::TaskResult"
       end
 
       key = execution_id.to_s
@@ -432,7 +432,7 @@ module Phronomy
     end
 
     # Atomically detaches all process-local completion waiters at authoritative
-    # terminal delivery. A fallback Task is included for pre-install terminal
+    # terminal delivery. A fallback TaskResult is included for pre-install terminal
     # paths that never acquired a live execution directory entry.
     # @api private
     def take_agent_completion_waiters(execution_id, fallback: nil)
@@ -1027,7 +1027,7 @@ module Phronomy
       if pending_waiters.any?
         error = Phronomy::ExecutionRehydrationRequiredError.new(
           "Runtime terminated while Agent execution remained nonterminal; " \
-          "process-local Task handles are not rehydrated"
+          "process-local TaskResult handles are not rehydrated"
         )
         pending_waiters.each { |waiter| complete_waiter(waiter, error) }
       end
@@ -1037,7 +1037,7 @@ module Phronomy
     def complete_waiter(waiter, payload)
       return unless waiter
 
-      if waiter.is_a?(Phronomy::Task)
+      if waiter.is_a?(Phronomy::TaskResult)
         payload.is_a?(Exception) ? waiter.fail(payload) : waiter.complete(payload)
       else
         waiter.push(payload)

data/lib/phronomy/engine/fsm_session.rb

@@ -6,7 +6,7 @@ module Phronomy
   # Event-driven execution wrapper for a single FSM session.
   #
   # All public methods are called from the Runtime-owned EventLoop thread.
-  # FSMSession owns FSM execution only; it does not own external Task handles,
+  # FSMSession owns FSM execution only; it does not own external TaskResult handles,
   # activity tokens, callback correlation, or domain-specific stale-event policy.
   class FSMSession
     class IdentityReservation
@@ -195,9 +195,9 @@ module Phronomy
     end
 
     def apply_synchronous_action_result!(result, state_name)
-      if result.is_a?(Phronomy::Task)
+      if result.is_a?(Phronomy::TaskResult)
         raise Phronomy::InvalidAsyncEntryActionError,
-          "Entry action for state #{state_name.inspect} returned Phronomy::Task. " \
+          "Entry action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
           "Start the asynchronous operation, register its callback/listener, " \
           "and return the WorkflowContext or nil."
       end

data/lib/phronomy/engine/runtime/timer_queue.rb

@@ -44,6 +44,17 @@ module Phronomy
         end
       end
 
+      # Remove this registration without changing another user's timers. A
+      # callback already taken by fire_due may still run; owners arbitrate once.
+      # @api private
+      def cancel(callback)
+        @mutex.synchronize do
+          before = @heap.length
+          @heap.delete_if { |(_, registered)| registered == callback }
+          before != @heap.length
+        end
+      end
+
       # Executes all callbacks whose deadline is due. Must be called by EventLoop.
       def fire_due
         callbacks = @mutex.synchronize do