phronomy 0.25.0 → 0.27.0

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

@@ -4,8 +4,8 @@ module Phronomy
   module Agent
     # Normal control-transfer signal raised before RubyLLM executes a Tool Call.
     #
-    # RubyLLM >= 1.15 guarantees that the complete assistant message has already
-    # been added to Chat#messages before before_tool_call runs. Keeping that
+    # RubyLLM 2.0 guarantees that the complete assistant message has already
+    # been added to Chat#messages before after_message runs. Keeping that
     # message here allows Phronomy to persist the complete Provider outcome even
     # though the RubyLLM call itself unwinds through this exception.
     # @api private

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

@@ -14,10 +14,10 @@ module Phronomy
             "name" => tool.name.to_s,
             "description" => tool.description.to_s,
             "parameters_schema" => normalize(
-              tool.respond_to?(:parameters_schema) ? tool.parameters_schema : {}
+              tool.parameters_schema
             ),
             "provider_options" => normalize(
-              tool.respond_to?(:provider_options) ? tool.provider_options : {}
+              tool.provider_options
             )
           }
         end.freeze
@@ -47,13 +47,13 @@ module Phronomy
 
       def initialize(runtime_tools:, definitions:)
         @runtime_tools = Array(runtime_tools).freeze
-        @definitions = Immutable.copy(definitions)
+        @definitions = Phronomy::Values::Immutable.copy(definitions)
         validate_unique_names!
         freeze
       end
 
       def select_definitions(expected_definitions)
-        expected = Immutable.copy(Array(expected_definitions))
+        expected = Phronomy::Values::Immutable.copy(Array(expected_definitions))
         current_by_name = definitions.each_with_index.to_h do |definition, index|
           [definition.fetch("name"), [definition, runtime_tools.fetch(index)]]
         end
@@ -70,6 +70,11 @@ module Phronomy
             raise Phronomy::ConfigurationError,
               "ContextPolicy selected Tool not present in current Agent configuration: #{name}"
           end
+          if definition["parameters_schema"] == {} && current_definition["parameters_schema"] != {}
+            raise Phronomy::ConfigurationError,
+              "Saved Tool definition lacks a verifiable parameters_schema: #{name}; " \
+              "finish this in-flight execution on its original version before upgrading"
+          end
           unless Phronomy::CanonicalJSON.dump(current_definition) ==
               Phronomy::CanonicalJSON.dump(definition)
             raise Phronomy::ConfigurationError,

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

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/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
@@ -215,7 +244,7 @@ module Phronomy
           cancellation_token: @config[:cancellation_token],
           on_full: :raise
         ) { evaluator.send(:evaluate_authorization_command, command) }
-        runtime.event_loop.supervise_agent_operation(@execution_id, operation)
+        Phronomy::Agent::ExecutionRegistry.for(runtime.event_loop).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
@@ -259,7 +288,7 @@ module Phronomy
             raise Phronomy::ToolError,
               "Tool #{@tool.class.name}#call_async must return a completion handle"
           end
-          runtime.event_loop.supervise_agent_operation(@execution_id, operation)
+          Phronomy::Agent::ExecutionRegistry.for(runtime.event_loop).supervise_agent_operation(@execution_id, operation)
 
           evaluator = self.class
           tool_invocation_id = @id.to_s.freeze
@@ -332,7 +361,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 +374,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
 
@@ -490,24 +553,7 @@ module Phronomy
       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::Task) ||
-          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)
+        value.is_a?(Phronomy::Concurrency::WorkerInputRestricted)
       end
       private_class_method :phronomy_managed_live_domain_object?
 
@@ -551,7 +597,7 @@ module Phronomy
 
       def start_async_tool_operation(runtime)
         if uses_default_call_async?
-          Phronomy::Agent::ToolExecutor.call_async(
+          Phronomy::Agent::Context::Capability::ToolExecutor.call_async(
             tool: @tool,
             args: @arguments,
             cancellation_token: @config[:cancellation_token],
@@ -665,18 +711,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_invocation_session_builder.rb → tool_execution/tool_invocation_session_builder.rb}

@@ -181,9 +181,9 @@ module Phronomy
       def self.build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Tool entry action for #{state_name.inspect} returned Phronomy::Task"
+              "Tool entry action for #{state_name.inspect} returned Phronomy::TaskResult"
           end
           machine.context = result if result.respond_to?(:set_graph_metadata)
         }

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

data/lib/phronomy/{agent → common/values}/immutable.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "../canonical_json"
+
 module Phronomy
-  module Agent
+  module Values
+    # Shared value operations for snapshots, recovery facts, and result views.
+    # Hash, Array, and String trees are copied and frozen; other values retain
+    # their identity. Canonical JSON validation is a separate operation.
+    # @api private
     module Immutable
       module_function
 
+      # @api private
       def copy(value)
         case value
         when Hash
@@ -20,6 +27,7 @@ module Phronomy
         end
       end
 
+      # @api private
       def validate_canonical_json!(value, label: "value")
         Phronomy::CanonicalJSON.dump(value)
         true

data/lib/phronomy/common/values/serializable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Values
+    # Prepares a Ruby value tree for JSON serialization. Hash keys and Symbol
+    # values become Strings; containers are rebuilt and scalar objects retained.
+    # This neither freezes values nor validates canonical JSON numbers/encoding.
+    # @api private
+    module Serializable
+      module_function
+
+      def convert(value, unsupported_message:)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_s, convert(child, unsupported_message: unsupported_message)] }
+        when Array
+          value.map { |child| convert(child, unsupported_message: unsupported_message) }
+        when String, Integer, Float, TrueClass, FalseClass, NilClass
+          value
+        when Symbol
+          value.to_s
+        else
+          if value.respond_to?(:to_h)
+            convert(value.to_h, unsupported_message: unsupported_message)
+          else
+            raise ArgumentError, "#{unsupported_message}: #{value.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{configuration.rb → configuration/configuration.rb}

@@ -6,13 +6,23 @@ module Phronomy
     STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
     private_constant :STREAM_CALLBACK_ERROR_POLICIES
 
+    DEFAULT_FACTORIES = {}
+    private_constant :DEFAULT_FACTORIES
+
+    # Bind fresh-instance factories once during application loading. Concrete
+    # component selection belongs to runtime_composition, not configuration.
+    # Applications replace instances through the existing configuration writers.
+    # @api private
+    def self.install_default_factories(tracer:, llm_adapter:)
+      DEFAULT_FACTORIES.replace(tracer: tracer, llm_adapter: llm_adapter).freeze
+      nil
+    end
+
     attr_accessor :default_model
     attr_accessor :default_embedding_model
     attr_accessor :tracer
     attr_accessor :before_llm_input
-    attr_accessor :default_output_reserve
     attr_accessor :recursion_limit
-    attr_accessor :parallel_tool_execution
     attr_accessor :trace_pii
     attr_accessor :logger
     attr_accessor :event_loop_stop_grace_seconds
@@ -40,11 +50,10 @@ module Phronomy
 
     def initialize
       @recursion_limit = 25
-      @tracer = Phronomy::Tracing::NullTracer.new
+      @tracer = DEFAULT_FACTORIES.fetch(:tracer).call
       @trace_pii = false
-      @parallel_tool_execution = false
       @event_loop_stop_grace_seconds = 5
-      @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+      @llm_adapter = DEFAULT_FACTORIES.fetch(:llm_adapter).call
       @event_loop_starvation_threshold_seconds = nil
       @event_loop_dispatch_threshold_seconds = nil
       @stream_callback_error_policy = :report

data/lib/phronomy/configuration/global_configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Global configuration access, replacement, and scoped overrides.
+# Explicitly loaded by the application entry point; not a common definition.
+module Phronomy
+  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
+  end
+end

data/lib/phronomy/content_store/storage_schema.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module ContentStore
+    # @api private
+    module StorageSchema
+      CONTENTS = Phronomy::Storage::Resource.new(id: "content.blobs", kind: :blobs,
+        attributes: {canonicalization_version: :integer})
+    end
+  end
+end

data/lib/phronomy/content_store/stored_contents.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module ContentStore
+    # Content identity and digest validation belong to ContentStore, not Blobs.
+    # @api private
+    class StoredContents < Base
+      def initialize(view) = @view = view
+
+      def put(bytes, canonicalization_version:)
+        value = String(bytes).b
+        id = content_id_for(value)
+        @view.atomic do |bound|
+          blob = bound.blobs(StorageSchema::CONTENTS).put_if_absent(key: id, bytes: value,
+            attributes: {canonicalization_version: Integer(canonicalization_version)})
+          verify!(blob, id)
+          id
+        end
+      rescue Phronomy::Storage::BlobConflictError => error
+        raise IntegrityError, error.message
+      end
+
+      def fetch(content_id)
+        id = content_id.to_s
+        @view.atomic do |bound|
+          blob = bound.blobs(StorageSchema::CONTENTS).fetch(id)
+          verify!(blob, id)
+          blob.bytes.dup
+        end
+      end
+
+      def exist?(content_id) = @view.blobs(StorageSchema::CONTENTS).exist?(content_id.to_s)
+
+      private
+
+      def verify!(blob, id)
+        unless blob.key == id && content_id_for(blob.bytes) == id
+          raise IntegrityError, "content digest mismatch: #{id}"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/engine/backpressure_error.rb

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

data/lib/phronomy/{blocking.rb → engine/blocking.rb}

@@ -7,27 +7,34 @@ module Phronomy
   module Blocking
     # Submits synchronous application work to the default Runtime OffloadPool.
     # Admission never waits for queue space. Admission StandardError failures
-    # become failed Tasks; accepted work retains the pool's Task unchanged.
-    # A timeout/cancellation can settle that Task before a running worker exits.
-    # The block must not wait for another Agent, Workflow, or Task.
+    # become failed results; accepted work retains the pool's TaskResult unchanged.
+    # A timeout/cancellation can settle that TaskResult before a running worker exits.
+    # The block must not wait for another Agent, Workflow, or TaskResult.
     # @param timeout [Numeric, nil] operation deadline, including queue time
     # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+    # @param invocation_context [Phronomy::InvocationContext, nil] explicit context/scope
     # @yield synchronous application work
-    # @return [Phronomy::Task] original accepted Task or failed admission Task
+    # @return [Phronomy::TaskResult] original accepted TaskResult or failed admission TaskResult
     # @raise [ArgumentError] if no block is supplied
     # @api public
-    def self.call_async(timeout: nil, cancellation_token: nil, &block)
+    def self.call_async(timeout: nil, cancellation_token: nil, invocation_context: nil, &block)
       raise ArgumentError, "Blocking.call_async requires a block" unless block
 
       begin
-        Phronomy::Runtime.instance.offload.submit(
+        unless invocation_context.nil?
+          binding = Concurrency::OperationBinding.new(invocation_context: invocation_context,
+            cancellation_token: cancellation_token)
+        end
+        result = Phronomy::Runtime.instance.offload.submit(
           on_full: :raise,
           timeout: timeout,
-          cancellation_token: cancellation_token,
+          cancellation_token: binding ? binding.token : cancellation_token,
           &block
         )
+        binding ? binding.bind(result) : result
       rescue => error
-        Phronomy::Task.failed(error, name: "blocking-admission-failed")
+        result = Phronomy::TaskResult.failed(error, name: "blocking-admission-failed")
+        binding ? binding.bind(result) : result
       end
     end
   end

data/lib/phronomy/engine/cancellation_error.rb

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

data/lib/phronomy/engine/concurrency/cancellation_token.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require_relative "worker_input_restricted"
+
 module Phronomy
   module Concurrency
     # Cooperative cancellation token for Agent/Tool work.
     class CancellationToken
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # Creates a token that expires after +seconds+ measured with the monotonic clock.
       # @api public
       def self.timeout_after(seconds)

data/lib/phronomy/engine/concurrency/offload_pool.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "worker_input_restricted"
+
 module Phronomy
   module Concurrency
     # A bounded, observable thread pool for synchronous work that must not run on
@@ -13,7 +15,7 @@ module Phronomy
     # synchronous call. Phronomy deliberately does not classify the workload by
     # cause; the application decides whether a unit of work is EventLoop-safe.
     #
-    # Logical waits are different. Waiting for another Phronomy Task, Agent,
+    # Logical waits are different. Waiting for another Phronomy TaskResult, Agent,
     # Workflow, ToolInvocation, timer, or FSMSession must remain an explicit
     # EventLoop/FSMSession continuation and must not consume an OffloadPool worker.
     # See ADR-010.
@@ -22,7 +24,7 @@ module Phronomy
     #
     # 1. The total number of worker OS threads is capped.
     # 2. Queue depth is bounded (backpressure when the pool is saturated).
-    # 3. Per-operation timeouts and cancellation settle the caller-facing Task.
+    # 3. Per-operation timeouts and cancellation settle the caller-facing TaskResult.
     # 4. Operations that settle after worker execution has started are tracked as
     #    abandoned until that worker returns.
     # 5. Metrics expose active work, queue depth, cumulative abandonment,
@@ -41,9 +43,11 @@ module Phronomy
     #   task = pool.submit(timeout: 30, cancellation_token: token) { expensive_call }
     #   result = task.wait_result
     class OffloadPool
+      include Phronomy::Concurrency::WorkerInputRestricted
+
       # Private execution record for one submitted synchronous operation.
       #
-      # Caller-facing completion is represented exclusively by {Phronomy::Task}.
+      # Caller-facing completion is represented exclusively by {Phronomy::TaskResult}.
       # This object owns only OffloadPool-specific execution state: queue timing,
       # worker-start linearization, submit timeout/cancellation, abandonment, and
       # the submitted block itself.
@@ -77,6 +81,7 @@ module Phronomy
           @submitted_at = submitted_at ||
             Process.clock_gettime(Process::CLOCK_MONOTONIC)
           @mutex = Mutex.new
+          @timer_subscriptions = Subscriptions.new
 
           # Explicit submit cancellation is operation-wide. Deadline-only tokens are
           # promoted to cancel! by OffloadPool#submit using the Runtime timer queue.
@@ -92,19 +97,26 @@ module Phronomy
           @mutex.synchronize { @settled }
         end
 
-        # @return [Boolean] true when the submit-time deadline settled the Task
+        # Registration can race logical completion. Dispose the timer even when
+        # settlement occurred while schedule was returning.
+        def schedule(timer_queue, seconds:, &callback)
+          timer_queue.schedule(seconds: seconds, &callback)
+          @timer_subscriptions.add { timer_queue.cancel(callback) }
+        end
+
+        # @return [Boolean] true when the submit-time deadline settled the TaskResult
         # @api private
         def timed_out?
           @mutex.synchronize { @timed_out }
         end
 
-        # @return [Boolean] true when submit cancellation settled the Task
+        # @return [Boolean] true when submit cancellation settled the TaskResult
         # @api private
         def cancelled?
           @mutex.synchronize { @cancelled }
         end
 
-        # @return [Boolean] true when timeout/cancellation settled the Task after
+        # @return [Boolean] true when timeout/cancellation settled the TaskResult after
         #   worker execution had started. The worker is not forcibly interrupted.
         # @api private
         def abandoned?
@@ -117,7 +129,7 @@ module Phronomy
           @wait_time || 0.0
         end
 
-        # Settles the caller-facing Task with a submit-time timeout.
+        # Settles the caller-facing TaskResult with a submit-time timeout.
         #
         # The worker is not interrupted. If execution has already started, the
         # operation is marked abandoned and the worker's eventual result is discarded.
@@ -132,7 +144,7 @@ module Phronomy
           end
         end
 
-        # Settles the caller-facing Task because its submit cancellation token was
+        # Settles the caller-facing TaskResult because its submit cancellation token was
         # cancelled. Cancellation never injects Thread#raise into the worker.
         #
         # @return [Boolean] true when this call won settlement
@@ -201,7 +213,7 @@ module Phronomy
             complete_with_value!(@block.call)
           rescue Exception => e # rubocop:disable Lint/RescueException
             # Rescue all Exception subclasses so non-StandardError raises still
-            # settle the Task and unblock waiters.
+            # settle the TaskResult and unblock waiters.
             complete_with_error!(e)
             raise if e.is_a?(SignalException) || e.is_a?(SystemExit)
           end
@@ -280,6 +292,7 @@ module Phronomy
         end
 
         def detach_submit_cancellation
+          @timer_subscriptions.close
           return unless @cancellation_token && @cancellation_callback
 
           @cancellation_token.send(
@@ -325,20 +338,20 @@ module Phronomy
 
       # Submits synchronous off-EventLoop work to the pool.
       #
-      # Returns a {Phronomy::Task} immediately after queue admission; the block
+      # Returns a {Phronomy::TaskResult} immediately after queue admission; the block
       # runs on a worker thread. Do not submit logical waits (for example waiting
-      # for a child Agent Task) merely to make them asynchronous; those belong to
+      # for a child Agent TaskResult) merely to make them asynchronous; those belong to
       # FSMSession/EventLoop completion events.
       #
       # A submit-time +timeout+ is an operation-wide deadline measured from the
-      # start of this method, including queue wait. The timer settles the Task and
+      # start of this method, including queue wait. The timer settles the TaskResult and
       # notifies +on_complete+ without forcibly interrupting a running worker. If
       # the deadline fires before worker execution starts, the block is skipped.
       # If it fires after execution starts, the private Operation is marked
       # abandoned and the eventual worker result is discarded.
       #
       # The submit +cancellation_token+ is also operation-wide. Explicit
-      # cancellation settles the Task immediately. A token with a monotonic
+      # cancellation settles the TaskResult immediately. A token with a monotonic
       # deadline is attached to the Runtime timer queue so deadline expiry becomes
       # explicit cancellation without adding a polling Thread. Cancellation before
       # execution skips the block; cancellation after execution starts abandons
@@ -356,7 +369,7 @@ module Phronomy
       # @param on_full [Symbol] +:wait+, +:raise+, or +:timeout+
       # @param full_timeout [Numeric, nil] queue-admission timeout for +on_full: :timeout+
       # @yield block containing synchronous work
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @raise [Phronomy::ConfigurationError] when a timer is required but no
       #   timer queue provider is configured
       # @raise [Phronomy::PoolShutdownError] when the pool has been shut down
@@ -421,7 +434,7 @@ module Phronomy
 
             # Arm before queue admission so the deadline includes time spent waiting
             # for a queue slot.
-            timer_queue.schedule(seconds: remaining) { operation.fire_timeout! }
+            operation.schedule(timer_queue, seconds: remaining) { operation.fire_timeout! }
           end
 
           if cancellation_remaining
@@ -431,7 +444,7 @@ module Phronomy
               cancellation_token.cancel!
               return task
             end
-            timer_queue.schedule(seconds: remaining) { cancellation_token.cancel! }
+            operation.schedule(timer_queue, seconds: remaining) { cancellation_token.cancel! }
           end
 
           # Cancellation/timeout can race with timer registration. Do not enqueue