phronomy 0.25.0 → 0.27.0

data/lib/phronomy/vector_store/async_backend.rb

@@ -12,7 +12,7 @@ module Phronomy
     # the framework rather than by each backend.
     #
     # A future genuine native-async backend may adapt its completion into a
-    # {Phronomy::Task} without an OffloadPool worker, but native async override is
+    # {Phronomy::TaskResult} without an OffloadPool worker, but native async override is
     # not part of the current backend SPI.
     #
     # @api private
@@ -24,7 +24,7 @@ module Phronomy
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -42,7 +42,7 @@ module Phronomy
       # @param k                  [Integer]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -59,7 +59,7 @@ module Phronomy
       # @param id                 [String]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def remove_async(id:, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -75,7 +75,7 @@ module Phronomy
       #
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def clear_async(cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -7,7 +7,7 @@ module Phronomy
       #
       # Concrete implementations override {#embed}. Phronomy owns the async
       # bridge: {#embed_async} routes the synchronous implementation through the
-      # bounded OffloadPool and returns a {Phronomy::Task}.
+      # bounded OffloadPool and returns a {Phronomy::TaskResult}.
       #
       # @api public
       class Base
@@ -27,7 +27,7 @@ module Phronomy
         # @param text               [String]
         # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
         # @param timeout            [Numeric, nil] operation-wide submit timeout
-        # @return [Phronomy::Task]
+        # @return [Phronomy::TaskResult]
         # @api public
         def embed_async(text, cancellation_token = nil, timeout: nil)
           Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.25.0"
+  VERSION = "0.27.0"
 end

data/lib/phronomy/{workflow.rb → workflow/execution/workflow.rb}

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 require_relative "workflow_runner"
-require_relative "runnable"
+require_relative "../../engine/runnable"
 
 module Phronomy
   # StateChart-style Workflow definition DSL.
   class Workflow
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     include Phronomy::Runnable
 
     def self.define(context_class, persistence: nil, &block)
@@ -72,8 +76,6 @@ module Phronomy
     public
 
     class Builder
-      FINISH = Phronomy::WorkflowRunner::FINISH
-
       def initialize(context_class, persistence: nil)
         @context_class = context_class
         @persistence = persistence
@@ -93,7 +95,7 @@ module Phronomy
       #
       # Entry actions are synchronous Run-to-Completion callbacks. To start
       # asynchronous work, register its listener/callback inside the action and
-      # return the context or nil. Returning Phronomy::Task is an error.
+      # return the context or nil. Returning Phronomy::TaskResult is an error.
       def state(name, action: nil)
         @declared_states << name
         entry(name, action) if action
@@ -117,9 +119,9 @@ module Phronomy
       # Transition actions are synchronous Run-to-Completion callbacks executed
       # after the source exit callbacks and before the target entry callbacks.
       # They may start asynchronous work and register listeners, but returning
-      # Phronomy::Task is an error; completion must arrive as a later event.
+      # Phronomy::TaskResult is an error; completion must arrive as a later event.
       def transition(from:, to:, guard: nil, on: nil, action: nil)
-        destination = (to == :__finish__) ? FINISH : to
+        destination = (to == :__finish__) ? FSMProtocol::FINISH : to
         @transitions << {
           from: from,
           to: destination,
@@ -184,7 +186,7 @@ module Phronomy
 
         undefined_targets = @transitions
           .map { |transition| transition[:to] }
-          .reject { |target| target == FINISH } - all_states
+          .reject { |target| target == FSMProtocol::FINISH } - all_states
         unless undefined_targets.empty?
           raise ArgumentError,
             "Workflow transition(s) reference undefined state(s): " \
@@ -205,7 +207,7 @@ module Phronomy
           current = queue.shift
           @transitions.each do |transition|
             next unless transition[:from] == current
-            next if transition[:to] == FINISH
+            next if transition[:to] == FSMProtocol::FINISH
             next if reachable.include?(transition[:to])
 
             reachable.add(transition[:to])

data/lib/phronomy/{workflow_context.rb → workflow/execution/workflow_context.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 module Phronomy
   # Module for defining Workflow context data.
   #
@@ -12,6 +14,8 @@ module Phronomy
   # evaluation, return a replacement WorkflowContext, or return +:consume+ to
   # discard a stale/unrelated event without firing a transition.
   module WorkflowContext
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     def self.included(base)
       base.extend(ClassMethods)
       base.instance_variable_set(:@fields, {})

data/lib/phronomy/workflow/execution/workflow_context_ownership_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../../common/error"
+
+module Phronomy
+  class WorkflowContextOwnershipError < Error; end
+end

data/lib/phronomy/workflow/execution/workflow_execution_registry.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Workflow-owned segment admission and routing, mutated only on EventLoop.
+  # @api private
+  class WorkflowExecutionRegistry < Phronomy::ExecutionReceiver
+    # Workflow-owned process-local Workflow execution-segment admission. The
+    # owner token is a Runtime coordination capability, not a domain identity or
+    # routing identity. fsm_session_id is bound only after durable load/hydration
+    # completes and a concrete FSMSession has been constructed.
+    WorkflowAdmission = Data.define(
+      :workflow_instance_id, :owner_token, :fsm_session_id, :state
+    )
+    private_constant :WorkflowAdmission
+
+    def initialize(event_loop:)
+      super
+      @workflow_admissions = {}
+    end
+
+    def post(command, admission: false, completion: nil)
+      post_message(command, admission: admission, completion: completion)
+    end
+
+    def deliver(command)
+      assert_event_loop_thread!
+      command.runner.deliver_on_event_loop(command)
+    end
+
+    def idle?
+      !workflow_admission_transition_in_progress_locked?
+    end
+
+    def session_retired(fsm_session_id, reason:)
+      assert_event_loop_thread!
+      mark_workflow_recovery_required_for_session(fsm_session_id) if reason == :recovery_required
+    end
+
+    def shutdown(error:)
+      synchronize { @workflow_admissions.clear }
+    end
+
+    # Reserves one logical Workflow execution segment before durable load or
+    # hydration. The owner token is independent from any later FSMSession id.
+    # @api private
+    def admit_workflow(workflow_instance_id, owner_token:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      raise ArgumentError, "workflow_instance_id must not be empty" if key.empty?
+      raise ArgumentError, "owner_token is required" unless owner_token
+
+      admit do
+        if @workflow_admissions.key?(key)
+          raise Phronomy::Error,
+            "Workflow instance #{key.inspect} already has a live execution segment"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: key.freeze,
+          owner_token: owner_token,
+          fsm_session_id: nil,
+          state: :admitting
+        )
+      end
+      true
+    end
+
+    # Binds the concrete routing identity after admission and durable hydration.
+    # @api private
+    def bind_workflow_session(workflow_instance_id, owner_token:, fsm_session_id:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      fsm_key = fsm_session_id.to_s
+      raise ArgumentError, "fsm_session_id must not be empty" if fsm_key.empty?
+
+      synchronize do
+        current = @workflow_admissions.fetch(key) do
+          raise Phronomy::Error, "Workflow instance #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token) && current.fsm_session_id.nil?
+          raise Phronomy::Error, "stale Workflow admission bind for #{key.inspect}"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: current.workflow_instance_id,
+          owner_token: current.owner_token,
+          fsm_session_id: fsm_key.freeze,
+          state: :executing
+        )
+      end
+      true
+    end
+
+    # @api private
+    def mark_workflow_admission(workflow_instance_id, owner_token:, state:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      next_state = state.to_sym
+      unless %i[executing persisting_terminal recovery_required].include?(next_state)
+        raise ArgumentError, "unsupported Workflow admission state: #{next_state.inspect}"
+      end
+
+      synchronize do
+        current = @workflow_admissions.fetch(key) do
+          raise Phronomy::Error, "Workflow instance #{key.inspect} has no Runtime admission"
+        end
+        unless current.owner_token.equal?(owner_token)
+          raise Phronomy::Error, "stale Workflow admission update for #{key.inspect}"
+        end
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: current.workflow_instance_id,
+          owner_token: current.owner_token,
+          fsm_session_id: current.fsm_session_id,
+          state: next_state
+        )
+      end
+      true
+    end
+
+    # Owner-aware release. A competing or stale attempt cannot release the
+    # current Workflow execution segment.
+    # @api private
+    def release_workflow(workflow_instance_id, owner_token:)
+      assert_event_loop_thread!
+      key = workflow_instance_id.to_s
+      synchronize do
+        current = @workflow_admissions[key]
+        next false unless current&.owner_token&.equal?(owner_token)
+
+        @workflow_admissions.delete(key)
+        true
+      end
+    end
+
+    # Read-only diagnostics used by internal tests and routing assertions.
+    def workflow_admission_owner(workflow_instance_id)
+      synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.owner_token
+      end
+    end
+
+    def workflow_admission_fsm_session_id(workflow_instance_id)
+      synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.fsm_session_id
+      end
+    end
+
+    def workflow_admission_state(workflow_instance_id)
+      synchronize do
+        @workflow_admissions[workflow_instance_id.to_s]&.state
+      end
+    end
+
+    def post_to_workflow(workflow_instance_id:, event:, payload: nil)
+      @event_loop.__route_execution_event(self) do
+        admission = @workflow_admissions[workflow_instance_id.to_s]
+        next unless admission&.state == :executing && admission.fsm_session_id
+
+        Phronomy::Event.new(
+          type: event.to_sym, target_id: admission.fsm_session_id, payload: payload
+        )
+      end
+    end
+
+    private
+
+    def mark_workflow_recovery_required_for_session(fsm_session_id)
+      synchronize do
+        key, admission = @workflow_admissions.find do |_workflow_instance_id, candidate|
+          candidate.fsm_session_id == fsm_session_id.to_s
+        end
+        return false unless admission
+
+        @workflow_admissions[key] = WorkflowAdmission.new(
+          workflow_instance_id: admission.workflow_instance_id,
+          owner_token: admission.owner_token,
+          fsm_session_id: nil,
+          state: :recovery_required
+        )
+      end
+      true
+    end
+
+    def workflow_admission_transition_in_progress_locked?
+      @workflow_admissions.values.any? do |admission|
+        %i[admitting executing persisting_terminal].include?(admission.state)
+      end
+    end
+  end
+end