phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/{tool_invocation.rb → tool_execution/tool_invocation.rb}

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../execution/concurrency/worker_input_restricted"
+
+require "digest"
 require "securerandom"
 
 module Phronomy
   module Agent
     class ToolInvocation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       AuthorizationOutcome = Data.define(
         :tool_invocation_id, :decision, :facts, :reason, :error, :cancelled
       ) do
@@ -74,6 +79,20 @@ module Phronomy
         :origin,
         :metadata
 
+      # Stable identity used both before dispatch and when rebuilding facts.
+      # This does not construct, authorize, or execute a Tool invocation.
+      # @api private
+      def self.semantic_id(execution_id:, llm_call_id:, tool_call_id:, tool_name:)
+        source = [
+          "tool_invocation",
+          execution_id.to_s,
+          llm_call_id.to_s,
+          tool_call_id.to_s,
+          tool_name.to_s
+        ].join("\0")
+        "tool_invocation-#{Digest::SHA256.hexdigest(source)}".freeze
+      end
+
       def self.missing(
         execution_id:,
         agent:,
@@ -135,6 +154,16 @@ module Phronomy
         @phase = phase
       end
 
+      # Restores a newly constructed invocation from materialized saved facts.
+      # Recovery owns snapshot decoding and identity matching. This operation
+      # owns state application; it neither dispatches nor reevaluates approval.
+      # @api private
+      def restore_state!(status:, result: nil, approval_item: nil)
+        restore_saved_state!(status, result)
+        restore_approval_evidence!(approval_item)
+        self
+      end
+
       def handle_fsm_event(event)
         case event.type
         when :authorization_completed
@@ -167,11 +196,7 @@ module Phronomy
       def validate!
         return self if terminal?
 
-        validated, schema_error = if @tool.respond_to?(:validate_and_coerce, true)
-          @tool.send(:validate_and_coerce, @raw_arguments)
-        else
-          [@raw_arguments, nil]
-        end
+        validated, schema_error = @tool.validate_arguments(@raw_arguments)
 
         if schema_error
           if @tool.class.respond_to?(:on_schema_error) && @tool.class.on_schema_error == :raise
@@ -195,27 +220,21 @@ module Phronomy
         self
       end
 
-      def start_authorization(runtime: Phronomy::Runtime.instance, &callback)
+      def start_authorization(environment:, &callback)
         raise ArgumentError, "start_authorization requires a callback" unless callback
 
         command = authorization_command
         evaluator = self.class
         tool_invocation_id = @id.to_s.freeze
-        pool = runtime.pool(
-          :authorization,
-          size: Phronomy.configuration.authorization_pool_size,
-          queue_size: Phronomy.configuration.authorization_queue_size
-        )
         timeout = @config.fetch(
           :authorization_timeout,
-          Phronomy.configuration.authorization_timeout
+          Phronomy::Agent::Settings.current.authorization_timeout
         )
-        operation = pool.submit(
+        operation = environment.submit_authorization(
           timeout: timeout,
-          cancellation_token: @config[:cancellation_token],
-          on_full: :raise
+          cancellation_token: @config[:cancellation_token]
         ) { evaluator.send(:evaluate_authorization_command, command) }
-        runtime.event_loop.supervise_agent_operation(@execution_id, operation)
+        environment.registry.supervise_agent_operation(@execution_id, operation)
         operation.on_complete do |outcome, error|
           callback.call(
             error ? evaluator.send(:authorization_failure_result, tool_invocation_id, error) : outcome
@@ -229,7 +248,7 @@ module Phronomy
         self
       end
 
-      def start_execution(runtime: Phronomy::Runtime.instance, &callback)
+      def start_execution(environment:, &callback)
         raise ArgumentError, "start_execution requires a callback" unless callback
         unless dispatchable?
           callback.call(ExecutionOutcome.new(
@@ -241,45 +260,24 @@ module Phronomy
           return self
         end
 
-        trace_handle = nil
-        case @tool.class.execution_mode
-        when :cooperative, :offloaded
-          trace_handle = Phronomy::Tracing::Automatic.start(
-            "tool.execute",
-            input: @arguments || @raw_arguments,
-            agent_id: @agent.agent_id,
-            execution_id: @execution_id,
-            tool_invocation_id: @id,
-            tool_call_id: @tool_call_id,
-            tool_name: @tool_name,
-            **@agent.send(:_build_caller_meta, @config)
-          )
-          operation = start_async_tool_operation(runtime)
-          unless operation.respond_to?(:on_complete)
-            raise Phronomy::ToolError,
-              "Tool #{@tool.class.name}#call_async must return a completion handle"
-          end
-          runtime.event_loop.supervise_agent_operation(@execution_id, operation)
-
-          evaluator = self.class
-          tool_invocation_id = @id.to_s.freeze
-          operation.on_complete do |result, error|
-            Phronomy::Tracing::Automatic.finish(
-              trace_handle,
-              output: result,
-              error: error
-            )
-            callback.call(
-              evaluator.send(:build_execution_outcome, tool_invocation_id, result, error)
-            )
-          end
-        else
-          callback.call(ExecutionOutcome.new(
-            tool_invocation_id: @id,
-            error: Phronomy::ConfigurationError.new(
-              "unknown Tool execution_mode: #{@tool.class.execution_mode.inspect}"
-            )
-          ))
+        trace_handle = Phronomy::Tracing::Automatic.start(
+          "tool.execute",
+          input: @arguments || @raw_arguments,
+          agent_id: @agent.agent_id,
+          execution_id: @execution_id,
+          tool_invocation_id: @id,
+          tool_call_id: @tool_call_id,
+          tool_name: @tool_name,
+          **@agent.send(:_build_caller_meta, @config)
+        )
+        operation = start_async_tool_operation(environment)
+        environment.registry.supervise_agent_operation(@execution_id, operation)
+
+        evaluator = self.class
+        tool_invocation_id = @id.to_s.freeze
+        operation.on_complete do |result, error|
+          Phronomy::Tracing::Automatic.finish(trace_handle, output: result, error: error)
+          callback.call(evaluator.send(:build_execution_outcome, tool_invocation_id, result, error))
         end
         self
       rescue => error
@@ -332,7 +330,7 @@ module Phronomy
       end
 
       def tool_schema
-        @tool&.respond_to?(:params_schema) ? @tool.params_schema : {}
+        @tool&.respond_to?(:parameters_schema) ? @tool.parameters_schema : {}
       end
 
       def display_arguments
@@ -345,6 +343,40 @@ module Phronomy
 
       private
 
+      def restore_saved_state!(status, result)
+        case status
+        when :awaiting_approval
+          validate! unless terminal?
+          @final_decision = :require_approval
+          mark_awaiting_approval!
+        when :authorized
+          validate! unless terminal?
+          @final_decision = :allow
+          mark_authorized!
+        when :completed
+          @result = result
+          @status = :completed
+        when :rejected
+          mark_rejected!
+        when :failed
+          mark_framework_failed!(
+            Phronomy::ToolError.new("durably restored Tool preflight failure")
+          )
+        when :cancelled
+          mark_cancelled!
+        else
+          raise Phronomy::ExecutionRehydrationRequiredError,
+            "unsupported durable Tool snapshot state: #{status.inspect}"
+        end
+      end
+
+      def restore_approval_evidence!(item)
+        return unless item
+
+        @facts = immutable_copy(item.facts)
+        @authorization_reason = item.reason
+      end
+
       def authorization_command
         definition = @agent.class.agent_definition
 
@@ -354,28 +386,20 @@ module Phronomy
           agent_definition_version: Integer(definition.fetch(:version)),
           execution_id: @execution_id,
           tool_name: @tool_name.to_s.freeze,
-          tool_schema: self.class.send(:immutable_command_copy, tool_schema),
+          tool_schema: Phronomy::Tool::Authorization.snapshot(tool_schema),
           tool_invocation_id: @id.to_s.freeze,
           tool_call_id: @tool_call_id&.to_s&.freeze,
-          arguments: self.class.send(
-            :immutable_command_copy,
+          arguments: Phronomy::Tool::Authorization.snapshot(
             @arguments || {}
           ),
-          approval_policy: self.class.send(
-            :safe_behavior_handle, @approval_policy, "approval_policy"
-          ),
-          approval_facts_callable: self.class.send(
-            :safe_behavior_handle, authorization_facts_callable, "approval_facts"
-          ),
-          approval_requirement: self.class.send(
-            :safe_behavior_handle, authorization_requirement, "requires_approval"
-          ),
-          approval_context: self.class.send(
-            :immutable_command_copy,
+          approval_policy: Phronomy::Tool::Authorization.behavior(@approval_policy, "approval_policy"),
+          approval_facts_callable: Phronomy::Tool::Authorization.behavior(authorization_facts_callable, "approval_facts"),
+          approval_requirement: Phronomy::Tool::Authorization.behavior(authorization_requirement, "requires_approval"),
+          approval_context: Phronomy::Tool::Authorization.snapshot(
             @approval_context
           ),
           origin: @origin,
-          metadata: self.class.send(:immutable_command_copy, @metadata)
+          metadata: Phronomy::Tool::Authorization.snapshot(@metadata)
         )
       end
 
@@ -393,58 +417,18 @@ module Phronomy
 
       def self.evaluate_authorization_command(command)
         request = build_authorization_request(command, facts: {}, default_decision: nil)
-        facts = evaluate_authorization_facts(command)
-        request = request.with(facts: facts)
-        default_decision = evaluate_default_authorization_decision(command, request)
-        request = request.with(default_decision: default_decision)
-        decision = command.approval_policy ? command.approval_policy.call(request) : default_decision
-        decision = decision.to_sym if decision.respond_to?(:to_sym)
-
-        unless ApprovalEvaluationRequest::VALID_DECISIONS.include?(decision)
-          raise Phronomy::ConfigurationError,
-            "tool_approval_policy must return :allow, :require_approval, or :reject " \
-            "(got #{decision.inspect})"
-        end
-
-        reason = if decision == :require_approval
-          (command.origin == :mcp) ?
-            "MCP Tool execution requires approval" : "Tool execution requires approval"
-        end
+        decision = Phronomy::Tool::Authorization.call(
+          request: request, arguments: command.arguments, context: command.approval_context,
+          facts: command.approval_facts_callable, requirement: command.approval_requirement,
+          policy: command.approval_policy
+        )
         AuthorizationOutcome.new(
           tool_invocation_id: command.tool_invocation_id,
-          decision: decision,
-          facts: facts,
-          reason: reason
+          decision: decision.decision, facts: decision.facts, reason: decision.reason
         )
       end
       private_class_method :evaluate_authorization_command
 
-      def self.evaluate_authorization_facts(command)
-        callable = command.approval_facts_callable
-        return {} unless callable
-
-        value = callable.call(command.arguments, command.approval_context)
-        unless value.nil? || value.is_a?(Hash)
-          raise Phronomy::ConfigurationError,
-            "approval_facts must return a Hash or nil (got #{value.class})"
-        end
-        immutable_command_copy(value || {})
-      end
-      private_class_method :evaluate_authorization_facts
-
-      def self.evaluate_default_authorization_decision(command, request)
-        requirement = command.approval_requirement
-        requirement = requirement.call(request) if requirement.respond_to?(:call)
-        case requirement
-        when true then :require_approval
-        when false, nil then :allow
-        else
-          raise Phronomy::ConfigurationError,
-            "requires_approval callable must return true or false (got #{requirement.inspect})"
-        end
-      end
-      private_class_method :evaluate_default_authorization_decision
-
       def self.build_authorization_request(command, facts:, default_decision:)
         ApprovalEvaluationRequest.new(
           agent_id: command.agent_id,
@@ -465,116 +449,19 @@ module Phronomy
       end
       private_class_method :build_authorization_request
 
-      def self.immutable_command_copy(value)
-        if phronomy_managed_live_domain_object?(value)
-          raise Phronomy::ConfigurationError,
-            "authorization worker snapshot cannot contain Phronomy-managed live " \
-            "domain object #{value.class}"
-        end
-
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[immutable_command_copy(key)] = immutable_command_copy(item)
-          end.freeze
-        when Array
-          value.map { |item| immutable_command_copy(item) }.freeze
-        when String
-          value.dup.freeze
-        else
-          # Application-defined opaque objects are permitted by ACS-11 and remain
-          # Application-owned. A stricter general value-type protocol is deferred.
-          value
-        end
-      end
-      private_class_method :immutable_command_copy
-
-      def self.phronomy_managed_live_domain_object?(value)
-        value.is_a?(Phronomy::Agent::Base) ||
-          value.is_a?(Phronomy::Agent::AgentRoot) ||
-          value.is_a?(Phronomy::Agent::AgentExecution) ||
-          value.is_a?(Phronomy::Agent::AgentInvocation) ||
-          value.is_a?(Phronomy::Agent::ToolInvocation) ||
-          value.is_a?(Phronomy::Agent::JournalProjection) ||
-          value.is_a?(Phronomy::Agent::ExecutionCoordinator) ||
-          value.is_a?(Phronomy::Agent::Context::Capability::Base) ||
-          value.is_a?(Phronomy::Workflow) ||
-          value.is_a?(Phronomy::WorkflowRunner) ||
-          value.is_a?(Phronomy::WorkflowContext) ||
-          value.is_a?(Phronomy::Runtime) ||
-          value.is_a?(Phronomy::TaskResult) ||
-          value.is_a?(Phronomy::EventLoop) ||
-          value.is_a?(Phronomy::FSMSession) ||
-          value.is_a?(Phronomy::FSMSession::EventSink) ||
-          value.is_a?(Phronomy::Concurrency::CancellationToken) ||
-          value.is_a?(Phronomy::Concurrency::OffloadPool)
-      end
-      private_class_method :phronomy_managed_live_domain_object?
-
-      def self.safe_behavior_handle(value, name)
-        return value if value.nil? || value == true || value == false
-        if phronomy_managed_live_domain_object?(value)
-          raise Phronomy::ConfigurationError,
-            "#{name} must not be a Phronomy-managed live domain object (got #{value.class})"
-        end
-        value
-      end
-      private_class_method :safe_behavior_handle
-
-      # Compatibility helpers for the existing private behavioral specs. These
-      # evaluate a frozen operation command just like the worker path; they do not
-      # reintroduce worker-side access to live mutable ToolInvocation state.
-      def evaluate_authorization
-        self.class.send(:evaluate_authorization_command, authorization_command)
-      end
-
-      def evaluate_facts
-        self.class.send(:evaluate_authorization_facts, authorization_command)
-      end
-
-      def evaluate_default_decision(request)
-        self.class.send(
-          :evaluate_default_authorization_decision,
-          authorization_command,
-          request
-        )
-      end
-
-      def build_request(facts:, default_decision:)
-        self.class.send(
-          :build_authorization_request,
-          authorization_command,
-          facts: facts,
-          default_decision: default_decision
+      def start_async_tool_operation(environment)
+        tool_config = @tool.class.respond_to?(:__framework_owned_operation?) ?
+          @config.merge(phronomy_tool_invocation_id: @id, execution_id: @execution_id).freeze : @config
+        Phronomy::Tool::Operation.call_async(
+          tool: @tool,
+          args: @arguments,
+          cancellation_token: @config[:cancellation_token],
+          config: tool_config,
+          submitter: environment,
+          on_full: :raise
         )
       end
 
-      def start_async_tool_operation(runtime)
-        if uses_default_call_async?
-          Phronomy::Agent::ToolExecutor.call_async(
-            tool: @tool,
-            args: @arguments,
-            cancellation_token: @config[:cancellation_token],
-            config: @config,
-            runtime: runtime,
-            on_full: :raise
-          )
-        else
-          tool_config = @tool.class.respond_to?(:__framework_owned_operation?) ?
-            @config.merge(phronomy_tool_invocation_id: @id, execution_id: @execution_id).freeze : @config
-          @tool.call_async(
-            @arguments,
-            cancellation_token: @config[:cancellation_token],
-            config: tool_config
-          )
-        end
-      end
-
-      def uses_default_call_async?
-        @tool.method(:call_async).owner ==
-          Phronomy::Agent::Context::Capability::Base
-      end
-
       def self.build_execution_outcome(tool_invocation_id, result, error)
         if error
           ExecutionOutcome.new(
@@ -590,7 +477,7 @@ module Phronomy
 
       def self.authorization_failure_result(tool_invocation_id, error)
         if error.is_a?(Phronomy::TimeoutError) ||
-            error.is_a?(Phronomy::TransportError) ||
+            error.is_a?(Phronomy::LLMAdapter::TransportError) ||
             error.is_a?(Phronomy::BackpressureError)
           AuthorizationOutcome.new(
             tool_invocation_id: tool_invocation_id,
@@ -608,16 +495,6 @@ module Phronomy
       end
       private_class_method :authorization_failure_result
 
-      # Private compatibility helpers used by existing behavioral specs. Runtime
-      # callbacks use only the pure class helpers above and captured semantic IDs.
-      def execution_outcome(result, error)
-        self.class.send(:build_execution_outcome, @id, result, error)
-      end
-
-      def authorization_failure_outcome(error)
-        self.class.send(:authorization_failure_result, @id, error)
-      end
-
       def authoritative_tool_outcome?(outcome)
         outcome.respond_to?(:tool_invocation_id) &&
           outcome.tool_invocation_id.to_s == @id
@@ -665,18 +542,7 @@ module Phronomy
       end
 
       def immutable_copy(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, item), result|
-            result[immutable_copy(key)] = immutable_copy(item)
-          end.freeze
-        when Array
-          value.map { |item| immutable_copy(item) }.freeze
-        when String
-          value.dup.freeze
-        else
-          value
-        end
+        Phronomy::Values::Immutable.copy(value)
       end
 
       def redact_for_display(value)

data/lib/phronomy/agent/tool_execution/tool_invocation_actions.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned Tool child entry operations and session-local result delivery.
+    # Workers return outcomes; the serial owner applies live invocation state.
+    # @api private
+    class ToolInvocationActions
+      def self.build_entry_actions(environment, event_sink, parent_event_sink)
+        {
+          validating: [method(:validating_action)],
+          authorizing: [method(:authorizing_action).curry.call(environment, event_sink)],
+          awaiting_approval: [method(:awaiting_approval_action).curry.call(parent_event_sink)],
+          authorized: [method(:authorized_action).curry.call(parent_event_sink)],
+          queued: [method(:queued_action)],
+          running: [method(:running_action).curry.call(environment, event_sink)],
+          completed: [method(:completed_action).curry.call(parent_event_sink)],
+          failed: [method(:failed_action).curry.call(parent_event_sink)],
+          rejected: [method(:rejected_action).curry.call(parent_event_sink)],
+          cancelled: [method(:cancelled_action).curry.call(parent_event_sink)]
+        }
+      end
+
+      def self.validating_action(invocation)
+        invocation.validate!
+      end
+      private_class_method :validating_action
+
+      def self.authorizing_action(environment, event_sink, invocation)
+        invocation.start_authorization(environment: environment) do |outcome|
+          post_to_session(event_sink, :authorization_completed, outcome)
+        end
+        invocation
+      end
+      private_class_method :authorizing_action
+
+      def self.awaiting_approval_action(parent_event_sink, invocation)
+        invocation.mark_awaiting_approval!
+        notify_parent(parent_event_sink, invocation, :tool_approval_required)
+        invocation
+      end
+      private_class_method :awaiting_approval_action
+
+      def self.authorized_action(parent_event_sink, invocation)
+        invocation.mark_authorized!
+        notify_parent(parent_event_sink, invocation, :tool_authorized)
+        invocation
+      end
+      private_class_method :authorized_action
+
+      def self.queued_action(invocation)
+        invocation.mark_queued!
+      end
+      private_class_method :queued_action
+
+      def self.running_action(environment, event_sink, invocation)
+        invocation.start_execution(environment: environment) do |outcome|
+          post_to_session(event_sink, :execution_completed, outcome)
+        end
+        invocation.mark_running!
+        invocation
+      end
+      private_class_method :running_action
+
+      def self.completed_action(parent_event_sink, invocation)
+        notify_parent(parent_event_sink, invocation, :tool_completed)
+        invocation
+      end
+      private_class_method :completed_action
+
+      def self.failed_action(parent_event_sink, invocation)
+        notify_parent(parent_event_sink, invocation, :tool_failed)
+        invocation
+      end
+      private_class_method :failed_action
+
+      def self.rejected_action(parent_event_sink, invocation)
+        invocation.mark_rejected!
+        notify_parent(parent_event_sink, invocation, :tool_rejected)
+        invocation
+      end
+      private_class_method :rejected_action
+
+      def self.cancelled_action(parent_event_sink, invocation)
+        invocation.mark_cancelled!
+        notify_parent(parent_event_sink, invocation, :tool_cancelled)
+        invocation
+      end
+      private_class_method :cancelled_action
+
+      def self.post_to_session(event_sink, event_type, payload)
+        return if event_sink.post(event_type, payload)
+
+        Phronomy::RuntimeSettings.current.logger&.warn(
+          "[Phronomy] Dropped #{event_type.inspect} for " \
+          "FSMSession #{event_sink.fsm_session_id}"
+        )
+      end
+      private_class_method :post_to_session
+
+      def self.notify_parent(parent_event_sink, invocation, event_type)
+        parent_event_sink.post(event_type, {tool_invocation_id: invocation.id})
+      end
+      private_class_method :notify_parent
+    end
+  end
+end

data/lib/phronomy/agent/tool_execution/tool_invocation_transitions.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent-owned Tool child progress. Ordered guards and source admission
+    # share one definition; no FSM library or Runtime is needed to evaluate it.
+    # @api private
+    module ToolInvocationTransitions
+      ENTRY_POINT = :idle
+      RECURSION_LIMIT = 20
+
+      AUTO_STATE_SET = {idle: true, validating: true, queued: true}.freeze
+
+      DECLARED_STATES = %i[
+        idle validating authorizing awaiting_approval authorized queued running
+        completed failed rejected cancelled
+      ].freeze
+
+      WAIT_STATES = %i[awaiting_approval authorized].freeze
+
+      EXTERNAL_EVENTS = {
+        authorization_completed: [
+          {from: :authorizing, to: :cancelled, guard: ->(ctx) { ctx.cancelled? }},
+          {from: :authorizing, to: :failed, guard: ->(ctx) { ctx.failed? }},
+          {from: :authorizing, to: :rejected, guard: ->(ctx) { ctx.rejected? }},
+          {from: :authorizing, to: :awaiting_approval, guard: ->(ctx) { ctx.awaiting_approval? }},
+          {from: :authorizing, to: :authorized, guard: ->(ctx) { ctx.authorized? }}
+        ],
+        execution_completed: [
+          {from: :running, to: :cancelled, guard: ->(ctx) { ctx.cancelled? }},
+          {from: :running, to: :failed, guard: ->(ctx) { ctx.failed? }},
+          {from: :running, to: :completed, guard: ->(ctx) { ctx.execution_completed? }}
+        ],
+        approve: [{from: :awaiting_approval, to: :authorized, guard: nil}],
+        reject: [{from: :awaiting_approval, to: :rejected, guard: nil}],
+        dispatch: [{from: :authorized, to: :queued, guard: nil}],
+        cancel: [
+          {from: :awaiting_approval, to: :cancelled, guard: nil},
+          {from: :authorized, to: :cancelled, guard: nil},
+          {from: :queued, to: :cancelled, guard: nil},
+          {from: :running, to: :cancelled, guard: nil}
+        ]
+      }.transform_values { |definitions| definitions.each(&:freeze).freeze }.freeze
+
+      AUTOMATIC_EVENTS = {
+        state_completed: [
+          {from: :idle, to: :validating, guard: nil},
+          {from: :validating, to: :failed, guard: ->(ctx) { ctx.failed? }},
+          {from: :validating, to: :completed, guard: ->(ctx) { ctx.validation_completed? }},
+          {from: :validating, to: :authorizing, guard: ->(ctx) { ctx.validation_passed? }},
+          {from: :queued, to: :running, guard: nil}
+        ].each(&:freeze).freeze
+      }.freeze
+
+      EVENTS = AUTOMATIC_EVENTS.merge(EXTERNAL_EVENTS).freeze
+
+      def self.next_phase(phase, event, context)
+        definition = EVENTS.fetch(event.to_sym, []).find do |candidate|
+          candidate[:from] == phase.to_sym && allowed?(candidate, context)
+        end
+        definition&.fetch(:to)
+      end
+
+      def self.allowed?(definition, context)
+        guard = definition[:guard]
+        !guard || !!(context && guard.call(context))
+      end
+    end
+  end
+end

data/lib/phronomy/common/configuration_error.rb

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

data/lib/phronomy/common/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Error < StandardError; end
+end