phronomy 0.25.0 → 0.27.0

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 Agent, Blocking and Orchestrator admission; 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/concurrency/worker_input_restricted.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Marks framework-managed objects excluded from authorization worker value
+    # snapshots and application behavior handles. Each owning type opts in.
+    # This methodless contract does not validate arbitrary object graphs or
+    # restrict every OffloadPool command. Application-owned opaque values retain
+    # their existing contract (ADR-024/045).
+    # @api private
+    module WorkerInputRestricted
+    end
+  end
+end