phronomy 0.26.0 → 0.28.0

data/lib/phronomy/vector_store/base.rb

@@ -1,87 +1,156 @@
 # frozen_string_literal: true
 
+require_relative "invalid_result_error"
+
 module Phronomy
   module VectorStore
-    # Public extension SPI for vector stores.
-    #
-    # Backends implement the synchronous add/search/remove/clear/size contract.
-    # Phronomy supplies async convenience methods through {AsyncBackend}; blocking
-    # backend work is offloaded through the framework-owned bounded OffloadPool.
-    #
+    # Owns synchronous operations, input validation and the public result shape.
+    # Backends implement protected perform_* operations and embedding_dimension.
+    # No execution client, SDK or embedding provider is selected by this class.
     # @api public
     class Base
-      include AsyncBackend
-
-      # Add a document with its vector embedding.
-      #
-      # @param id                 [String] unique document identifier
-      # @param embedding          [Array<Float>] vector embedding
-      # @param metadata           [Hash] arbitrary metadata
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # Validate before invoking the backend. Cancellation is checked before the
+      # write, never reported after a successful write. No operation is retried.
+      # @param id [String]
+      # @param embedding [Array<Numeric>]
+      # @param metadata [Hash]
+      # @param cancellation_token [#raise_if_cancelled!, nil]
+      # @return [self]
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
-        raise NotImplementedError, "#{self.class}#add is not implemented"
+        validate_id!(id)
+        raise ArgumentError, "metadata must be a Hash" unless metadata.is_a?(Hash)
+        vector = validate_vector!(embedding)
+        perform_add(id: id, embedding: vector, metadata: metadata, cancellation_token: cancellation_token)
+        self
       end
 
-      # Return the k most similar documents to the query embedding.
-      #
-      # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer] number of results
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-      # @return [Array<Hash>] each element: { id:, score:, metadata: }
+      # Return at most k results ordered by descending similarity. Malformed
+      # backend output raises InvalidResultError; transport errors propagate.
+      # @param query_embedding [Array<Numeric>]
+      # @param k [Integer, String] positive integer or its decimal string
+      # @param cancellation_token [#raise_if_cancelled!, nil]
+      # @return [Array<Hash>]
       # @api public
       def search(query_embedding:, k: 5, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
-        raise NotImplementedError, "#{self.class}#search is not implemented"
+        limit = validate_k!(k)
+        vector = validate_vector!(query_embedding)
+        results = perform_search(query_embedding: vector, k: limit, cancellation_token: cancellation_token)
+        validate_results!(results, limit)
+        results
       end
 
-      # Remove a single document by id.
-      #
-      # @param id [String] document identifier
+      # Remove a document; an absent id is a successful no-op.
+      # @param id [String]
+      # @return [self]
       # @api public
       def remove(id:)
-        raise NotImplementedError, "#{self.class}#remove is not implemented"
+        validate_id!(id)
+        perform_remove(id: id)
+        self
       end
 
-      # Remove all documents.
+      # Clear documents without changing the configured dimension.
+      # @return [self]
       # @api public
       def clear
-        raise NotImplementedError, "#{self.class}#clear is not implemented"
+        perform_clear
+        self
       end
 
-      # Return the number of documents stored.
-      #
-      # @return [Integer]
+      # @return [Integer] non-negative document count
       # @api public
       def size
-        raise NotImplementedError, "#{self.class}#size is not implemented"
+        count = perform_size
+        unless count.is_a?(Integer) && count >= 0
+          raise InvalidResultError, "size must return a non-negative Integer"
+        end
+        count
+      end
+
+      protected
+
+      # @return [Integer, nil] nil delegates dimension enforcement to the backend
+      # @api public
+      def embedding_dimension
+        nil
+      end
+
+      # Storage extension point; inputs have passed common validation.
+      # @api public
+      def perform_add(id:, embedding:, metadata:, cancellation_token:)
+        raise NotImplementedError, "#{self.class}#perform_add is not implemented"
+      end
+
+      # Search extension point; return the documented result hashes in order.
+      # @api public
+      def perform_search(query_embedding:, k:, cancellation_token:)
+        raise NotImplementedError, "#{self.class}#perform_search is not implemented"
+      end
+
+      # @api public
+      def perform_remove(id:)
+        raise NotImplementedError, "#{self.class}#perform_remove is not implemented"
+      end
+
+      # @api public
+      def perform_clear
+        raise NotImplementedError, "#{self.class}#perform_clear is not implemented"
+      end
+
+      # @api public
+      def perform_size
+        raise NotImplementedError, "#{self.class}#perform_size is not implemented"
       end
 
       private
 
-      # Validates that embedding has the expected dimension.
-      # Raises ArgumentError if sizes differ.
-      # A nil expected_dimension is a no-op (dimension not yet established).
-      def validate_embedding_dimension!(embedding, expected_dimension)
-        return unless expected_dimension
+      def validate_id!(id)
+        raise ArgumentError, "id must be a String" unless id.is_a?(String)
+      end
 
-        actual = embedding.size
-        return if actual == expected_dimension
+      def finite_real?(value)
+        value.is_a?(Numeric) && value.real? && value.finite? && value.to_f.finite?
+      end
 
-        raise ArgumentError,
-          "Embedding dimension mismatch: expected #{expected_dimension}, got #{actual}"
+      def validate_vector!(embedding)
+        unless embedding.is_a?(Array) && embedding.all? { |value| finite_real?(value) }
+          raise ArgumentError, "embedding must be an Array of finite real numbers"
+        end
+        dimension = embedding_dimension
+        if dimension && embedding.size != dimension
+          raise ArgumentError, "Embedding dimension mismatch: expected #{dimension}, got #{embedding.size}"
+        end
+        embedding.map(&:to_f)
       end
 
-      # Validates that k is a positive integer.
-      # Accepts any value accepted by Integer() (e.g. "5"), but raises
-      # ArgumentError for non-integer strings, zero, and negative values.
       def validate_k!(k)
-        int_k = Integer(k)
-        raise ArgumentError, "k must be a positive integer, got #{int_k}" unless int_k >= 1
-        int_k
-      rescue ArgumentError => e
-        raise ArgumentError, "k must be a positive integer: #{e.message}"
+        valid = k.is_a?(Integer) || (k.is_a?(String) && k.match?(/\A\+?\d+\z/))
+        unless valid
+          raise ArgumentError, "k must be a positive integer"
+        end
+        value = k.is_a?(String) ? Integer(k, 10) : k
+        raise ArgumentError, "k must be a positive integer" unless value >= 1
+        value
+      end
+
+      def validate_results!(results, limit)
+        unless results.is_a?(Array) && results.size <= limit
+          raise InvalidResultError, "search must return an Array with at most k results"
+        end
+        previous = Float::INFINITY
+        results.each do |result|
+          unless result.is_a?(Hash) && result[:id].is_a?(String) &&
+              result[:metadata].is_a?(Hash) && finite_real?(result[:score])
+            raise InvalidResultError, "search results require a String id, finite score and Hash metadata"
+          end
+          if result[:score] > previous
+            raise InvalidResultError, "search results must be ordered by descending score"
+          end
+          previous = result[:score]
+        end
       end
     end
   end

data/lib/phronomy/vector_store/invalid_result_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module VectorStore
+    # A backend could not produce a valid synchronous result. This includes
+    # malformed external responses that must not be replaced with success values.
+    # @api public
+    class InvalidResultError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/vector_store.rb

@@ -1,23 +1,8 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Vector store infrastructure: backends, embeddings adapters, document loaders,
-  # and text splitters.
-  #
-  # Sub-namespaces are auto-loaded by Zeitwerk:
-  #   Phronomy::VectorStore::Base
-  #   Phronomy::VectorStore::InMemory
-  #   Phronomy::VectorStore::Pgvector
-  #   Phronomy::VectorStore::RedisSearch
-  #   Phronomy::VectorStore::Embeddings::Base
-  #   Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings
-  #   Phronomy::VectorStore::Loader::Base
-  #   Phronomy::VectorStore::Loader::PlainTextLoader
-  #   Phronomy::VectorStore::Loader::MarkdownLoader
-  #   Phronomy::VectorStore::Loader::CsvLoader
-  #   Phronomy::VectorStore::Splitter::Base
-  #   Phronomy::VectorStore::Splitter::FixedSizeSplitter
-  #   Phronomy::VectorStore::Splitter::RecursiveSplitter
+  # Synchronous vector search/storage contract, its backends and execution client.
+  # Embeddings and Documents are independent Phronomy responsibilities.
   module VectorStore
   end
 end

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow/completion.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Workflow
+    # Workflow definition contract shared with its execution runner.
+    # @api private
+    module Completion
+      FINISH = :__finish__
+    end
+  end
+end

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

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
 require_relative "workflow_runner"
-require_relative "runnable"
+require_relative "../../execution/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)
@@ -63,7 +67,7 @@ module Phronomy
     def _apply_invocation_context(config, invocation_context)
       effective = config.merge(invocation_context: invocation_context)
       if effective[:cancellation_token].nil?
-        token = invocation_context.effective_timeout_token
+        token = Phronomy::InvocationControls.effective_timeout_token(invocation_context)
         effective = effective.merge(cancellation_token: token) if token
       end
       effective
@@ -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
@@ -119,7 +121,7 @@ module Phronomy
       # They may start asynchronous work and register listeners, but returning
       # 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
         @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 == Completion::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] == Completion::FINISH
             next if reachable.include?(transition[:to])
 
             reachable.add(transition[:to])
@@ -220,7 +222,7 @@ module Phronomy
           "[Phronomy] Workflow has unreachable state(s): " \
           "#{unreachable.sort.inspect}. These states can never be entered " \
           "from the initial state #{entry_point.inspect}."
-        logger = Phronomy.configuration.logger
+        logger = Phronomy::RuntimeSettings.current.logger
         logger ? logger.warn(message) : Kernel.warn(message)
       end
     end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Workflow's synchronous callback rules, independent of FSM representation.
+  # Guards and transition actions may receive the triggering application event;
+  # actions may initiate async work but must not return a TaskResult.
+  # @api private
+  module WorkflowActionRules
+    module_function
+
+    def allowed?(guard, context, event)
+      guard.nil? || call_with_optional_event(guard, context, event)
+    end
+
+    def transition(callable, context, event, metadata:)
+      return context if callable.nil?
+
+      result = call_with_optional_event(callable, context, event)
+      if result.is_a?(Phronomy::TaskResult)
+        raise Phronomy::InvalidAsyncTransitionActionError,
+          "Transition action " \
+            "#{metadata[:from].inspect} --#{metadata[:event].inspect}--> " \
+            "#{metadata[:to].inspect} returned Phronomy::TaskResult. " \
+            "Start the asynchronous operation, register its callback/listener, " \
+            "and return the WorkflowContext or nil."
+      end
+      workflow_context_result?(result) ? result : context
+    end
+
+    def entry(callable, context, state_name)
+      result = callable.call(context)
+      if result.is_a?(Phronomy::TaskResult)
+        raise Phronomy::InvalidAsyncEntryActionError,
+          "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
+      result
+    end
+
+    def apply_entry(callable, context, state_name)
+      result = entry(callable, context, state_name)
+      workflow_context_result?(result) ? result : context
+    end
+
+    def exit(callable, context, state_name)
+      result = callable.call(context)
+      if result.is_a?(Phronomy::TaskResult)
+        raise Phronomy::InvalidAsyncEntryActionError,
+          "Exit action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
+            "Exit actions are synchronous Run-to-Completion callbacks."
+      end
+      nil
+    end
+
+    def call_with_optional_event(callable, context, event)
+      parameters = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+      (parameters.length >= 2) ? callable.call(context, event) : callable.call(context)
+    end
+    private_class_method :call_with_optional_event
+
+    def workflow_context_result?(result)
+      result.respond_to?(:set_graph_metadata)
+    end
+    private_class_method :workflow_context_result?
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/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, {})
@@ -134,7 +138,7 @@ module Phronomy
     # dispatch thread. All Workflow execution APIs now use that same path; there
     # is no caller-thread synchronous exception.
     def _assert_write_permitted!
-      return if Phronomy::Runtime.in_event_loop_context?
+      return if Phronomy::WaitPolicy.blocking_forbidden?
 
       raise Phronomy::WorkflowContextOwnershipError,
         "WorkflowContext fields may only be mutated from the EventLoop dispatch " \

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_environment.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Workflow-owned connection requirements. Progress, admission and durable
+  # outcome interpretation remain in Workflow; composition selects transport.
+  # @api private
+  class WorkflowExecutionEnvironment
+    class << self
+      def install_provider(provider)
+        raise ArgumentError, "Workflow execution provider must be callable" unless provider.respond_to?(:call)
+        @provider = provider
+      end
+
+      def current
+        @provider&.call || raise(Phronomy::ConfigurationError, "Workflow execution environment has not been configured")
+      end
+    end
+
+    def registry = raise(NotImplementedError)
+    def existing_registry = raise(NotImplementedError)
+    def executing? = raise(NotImplementedError)
+    def submit(**options, &operation) = raise(NotImplementedError)
+    def compile_transitions(**definition) = raise(NotImplementedError)
+    def build_session(**options) = raise(NotImplementedError)
+    def register_session(session, completion:) = raise(NotImplementedError)
+  end
+end

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

@@ -0,0 +1,186 @@
+# 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(channel:)
+      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)
+      route_event(type: event.to_sym, payload: payload) do
+        admission = @workflow_admissions[workflow_instance_id.to_s]
+        next unless admission&.state == :executing && admission.fsm_session_id
+
+        admission.fsm_session_id
+      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