phronomy 0.27.0 → 0.29.0

data/lib/phronomy/recovery/recovery.rb

@@ -1,186 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Small private Recovery semantic/primitives layer shared by Agent and
-  # Workflow recovery. Entity-specific orchestration remains outside this module.
-  # @api private
-  module Recovery
-    RESUMABLE = :resumable
-    RECONCILABLE = :reconcilable
-    RESOLUTION_REQUIRED = :resolution_required
-    DISPOSITIONS = [RESUMABLE, RECONCILABLE, RESOLUTION_REQUIRED].freeze
-
-    ALLOWED_OUTCOMES = %i[succeeded failed not_performed].freeze
-    # Internal shorthand used by the Agent Recovery implementation. This is not
-    # a public API constant; both names refer to the same frozen value.
-    OUTCOMES = ALLOWED_OUTCOMES
-
-    MISSING = Object.new.freeze
-
-    Classification = Data.define(
-      :disposition, :reason, :subject, :allowed_outcomes, :facts
-    ) do
-      def initialize(
-        disposition:,
-        reason:,
-        subject: nil,
-        allowed_outcomes: [],
-        facts: {}
-      )
-        normalized = disposition.to_sym
-        unless Phronomy::Recovery::DISPOSITIONS.include?(normalized)
-          raise ArgumentError, "unknown Recovery disposition: #{disposition.inspect}"
-        end
-        super(
-          disposition: normalized,
-          reason: reason.to_sym,
-          subject: subject && Phronomy::Recovery.normalize_subject(subject),
-          allowed_outcomes: Array(allowed_outcomes).map(&:to_sym).freeze,
-          facts: Phronomy::Values::Immutable.copy(facts || {})
-        )
-      end
-    end
-
-    module_function
-
-    def normalize_outcome(outcome)
-      normalized = outcome.to_sym
-      unless OUTCOMES.include?(normalized)
-        raise ArgumentError, "unsupported Recovery outcome: #{outcome.inspect}"
-      end
-      normalized
-    end
-
-    def validate_resolution_material!(outcome:, result_present:, error_present:)
-      normalized = normalize_outcome(outcome)
-      case normalized
-      when :succeeded
-        raise ArgumentError, "Recovery :succeeded requires result:" unless result_present
-        raise ArgumentError, "Recovery :succeeded forbids error:" if error_present
-      when :failed
-        raise ArgumentError, "Recovery :failed requires error:" unless error_present
-        raise ArgumentError, "Recovery :failed forbids result:" if result_present
-      when :not_performed
-        if result_present || error_present
-          raise ArgumentError, "Recovery :not_performed accepts neither result: nor error:"
-        end
-      end
-      true
-    end
-
-    def normalize_subject(subject)
-      hash = subject.to_h.transform_keys(&:to_sym)
-      type = hash.fetch(:type).to_sym
-      normalized = {type: type}
-      case type
-      when :llm_call
-        normalized[:llm_call_id] = required_id(hash, :llm_call_id)
-      when :tool_invocation
-        normalized[:tool_invocation_id] = required_id(hash, :tool_invocation_id)
-      when :persistence_operation
-        # Persistence operation references are structural only. Do not introduce
-        # a generic durable operation/recovery identity here.
-        normalized[:entity] = hash.fetch(:entity).to_sym
-      else
-        raise ArgumentError, "unsupported Recovery subject type: #{type.inspect}"
-      end
-      normalized.freeze
-    end
-
-    def subject_key(subject)
-      normalized = normalize_subject(subject)
-      case normalized.fetch(:type)
-      when :llm_call
-        "llm_call:#{normalized.fetch(:llm_call_id)}"
-      when :tool_invocation
-        "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
-      when :persistence_operation
-        "persistence_operation:#{normalized.fetch(:entity)}"
-      end
-    end
-
-    def subject_equal?(left, right)
-      normalize_subject(left) == normalize_subject(right)
-    rescue ArgumentError, KeyError
-      false
-    end
-
-    # Compare authoritative current state with a known pre/post revision pair.
-    # This is deliberately small: callers still validate entity-specific content.
-    def compare_revisions(current_revision:, expected_pre_revision:, intended_post_revision:)
-      current = current_revision
-      return :post_state if current == intended_post_revision
-      return :pre_state if current == expected_pre_revision
-
-      :conflict
-    end
-
-    # Generic F1 helper for revisioned snapshot repositories such as Workflow.
-    # Some repositories return a newly allocated revision only after save, so
-    # callers may not know the intended post revision in advance. In that case
-    # the intended snapshot plus a revision different from the expected pre
-    # revision identifies the post-state.
-    def compare_revisioned_snapshot(
-      record:,
-      expected_pre_revision:,
-      intended_snapshot:,
-      intended_post_revision: nil
-    )
-      return :pre_state if record.nil? && expected_pre_revision.nil?
-      return :conflict if record.nil?
-
-      revision = fetch_value(record, :revision)
-      snapshot = fetch_value(record, :snapshot)
-      normalized_snapshot = normalize_value(snapshot)
-      normalized_intended = normalize_value(intended_snapshot)
-
-      if intended_post_revision
-        if revision == intended_post_revision &&
-            normalized_snapshot == normalized_intended
-          return :post_state
-        end
-      elsif normalized_snapshot == normalized_intended &&
-          revision != expected_pre_revision
-        return :post_state
-      end
-
-      return :pre_state if revision == expected_pre_revision
-
-      :conflict
-    end
-
-    def normalize_value(value)
-      case value
-      when Hash
-        value.each_with_object({}) do |(key, child), result|
-          result[key.to_s] = normalize_value(child)
-        end
-      when Array
-        value.map { |child| normalize_value(child) }
-      when Symbol
-        value.to_s
-      else
-        value
-      end
-    end
-
-    def fetch_value(record, key)
-      return nil unless record
-      return record.public_send(key) if record.respond_to?(key)
-      return record[key] if record.respond_to?(:key?) && record.key?(key)
-      string_key = key.to_s
-      return record[string_key] if record.respond_to?(:key?) && record.key?(string_key)
-
-      nil
-    end
-
-    def required_id(hash, key)
-      value = hash.fetch(key)
-      text = value.to_s
-      raise ArgumentError, "#{key} must not be empty" if text.empty?
-
-      text.freeze
-    end
-    private_class_method :required_id
-  end
-end

data/lib/phronomy/tool/contract/tool_error.rb

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

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

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    module Embeddings
-      # Public extension SPI for embedding adapters.
-      #
-      # Concrete implementations override {#embed}. Phronomy owns the async
-      # bridge: {#embed_async} routes the synchronous implementation through the
-      # bounded OffloadPool and returns a {Phronomy::TaskResult}.
-      #
-      # @api public
-      class Base
-        # Embed the given text and return a vector representation.
-        #
-        # @param text               [String] the text to embed
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-        # @return [Array<Float>] the embedding vector
-        # @api public
-        def embed(text, cancellation_token = nil)
-          cancellation_token&.raise_if_cancelled!
-          raise NotImplementedError, "#{self.class}#embed is not implemented"
-        end
-
-        # Submits an {#embed} call to {OffloadPool}.
-        #
-        # @param text               [String]
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-        # @param timeout            [Numeric, nil] operation-wide submit timeout
-        # @return [Phronomy::TaskResult]
-        # @api public
-        def embed_async(text, cancellation_token = nil, timeout: nil)
-          Phronomy::Runtime.instance.offload.submit(
-            timeout: timeout,
-            cancellation_token: cancellation_token,
-            on_full: :raise
-          ) do
-            embed(text, cancellation_token)
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module VectorStore
-    module Embeddings
-      # Embeddings adapter backed by RubyLLM.
-      #
-      # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
-      # +Array<Float>+.
-      #
-      # @example Default model
-      #   embeddings = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new
-      #   vector = embeddings.embed("Hello, world!")
-      #
-      # @example Explicit model
-      #   embeddings = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
-      #   vector = embeddings.embed("Hello, world!")
-      class RubyLLMEmbeddings < Base
-        # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
-        # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
-        # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
-        #                                          (useful for locally hosted models not in the registry)
-        # @api public
-        def initialize(model: nil, provider: nil, assume_model_exists: false)
-          @model = model
-          @provider = provider
-          @assume_model_exists = assume_model_exists
-        end
-
-        # Embed text via RubyLLM.
-        #
-        # @param text               [String]
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-        # @return [Array<Float>]
-        # @api public
-        def embed(text, cancellation_token = nil)
-          cancellation_token&.raise_if_cancelled!
-          opts = {}
-          opts[:model] = @model if @model
-          opts[:provider] = @provider if @provider
-          opts[:assume_model_exists] = true if @assume_model_exists
-          RubyLLM.embed(text, **opts).vectors
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -1,205 +0,0 @@
-# frozen_string_literal: true
-
-require "state_machines"
-
-module Phronomy
-  class Workflow
-    # Builds the anonymous state-machine Class used by WorkflowRunner.
-    #
-    # This class compiles Workflow topology into state_machines declarations.
-    # It intentionally does not await Tasks, register completion callbacks,
-    # cancel external work, or interpret application event payloads.
-    #
-    # @api private
-    class PhaseMachineBuilder
-      def initialize(
-        entry_point:,
-        declared_states:,
-        wait_state_names:,
-        external_events:,
-        entry_actions:,
-        auto_transitions:,
-        exit_actions:
-      )
-        @entry_point = entry_point
-        @declared_states = declared_states
-        @wait_state_names = wait_state_names
-        @external_events = external_events
-        @entry_actions = entry_actions
-        @auto_transitions = auto_transitions
-        @exit_actions = exit_actions
-      end
-
-      def build
-        entry = @entry_point
-        all_states = (@declared_states + @wait_state_names + [FSMProtocol::FINISH]).uniq
-        auto_transitions = @auto_transitions
-        external_events = @external_events
-        entry_actions = @entry_actions
-        exit_actions = @exit_actions
-        condition_builder = method(:build_transition_condition)
-        entry_callback_builder = method(:build_entry_callback)
-        exit_callback_builder = method(:build_exit_callback)
-        transition_callback = build_transition_action_callback
-
-        Class.new do
-          attr_accessor(
-            :context,
-            :current_event,
-            :selected_transition_action,
-            :selected_transition_metadata
-          )
-
-          state_machine :phase, initial: entry do
-            all_states.each { |state_name| state state_name }
-
-            event :state_completed do
-              auto_transitions.each do |transition_definition|
-                transition(
-                  transition_definition[:from] => transition_definition[:to],
-                  :if => condition_builder.call(transition_definition)
-                )
-              end
-            end
-
-            external_events.each do |event_name, transitions|
-              event event_name do
-                transitions.each do |transition_definition|
-                  transition(
-                    transition_definition[:from] => transition_definition[:to],
-                    :if => condition_builder.call(transition_definition)
-                  )
-                end
-              end
-            end
-
-            entry_actions.each do |state_name, callables|
-              callables.each do |callable|
-                after_transition(
-                  to: state_name,
-                  &entry_callback_builder.call(callable, state_name)
-                )
-              end
-            end
-
-            # Both source exit callbacks and the transition action are
-            # before_transition callbacks. Register exits first to preserve the
-            # required exit -> transition action -> entry ordering.
-            exit_actions.each do |state_name, callables|
-              callables.each do |callable|
-                before_transition(
-                  from: state_name,
-                  &exit_callback_builder.call(callable, state_name)
-                )
-              end
-            end
-
-            before_transition(&transition_callback)
-          end
-        end
-      rescue => error
-        raise ArgumentError, "Failed to build phase machine: #{error.message}"
-      end
-
-      private
-
-      def build_transition_condition(transition_definition)
-        guard = transition_definition[:guard]
-        action = transition_definition[:action]
-        metadata = {
-          from: transition_definition[:from],
-          event: transition_definition[:event],
-          to: public_destination(transition_definition[:to])
-        }.freeze
-
-        ->(machine) {
-          matched =
-            guard.nil? ||
-            call_with_optional_event(
-              guard,
-              machine.context,
-              machine.current_event
-            )
-
-          if matched
-            machine.selected_transition_action = action
-            machine.selected_transition_metadata = metadata
-          end
-          matched
-        }
-      end
-
-      def build_transition_action_callback
-        ->(machine) {
-          callable = machine.selected_transition_action
-          unless callable.nil?
-            metadata = machine.selected_transition_metadata || {}
-            result = call_with_optional_event(
-              callable,
-              machine.context,
-              machine.current_event
-            )
-            if result.is_a?(Phronomy::TaskResult)
-              raise Phronomy::InvalidAsyncTransitionActionError,
-                transition_task_error_message(metadata)
-            end
-            machine.context = result if workflow_context_result?(result)
-          end
-        }
-      end
-
-      def build_entry_callback(callable, state_name)
-        ->(machine) {
-          result = callable.call(machine.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
-          machine.context = result if workflow_context_result?(result)
-        }
-      end
-
-      def build_exit_callback(callable, state_name)
-        ->(machine) {
-          result = callable.call(machine.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
-        }
-      end
-
-      def call_with_optional_event(callable, context, event)
-        parameters =
-          if callable.respond_to?(:parameters)
-            callable.parameters
-          else
-            callable.method(:call).parameters
-          end
-        accepts_event = parameters.length >= 2
-        accepts_event ? callable.call(context, event) : callable.call(context)
-      end
-
-      def workflow_context_result?(result)
-        result.respond_to?(:set_graph_metadata)
-      end
-
-      def public_destination(destination)
-        return :__finish__ if destination == FSMProtocol::FINISH
-
-        destination
-      end
-
-      def transition_task_error_message(metadata)
-        "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
-    end
-  end
-end

data/lib/phronomy/workflow/storage_contract/workflow_storage_schema.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Domain-owned Workflow metadata, loadable without the Workflow runtime.
-  # @api private
-  module WorkflowStorageSchema
-    STATES = Phronomy::Storage::Resource.new(id: "workflow.states", kind: :records)
-  end
-end

data/sig/phronomy/execution_receiver.rbs

@@ -1,34 +0,0 @@
-module Phronomy
-  # Internal Engine contract (ADR-042); not an application extension SPI.
-  class ExecutionReceiver
-    def self.for: (EventLoop event_loop) -> instance
-    def self.existing_for: (Runtime runtime) -> instance?
-    def initialize: (event_loop: EventLoop) -> void
-    def __bound_to?: (EventLoop event_loop) -> bool
-    def idle?: () -> bool
-    def deliver: (untyped message) -> untyped
-    def shutdown: (error: Exception?) -> untyped
-    def session_retired: (String fsm_session_id, reason: Symbol) -> untyped
-
-    private
-
-    def synchronize: [V] () { () -> V } -> V
-    def admit: [V] () { () -> V } -> V
-    def post_message: (untyped message, ?admission: bool, ?completion: TaskResult[untyped]?) -> bool
-    def assert_event_loop_thread!: () -> void
-  end
-
-  class EventLoop
-    def __execution_receiver: (key: untyped) -> ExecutionReceiver?
-    def __register_execution_receiver: (key: untyped, receiver: ExecutionReceiver) -> ExecutionReceiver
-    def __synchronize_execution_state: [V] () { () -> V } -> V
-    def __admit_execution: [V] (ExecutionReceiver receiver) { () -> V } -> V
-    def __post_execution: (ExecutionReceiver receiver, untyped message, ?admission: bool, ?completion: TaskResult[untyped]?) -> bool
-    def __route_execution_event: (ExecutionReceiver receiver) { () -> untyped } -> bool
-    def __receiver_cleanup_complete?: () -> bool
-  end
-
-  class Runtime
-    def __event_loop_if_initialized: () -> EventLoop?
-  end
-end

data/sig/phronomy/llm_adapter.rbs

@@ -1,11 +0,0 @@
-module Phronomy
-  module LLMAdapter
-    class Base
-      def complete: (untyped chat, String? message, ?config: Hash[untyped, untyped]) -> untyped
-      def stream: (untyped chat, String? message, ?config: Hash[untyped, untyped]) { (untyped chunk) -> void } -> untyped
-    end
-
-    class RubyLLM < Base
-    end
-  end
-end

data/sig/phronomy/runtime.rbs

@@ -1,76 +0,0 @@
-module Phronomy
-  class TaskResult[A]
-    class Outcome[V]
-      attr_reader index: Integer
-      attr_reader status: (:completed | :failed | :cancelled | :unfinished)
-      attr_reader value: V?
-      attr_reader error: Exception?
-    end
-
-    def self.completed: [V] (V value, ?name: String?) -> TaskResult[V]
-                      | (?name: String?) -> TaskResult[nil]
-    def self.failed: (Exception error, ?name: String?) -> TaskResult[untyped]
-    def self.all_settled: [V] (Array[TaskResult[V]] results) -> TaskResult[Array[Outcome[V]]]
-    attr_reader name: String?
-    attr_reader parent: TaskResult[untyped]?
-
-    def status: () -> (:pending | :completed | :failed | :cancelled)
-    def done?: () -> bool
-    def alive?: () -> bool
-    def wait_result: (?timeout: Numeric?) -> A
-    def on_complete: () { (A?, Exception?) -> void } -> self
-    def map: [B] () { (A) -> B } -> TaskResult[B]
-    def flat_map: [B] () { (A) -> TaskResult[B] } -> TaskResult[B]
-  end
-
-  class Execution
-    attr_reader invocation_context: InvocationContext
-
-    def self.run_async: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> TaskResult[Array[TaskResult::Outcome[V]]]
-    def self.run: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> Array[TaskResult::Outcome[V]]
-    def observe: [V] (TaskResult[V] source_result) -> TaskResult[V]
-  end
-
-  class ExecutionTimeoutError < TimeoutError
-    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
-  end
-
-  class ExecutionCancellationError < CancellationError
-    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
-    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
-  end
-
-  module Concurrency
-    class CancellationToken
-      def self.timeout_after: (Numeric seconds) -> CancellationToken
-      def initialize: (?monotonic_deadline: Float?) -> void
-      def remaining_monotonic_seconds: () -> Float?
-      def on_cancel: () { () -> void } -> self
-      def cancel!: () -> self
-      def cancelled?: () -> bool
-      def raise_if_cancelled!: (?String message) -> nil
-    end
-  end
-end
-
-module Phronomy
-  class InvocationContext
-    attr_reader user_id: String?
-    attr_reader cancellation_token: Concurrency::CancellationToken?
-    attr_reader deadline: untyped
-    attr_reader token_budget: Integer?
-    attr_reader approval_policy: untyped
-    attr_reader redaction_policy: untyped
-    attr_reader task_id: String?
-    attr_reader parent_task_id: String?
-
-    def initialize: (?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
-  end
-end
-
-module Phronomy
-  module Blocking
-    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { () -> V } -> TaskResult[V]
-  end
-end