phronomy 0.26.0 → 0.27.0

data/lib/phronomy/workflow/persistence/codec.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Workflow
+    module Persistence
+      # Current-format record schemas and conversion for this domain.
+      # @api private
+      module Codec
+        extend Phronomy::Storage::RecordCodec
+
+        WORKFLOW_STATE_RECORD_TYPE = "phronomy.workflow_state"
+        WORKFLOW_STATE_FORMAT_VERSION = "0.1"
+        WORKFLOW_STATE_KEYS = %w[
+          workflow_instance_id workflow_revision snapshot
+        ].freeze
+
+        WORKFLOW_SNAPSHOT_KEYS = %w[fields phase].freeze
+
+        module_function
+
+        def encode_workflow_state(workflow_instance_id:, workflow_revision:, snapshot:)
+          normalized_snapshot = canonicalize_workflow_snapshot(snapshot)
+          validate_workflow_snapshot!(normalized_snapshot)
+          revision = Integer(workflow_revision)
+          unless revision.positive?
+            raise Phronomy::Storage::SerializationError,
+              "Workflow durable revision must be positive"
+          end
+
+          payload = {
+            "workflow_instance_id" => String(workflow_instance_id),
+            "workflow_revision" => revision,
+            "snapshot" => normalized_snapshot
+          }
+          validate_workflow_state_payload!(payload)
+          build_record(WORKFLOW_STATE_RECORD_TYPE, WORKFLOW_STATE_FORMAT_VERSION, payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode Workflow state", error)
+        end
+
+        def decode_workflow_state(record, expected_workflow_instance_id: nil)
+          payload = current_payload!(
+            record,
+            record_type: WORKFLOW_STATE_RECORD_TYPE,
+            format_version: WORKFLOW_STATE_FORMAT_VERSION,
+            keys: WORKFLOW_STATE_KEYS,
+            label: "Workflow state payload"
+          )
+          validate_workflow_state_payload!(payload)
+          workflow_instance_id = payload.fetch("workflow_instance_id")
+          if expected_workflow_instance_id &&
+              workflow_instance_id != expected_workflow_instance_id.to_s
+            raise Phronomy::Storage::SerializationError,
+              "Workflow state identity mismatch: #{workflow_instance_id.inspect} != " \
+              "#{expected_workflow_instance_id.to_s.inspect}"
+          end
+
+          {
+            snapshot: immutable_copy(payload.fetch("snapshot")),
+            revision: payload.fetch("workflow_revision")
+          }.freeze
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode Workflow state", error)
+        end
+
+        def validate_workflow_state_payload!(payload)
+          validate_exact_keys!(payload, WORKFLOW_STATE_KEYS, label: "Workflow state payload")
+          require_nonempty_string!(payload, "workflow_instance_id", label: "Workflow state payload")
+          require_positive_integer!(payload, "workflow_revision", label: "Workflow state payload")
+          validate_workflow_snapshot!(payload.fetch("snapshot"))
+          payload
+        end
+
+        def validate_workflow_snapshot!(snapshot)
+          validate_exact_keys!(snapshot, WORKFLOW_SNAPSHOT_KEYS, label: "Workflow snapshot")
+          unless snapshot.fetch("fields").is_a?(Hash)
+            raise Phronomy::Storage::SerializationError,
+              "Workflow snapshot fields must be a Hash"
+          end
+          phase = snapshot.fetch("phase")
+          unless phase.nil? || phase.is_a?(String)
+            raise Phronomy::Storage::SerializationError,
+              "Workflow snapshot phase must be a String or nil"
+          end
+          Phronomy::CanonicalJSON.dump(snapshot)
+          snapshot
+        rescue ArgumentError => error
+          raise Phronomy::Storage::SerializationError,
+            "Workflow snapshot is not canonical JSON compatible: #{error.message}"
+        end
+
+        def canonicalize_workflow_snapshot(snapshot)
+          source = top_level_string_keys(snapshot, label: "Workflow snapshot")
+          fields = source.fetch("fields")
+          unless fields.is_a?(Hash)
+            raise Phronomy::Storage::SerializationError,
+              "Workflow snapshot fields must be a Hash"
+          end
+          {
+            "fields" => canonicalize_workflow_value(fields),
+            "phase" => source["phase"]&.to_s
+          }
+        end
+
+        def canonicalize_workflow_value(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, child), result|
+              unless key.is_a?(String) || key.is_a?(Symbol)
+                raise Phronomy::Storage::SerializationError,
+                  "Workflow field key must be String or Symbol, got #{key.class}"
+              end
+              string_key = key.to_s
+              if result.key?(string_key)
+                raise Phronomy::Storage::SerializationError,
+                  "duplicate Workflow field key after normalization: #{string_key.inspect}"
+              end
+              result[string_key] = canonicalize_workflow_value(child)
+            end
+          when Array
+            value.map { |child| canonicalize_workflow_value(child) }
+          when Symbol
+            value.to_s
+          when String, Integer, Float, TrueClass, FalseClass, NilClass
+            value
+          else
+            raise Phronomy::Storage::SerializationError,
+              "unsupported Workflow durable value: #{value.class}"
+          end
+        end
+
+        def immutable_copy(value)
+          case value
+          when Hash
+            value.each_with_object({}) do |(key, child), result|
+              result[key.dup.freeze] = immutable_copy(child)
+            end.freeze
+          when Array
+            value.map { |child| immutable_copy(child) }.freeze
+          when String
+            value.dup.freeze
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/workflow/persistence/state_repository.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Workflow
+    module Persistence
+      # Owns Workflow snapshot encoding and the initial revision.
+      # @api private
+      class StateRepository
+        def initialize(view) = @view = view
+
+        def load(workflow_instance_id)
+          @view.atomic do |bound|
+            entry = bound.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_instance_id.to_s)
+            entry && decode(entry, workflow_instance_id)
+          end
+        end
+
+        def save(workflow_instance_id, expected_revision:, snapshot:)
+          expected = expected_revision.nil? ? nil : Integer(expected_revision)
+          revision = expected.nil? ? 1 : expected + 1
+          record = Codec.encode_workflow_state(workflow_instance_id: workflow_instance_id,
+            workflow_revision: revision, snapshot: snapshot)
+          @view.atomic do |bound|
+            records = bound.records(Phronomy::WorkflowStorageSchema::STATES)
+            values = {key: workflow_instance_id.to_s, attributes: {}, record: record}
+            entry = if expected.nil?
+              records.insert(**values, revision: revision)
+            else
+              records.replace(**values, expected_revision: expected, next_revision: revision)
+            end
+            decoded = decode(entry, workflow_instance_id)
+            unless decoded.fetch(:revision) == revision
+              raise Phronomy::Storage::SerializationError, "backend returned another Workflow revision"
+            end
+            revision
+          end
+        rescue Phronomy::Storage::NotFoundError => error
+          raise Phronomy::Storage::ConflictError, error.message
+        end
+
+        def delete(workflow_instance_id, expected_revision:)
+          @view.records(Phronomy::WorkflowStorageSchema::STATES).delete(key: workflow_instance_id.to_s, expected_revision: Integer(expected_revision))
+        end
+
+        private
+
+        def decode(entry, workflow_instance_id)
+          decoded = Codec.decode_workflow_state(entry.record, expected_workflow_instance_id: workflow_instance_id)
+          unless entry.key == workflow_instance_id.to_s && decoded.fetch(:revision) == entry.revision
+            raise Phronomy::Storage::SerializationError, "backend returned another Workflow identity/revision"
+          end
+          decoded
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -32,7 +32,7 @@ module Phronomy
 
       def build
         entry = @entry_point
-        all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
+        all_states = (@declared_states + @wait_state_names + [FSMProtocol::FINISH]).uniq
         auto_transitions = @auto_transitions
         external_events = @external_events
         entry_actions = @entry_actions
@@ -188,7 +188,7 @@ module Phronomy
       end
 
       def public_destination(destination)
-        return :__finish__ if destination == Phronomy::WorkflowRunner::FINISH
+        return :__finish__ if destination == FSMProtocol::FINISH
 
         destination
       end

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

@@ -0,0 +1,9 @@
+# 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/lib/phronomy.rb

@@ -2,12 +2,13 @@
 
 require "zeitwerk"
 require "ruby_llm"
-require_relative "phronomy/ruby_llm_patches"
+require_relative "phronomy/version"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("rag" => "RAG")
 loader.inflector.inflect("fsm_session" => "FSMSession")
+loader.inflector.inflect("fsm_protocol" => "FSMProtocol")
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 loader.inflector.inflect("llm_operation_result" => "LLMOperationResult")
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
@@ -18,104 +19,61 @@ loader.inflector.inflect("llm_input_manifest" => "LLMInputManifest")
 loader.inflector.inflect("llm_input_build_context" => "LLMInputBuildContext")
 loader.inflector.inflect("llm_input_patch" => "LLMInputPatch")
 loader.inflector.inflect("before_llm_input" => "BeforeLLMInput")
-loader.collapse("#{__dir__}/phronomy/engine")
-# Loaded via require_relative before loader.setup; ignore to avoid Zeitwerk constant-name mismatch.
-loader.ignore("#{__dir__}/phronomy/ruby_llm_patches.rb")
-# Persistence backend conformance tests are explicit test support. Keep them out
-# of production eager-load so ordinary `require "phronomy"` never requires RSpec.
+# These responsibility directories do not add a public Ruby namespace.
+%w[common configuration engine generation llm_contract recovery].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/#{directory}")
+end
+# Agent responsibility directories retain the existing Agent constant names.
+%w[
+  context_contract lifecycle execution tool_execution context_assembly
+  journal handoff recovery
+].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/agent/#{directory}")
+end
+
+# A nested root is independent of its enclosing Ruby namespace. Keep existing
+# Phronomy::Workflow, Phronomy::WorkflowContext, and other canonical constants
+# beside the feature they belong to, without aliases or a new partial-load API.
+%w[
+  agent/api
+  agent/lifecycle_contract
+  filter/contract
+  output_parser/contract
+  persistence/api
+  tool/contract
+  workflow/execution
+  workflow/storage_contract
+  multi_agent/storage_contract
+].each do |directory|
+  loader.push_dir("#{__dir__}/phronomy/#{directory}", namespace: Phronomy)
+end
+
+# These files wire composition, reopen namespaces, or patch a dependency.
+loader.ignore(
+  "#{__dir__}/phronomy/configuration/global_configuration.rb",
+  "#{__dir__}/phronomy/agent/composition",
+  "#{__dir__}/phronomy/runtime_composition/agent_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/configuration_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/global_runtime.rb"
+)
+# Persistence conformance support must never make production loading require RSpec.
 loader.ignore(
   "#{__dir__}/phronomy/testing/persistence_contract.rb",
   "#{__dir__}/phronomy/testing/persistence_contract"
 )
 loader.setup
 
-require_relative "phronomy/version"
-require_relative "phronomy/token_usage"
-
-module Phronomy
-  class Error < StandardError; end
-  class ParseError < Error; end
-  class RecursionLimitError < Error; end
-  class ToolError < Error; end
-  class TimeoutError < Error; end
-  class ConfigurationError < Error; end
-  class HandoffError < Error; end
-
-  class TransportError < Error; end
-  class RateLimitError < TransportError; end
-  class AuthenticationError < TransportError; end
-  class ContextLengthError < Error; end
-  class CancellationError < Error; end
-
-  # Raised when a synchronous API would block the EventLoop control thread.
-  class EventLoopReentrancyError < Error; end
-
-  # Backward-compatible error class name for callers that still rescue the old
-  # scheduler-oriented exception. New code should use EventLoopReentrancyError.
-  class SchedulerReentrancyError < EventLoopReentrancyError; end
+require_relative "phronomy/runtime_composition/configuration_defaults"
+require_relative "phronomy/llm_contract/token_usage"
+require_relative "phronomy/configuration/global_configuration"
+require_relative "phronomy/runtime_composition/global_runtime"
 
-  class RuntimeShutdownError < Error; end
-  class RuntimeShutdownReentrancyError < RuntimeShutdownError; end
-
-  class LowConfidenceError < Error
-    attr_reader :result
-
-    def initialize(result)
-      @result = result
-      super("Answer confidence #{result.confidence} is below the required threshold")
-    end
-  end
-
-  class FilterBlockError < Error
-    attr_reader :filter
-
-    def initialize(message, filter: nil)
-      super(message)
-      @filter = filter
-    end
-  end
-
-  class PoolShutdownError < Error; end
-  class BackpressureError < Error; end
-
-  class WorkflowContextOwnershipError < Error; end
-
-  class << self
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    def configure
-      yield configuration
-    end
-
-    def reset_configuration!
-      @configuration = Configuration.new
-    end
-
-    def with_configuration
-      original = @configuration&.dup
-      yield configuration
-    ensure
-      @configuration = original
-    end
-
-    def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
-      previous_grace = @configuration&.event_loop_stop_grace_seconds
-      result = Runtime.reset_default!(timeout: timeout)
-
-      new_configuration = Configuration.new
-      if previous_grace
-        new_configuration.event_loop_stop_grace_seconds = previous_grace
-      end
-      @configuration = new_configuration
-      result
-    end
-  end
-end
+# Explicitly install the Agent namespace extensions even if its factory
+# contract was loaded first. Composition owns both concrete binding and the
+# run_once method definition; neither is required from Agent execution files.
+require_relative "phronomy/agent/api/agent"
+require_relative "phronomy/runtime_composition/agent_defaults"
+require_relative "phronomy/agent/composition/run_once"
 
-# Shared Recovery primitives and Workflow Persistence F1 reconciliation.
-# Entity-specific Agent Recovery is loaded from lib/phronomy/agent.rb when the
-# Agent namespace is materialized.
-require_relative "phronomy/recovery"
-require_relative "phronomy/workflow_recovery"
+# Load the common recovery vocabulary during ordinary application loading.
+require_relative "phronomy/recovery/recovery"

data/scripts/api_snapshot.rb

@@ -36,7 +36,7 @@ PUBLIC_API_ENTRIES = [
   # Beta
   Phronomy::Agent::Handoff,
   Phronomy::Agent::HandoffPolicy,
-  Phronomy::Agent::HandoffRunner,
+  Phronomy::MultiAgent::HandoffRunner,
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Filter::Base,

data/scripts/storage_spi_snapshot.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/phronomy"
+
+# Explicit SPI 2 scope, independent of the Stable/Beta product API snapshot.
+# Private dispatch and domain composition helpers are deliberately excluded.
+surfaces = {
+  Phronomy::Persistence => Phronomy::Persistence.public_instance_methods(false).sort,
+  Phronomy::Storage::Backend => %i[initialize capabilities transaction resources view],
+  Phronomy::Storage::Backends::InMemory => %i[initialize capabilities],
+  Phronomy::Storage::View => %i[records streams blobs check!],
+  Phronomy::Storage::Resource => %i[initialize id kind attributes immutable_attributes indexes unique guard validate_attributes index_values],
+  Phronomy::Storage::Records => %i[resource insert read fetch replace delete scan delete_matching],
+  Phronomy::Storage::Streams => %i[resource append read head delete],
+  Phronomy::Storage::Blobs => %i[resource put_if_absent fetch exist?],
+  Phronomy::Storage::GuardRef => %i[initialize resource key],
+  Phronomy::Storage::Condition::RevisionIs => %i[initialize resource key expected],
+  Phronomy::Storage::Condition::StreamHeadIs => %i[initialize resource stream expected],
+  Phronomy::Storage::Condition::NoRows => %i[initialize resource index equals],
+  Phronomy::Storage::Entry::Record => %i[initialize key revision attributes record],
+  Phronomy::Storage::Entry::Stream => %i[initialize position id record],
+  Phronomy::Storage::Entry::Append => %i[initialize id record],
+  Phronomy::Storage::Entry::Blob => %i[initialize key bytes attributes],
+  Phronomy::Storage::UniqueConstraintError => %i[initialize resource constraint],
+  Phronomy::Storage::ConditionFailedError => %i[initialize condition]
+}
+snapshot = {spi_version: 2, capabilities: Phronomy::Storage::Backend::REQUIRED_CAPABILITIES,
+            surfaces: surfaces.to_h { |type, names| [type.name, names.sort.to_h { |name| [name, type.instance_method(name).parameters] }] }}
+json = JSON.pretty_generate(snapshot) + "\n"
+if ARGV.include?("--write")
+  File.write(File.expand_path("../spec/fixtures/storage_spi_v2_snapshot.json", __dir__), json)
+else
+  puts json
+end

data/sig/phronomy/agent.rbs

@@ -190,7 +190,6 @@ module Phronomy
       def self.max_iterations: (?Integer value) -> Integer
       def self.cache_instructions: (?bool enabled) -> bool?
       def self.max_output_tokens: (?Integer value) -> Integer?
-      def self.context_window: (?Integer value) -> Integer?
       def self.context_policy: () -> ContextPolicy
                              | (ContextPolicy policy) -> ContextPolicy
       def self.agent_definition: () -> Hash[Symbol, untyped]

data/sig/phronomy/execution_receiver.rbs

@@ -0,0 +1,34 @@
+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/handoff.rbs

@@ -25,14 +25,16 @@ module Phronomy
       def selectable_categories: () -> Array[Symbol]
       def to_h: () -> Hash[String, Hash[String, String]]
     end
+  end
 
+  module MultiAgent
     class HandoffRunner
       MAX_HANDOFFS: Integer
 
       attr_reader main_agent: ::Phronomy::Agent::Base
-      attr_reader handoffs: Array[Handoff]
+      attr_reader handoffs: Array[::Phronomy::Agent::Handoff]
 
-      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[Handoff]) -> void
+      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[::Phronomy::Agent::Handoff]) -> void
       def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
       def result: (String execution_id) -> Hash[Symbol, untyped]
       def cancel: (String execution_id) -> Hash[Symbol, untyped]

data/sig/phronomy/multi_agent.rbs

@@ -1,5 +1,23 @@
 module Phronomy
   module MultiAgent
+    class SharedState
+      class KnowledgeStore
+        def self.new: () -> instance
+        def read_all: () -> Array[Hash[Symbol, untyped]]
+        def write: (agent: untyped, content: untyped, cycle: untyped) -> nil
+        def size: () -> Integer
+      end
+
+      def self.new: () -> instance
+      def self.member: (singleton(::Phronomy::Agent::Base) klass, ?instruction: untyped) -> Array[Hash[Symbol, untyped]]
+      def self.coordination: (?untyped text) -> untyped
+      def self.max_cycles: (?untyped value) -> Integer?
+      def self.timeout: (?untyped value) -> Float?
+      def self.terminate_when: () ?{ (KnowledgeStore) -> untyped } -> untyped
+      def self.aggregate: () ?{ (KnowledgeStore) -> untyped } -> untyped
+      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    end
+
     class Orchestrator < ::Phronomy::Agent::Base
       def self.subagent: (Symbol | String name, singleton(::Phronomy::Agent::Base) agent_class, ?on_error: Symbol, ?inherit_knowledge: bool) -> untyped
       def self.registered_subagents: () -> Hash[Symbol | String, untyped]