phronomy 0.27.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.27.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/execution/workflow.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 require_relative "workflow_runner"
-require_relative "../../engine/runnable"
+require_relative "../../execution/runnable"
 
 module Phronomy
   # StateChart-style Workflow definition DSL.
@@ -67,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
@@ -121,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__) ? FSMProtocol::FINISH : to
+        destination = to
         @transitions << {
           from: from,
           to: destination,
@@ -186,7 +186,7 @@ module Phronomy
 
         undefined_targets = @transitions
           .map { |transition| transition[:to] }
-          .reject { |target| target == FSMProtocol::FINISH } - all_states
+          .reject { |target| target == Completion::FINISH } - all_states
         unless undefined_targets.empty?
           raise ArgumentError,
             "Workflow transition(s) reference undefined state(s): " \
@@ -207,7 +207,7 @@ module Phronomy
           current = queue.shift
           @transitions.each do |transition|
             next unless transition[:from] == current
-            next if transition[:to] == FSMProtocol::FINISH
+            next if transition[:to] == Completion::FINISH
             next if reachable.include?(transition[:to])
 
             reachable.add(transition[:to])
@@ -222,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/execution/workflow_context.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../engine/concurrency/worker_input_restricted"
+require_relative "../../execution/concurrency/worker_input_restricted"
 
 module Phronomy
   # Module for defining Workflow context data.
@@ -138,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_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

@@ -13,7 +13,7 @@ module Phronomy
     )
     private_constant :WorkflowAdmission
 
-    def initialize(event_loop:)
+    def initialize(channel:)
       super
       @workflow_admissions = {}
     end
@@ -150,13 +150,11 @@ module Phronomy
     end
 
     def post_to_workflow(workflow_instance_id:, event:, payload: nil)
-      @event_loop.__route_execution_event(self) do
+      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
 
-        Phronomy::Event.new(
-          type: event.to_sym, target_id: admission.fsm_session_id, payload: payload
-        )
+        admission.fsm_session_id
       end
     end