phronomy 0.7.1 → 0.8.0

data/lib/phronomy/blocking_adapter_pool.rb

@@ -1,435 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # A bounded, observable thread pool for blocking I/O operations.
-  #
-  # ## Architectural boundary
-  #
-  # `BlockingAdapterPool` is the *only* place in Phronomy that uses raw OS threads
-  # for I/O. All third-party gem calls whose internal I/O Phronomy cannot control
-  # — including RubyLLM, ActiveRecord, Redis, Faraday, and MCP stdio transport —
-  # **must** route through this pool (or a named pool obtained via
-  # {Runtime#pool}). Custom non-blocking HTTP/selector runtimes are intentionally
-  # out of scope; the pool + cooperative scheduler combination satisfies all
-  # current concurrency requirements without that complexity. (See ADR-010.)
-  #
-  # All blocking calls (LLM HTTP, MCP stdio, ActiveRecord, Redis, etc.) must be
-  # submitted through this pool so that:
-  #
-  # 1. The total number of OS threads is capped.
-  # 2. Queue depth is bounded (backpressure when the pool is saturated).
-  # 3. Per-operation timeouts are enforced consistently.
-  # 4. Abandoned (timed-out) operations are tracked and logged.
-  # 5. Metrics (active count, queue depth, abandoned count, avg wait time) are
-  #    observable at runtime.
-  #
-  # @example Submitting a blocking LLM call
-  #   op = runtime.blocking_io.submit(timeout: 30) { chat.ask(message) }
-  #   result = op.await   # blocks the calling thread until done
-  #
-  # @example With cancellation
-  #   token = Phronomy::CancellationToken.timeout_after(60)
-  #   op = pool.submit(timeout: 30, cancellation_token: token) { expensive_call }
-  #   result = op.await
-  class BlockingAdapterPool
-    # Represents the pending result of a submitted blocking operation.
-    # Returned immediately by {BlockingAdapterPool#submit}; call {#await} to
-    # wait for the result.
-    class PendingOperation
-      # @return [Boolean] true when the operation has finished (success or error)
-      # @api private
-      def done?
-        @mutex.synchronize { @done }
-      end
-
-      # @return [Boolean] true when the operation was abandoned due to timeout
-      # @api private
-      def abandoned?
-        @abandoned
-      end
-
-      # @return [Float] seconds spent in the queue before execution started
-      # @api private
-      def wait_time
-        @wait_time || 0.0
-      end
-
-      # Blocks until the operation completes and returns its value.
-      #
-      # An optional +timeout+ (in seconds) may be passed here; it is measured
-      # from the moment +await+ is called. If both a submit-time timeout and an
-      # await-time timeout are present, the earlier deadline wins. The worker
-      # thread is NOT interrupted — it runs to completion on its own.
-      #
-      # An optional +cancellation_token+ may be passed here (or at submit time).
-      # If the token is cancelled while waiting, {Phronomy::CancellationError} is
-      # raised immediately without interrupting the worker.
-      #
-      # **Cooperative path (`:fiber` / `DeterministicScheduler`):**
-      # When called from a Fiber managed by {DeterministicScheduler} (i.e. under
-      # the +:fiber+ runtime backend), the calling Fiber suspends cooperatively
-      # via +Fiber.yield+ rather than blocking the OS thread.  The Fiber is
-      # resumed on the scheduler's ready queue once the worker thread completes
-      # the operation.
-      #
-      # @note **Cooperative cancellation semantics** (ADR-010):
-      #   Phronomy uses a non-preemptive, cooperative-first concurrency model.
-      #   Cancellation is *cooperative*, not preemptive:
-      #   - When a +cancellation_token+ is cancelled, +CancellationError+ is
-      #     raised to the +await+ caller immediately; when the timeout fires,
-      #     +TimeoutError+ is raised instead. In both cases, the underlying
-      #     worker thread is **not** forcibly stopped.
-      #   - The worker thread will complete its submitted block naturally.
-      #     Code inside the block must call +token.check!+ at suitable
-      #     checkpoints to observe the cancelled state and exit early.
-      #   - There is no +Thread#kill+ or +Thread#raise+ involved. The framework
-      #     never forcibly terminates worker threads.
-      #
-      # @note **Cooperative timeout limitation**: the +timeout:+ parameter passed
-      #   to +await+ is *not* enforced on the cooperative path.  The calling Fiber
-      #   remains suspended until the worker thread finishes regardless of how many
-      #   seconds elapse.  This is because the cooperative scheduler cannot
-      #   preempt a running OS thread.  If a time bound is required, set
-      #   +timeout:+ at {BlockingAdapterPool#submit submit} time instead; the pool
-      #   will then abandon the operation on the worker side and mark it as
-      #   {#abandoned?}.
-      #
-      # @param timeout [Numeric, nil] seconds from now before raising TimeoutError
-      #   (thread path only; ignored on the cooperative/fiber path)
-      # @param cancellation_token [CancellationToken, nil]
-      # @return [Object]
-      # @raise [Phronomy::TimeoutError]
-      # @raise [Phronomy::CancellationError]
-      # @raise [Exception] error raised inside the submitted block
-      # @api private
-      def await(timeout: nil, cancellation_token: nil)
-        effective_timeout = [timeout, @timeout].compact.min
-        effective_token = cancellation_token || @cancellation_token
-
-        raise CancellationError, "blocking operation cancelled" if effective_token&.cancelled?
-
-        # Cooperative context: suspend the calling Fiber rather than blocking
-        # the OS thread so that DeterministicScheduler can continue dispatching
-        # other tasks while waiting for the blocking worker to finish.
-        # (Issue #338, ADR-010 Rule 3)
-        # Uses the same thread-local key as Task::FiberBackend::SCHEDULER_KEY
-        # (:phronomy_deterministic_scheduler) to avoid a cross-file constant
-        # dependency at load time.
-        scheduler = Thread.current.thread_variable_get(:phronomy_deterministic_scheduler)
-        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
-        if scheduler && in_managed_fiber
-          unless @done
-            # Register this await with the scheduler so run_until_idle knows
-            # not to exit until the worker thread completes (Issue #338).
-            scheduler.track_blocking_await
-            waiting_fiber = Fiber.current
-            on_complete do |_result, _error|
-              # Decrement the counter and wake run_until_idle, then re-enqueue
-              # the suspended Fiber for cooperative resumption.
-              scheduler.complete_blocking_await
-              scheduler.enqueue_fiber(-> { waiting_fiber.resume })
-            end
-            Fiber.yield(:cooperative_suspend)
-          end
-          raise CancellationError, "blocking operation cancelled" if effective_token&.cancelled?
-          raise @error if @error
-
-          return @value
-        end
-
-        # Wake up the waiting thread whenever the token is cancelled so we can
-        # propagate cancellation without sleeping until the timeout expires.
-        effective_token&.on_cancel { @mutex.synchronize { @cond.broadcast } }
-
-        if effective_timeout
-          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + effective_timeout
-          @mutex.synchronize do
-            until @done
-              raise CancellationError, "blocking operation cancelled" if effective_token&.cancelled?
-
-              remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-              if remaining <= 0
-                # Guard against double-counting when await is called multiple times.
-                unless @abandoned
-                  @abandoned = true
-                  @on_abandoned&.call
-                end
-                raise Phronomy::TimeoutError, "blocking operation timed out after #{effective_timeout}s"
-              end
-              @cond.wait(@mutex, remaining)
-            end
-          end
-        else
-          @mutex.synchronize do
-            until @done
-              raise CancellationError, "blocking operation cancelled" if effective_token&.cancelled?
-
-              @cond.wait(@mutex)
-            end
-          end
-        end
-        raise @error if @error
-
-        @value
-      end
-
-      # Registers a callback to be called when the operation finishes.
-      # If the operation has already finished the callback is invoked immediately
-      # on the calling thread.  Otherwise it is invoked on the worker thread that
-      # completes the operation.
-      #
-      # The callback receives +result+ and +error+ (one of them will be +nil+).
-      #
-      # @yield [result, error]
-      # @return [self]
-      # @api private
-      def on_complete(&callback)
-        fire_args = nil
-        @mutex.synchronize do
-          if @done
-            fire_args = [@value, @error]
-          else
-            @callbacks ||= []
-            @callbacks << callback
-          end
-        end
-        callback.call(*fire_args) if fire_args
-        self
-      end
-
-      # @api private
-      def initialize(block, timeout: nil, cancellation_token: nil, on_abandoned: nil)
-        @block = block
-        @timeout = timeout
-        @cancellation_token = cancellation_token
-        @on_abandoned = on_abandoned
-        @value = nil
-        @error = nil
-        @done = false
-        @abandoned = false
-        @wait_time = nil
-        @submitted_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        @mutex = Mutex.new
-        @cond = ConditionVariable.new
-      end
-
-      # @api private
-      def execute!
-        @wait_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @submitted_at
-
-        if @cancellation_token&.cancelled?
-          complete_with_error!(CancellationError.new("operation cancelled before execution"))
-          return
-        end
-
-        # Do NOT use Timeout.timeout here — it delivers an async Thread#raise
-        # that can corrupt external library state (mutexes, C extensions, etc.).
-        # Timeout enforcement is handled cooperatively in #await instead.
-        # Each blocking library (Net::HTTP, pg, redis, etc.) should set its
-        # own native connection/read timeouts.
-        begin
-          complete_with_value!(@block.call)
-        rescue => e
-          complete_with_error!(e)
-        end
-      end
-
-      private
-
-      def complete_with_value!(value)
-        cbs = nil
-        @mutex.synchronize do
-          @value = value
-          @done = true
-          @cond.broadcast
-          cbs = @callbacks
-          @callbacks = nil
-        end
-        cbs&.each { |cb| cb.call(value, nil) }
-      end
-
-      def complete_with_error!(error)
-        cbs = nil
-        @mutex.synchronize do
-          @error = error
-          @done = true
-          @cond.broadcast
-          cbs = @callbacks
-          @callbacks = nil
-        end
-        cbs&.each { |cb| cb.call(nil, error) }
-      end
-    end
-
-    # @param pool_size  [Integer] maximum number of worker threads
-    # @param queue_size [Integer] maximum pending operations waiting for a worker
-    # @param name       [String, Symbol, nil] optional pool name used in thread labels
-    # @param logger     [Logger, nil] optional logger for warnings
-    # @api private
-    def initialize(pool_size: 10, queue_size: 100, name: nil, logger: nil)
-      @pool_size = pool_size
-      @queue_size = queue_size
-      @name = name
-      @logger = logger
-      @queue = SizedQueue.new(queue_size)
-      @active_count = 0
-      @abandoned_count = 0
-      @total_wait_ns = 0
-      @completed_count = 0
-      @mutex = Mutex.new
-      @shutdown = false
-      @workers = Array.new(pool_size) { |i| spawn_worker(i) }
-    end
-
-    # Submits a blocking operation to the pool.
-    # Returns a {PendingOperation} immediately; the block runs on a worker thread.
-    #
-    # @note **Cooperative callers**: if you are running under the `:fiber` backend
-    #   (i.e. inside a {DeterministicScheduler} Fiber), set +timeout:+ here
-    #   rather than on {PendingOperation#await}.  The await-time timeout is not
-    #   enforced on the cooperative path (the Fiber cannot preempt a running
-    #   worker thread).  A submit-time timeout triggers on the worker side and
-    #   marks the operation {PendingOperation#abandoned? abandoned}, which
-    #   unblocks the waiting Fiber via the normal on-complete callback.
-    # @param timeout [Numeric, nil] seconds before the operation is abandoned
-    # @param cancellation_token [CancellationToken, nil]
-    # @yield block containing the blocking call
-    # @return [PendingOperation]
-    # @raise [Phronomy::PoolShutdownError] when the pool has been shut down
-    # @raise [Phronomy::BackpressureError] when +on_full: :raise+ and queue is full
-    # @raise [Phronomy::TimeoutError] when +on_full: :timeout+ and wait exceeds +full_timeout+
-    # @api private
-    def submit(timeout: nil, cancellation_token: nil, on_full: :wait, full_timeout: nil, &block)
-      raise Phronomy::PoolShutdownError, "pool has been shut down" if @shutdown
-
-      op = PendingOperation.new(block, timeout: timeout, cancellation_token: cancellation_token,
-        on_abandoned: timeout ? -> { @mutex.synchronize { @abandoned_count += 1 } } : nil)
-      begin
-        case on_full
-        when :raise
-          begin
-            @queue.push(op, true)
-          rescue ThreadError
-            raise Phronomy::BackpressureError, "BlockingAdapterPool queue is full (depth: #{@queue_size})"
-          end
-        when :timeout
-          deadline = full_timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + full_timeout) : nil
-          loop do
-            @queue.push(op, true)
-            break
-          rescue ThreadError
-            if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-              raise Phronomy::TimeoutError, "timed out waiting for a free slot in BlockingAdapterPool"
-            end
-            sleep(0.005)
-          end
-        else # :wait (default)
-          @queue.push(op)
-        end
-      rescue ClosedQueueError
-        # Shutdown raced with this submit — treat as if @shutdown was already set.
-        raise Phronomy::PoolShutdownError, "pool has been shut down"
-      end
-      op
-    end
-
-    # Gracefully drains the pool and terminates all worker threads.
-    # Waits up to +drain_timeout+ seconds for in-flight operations to finish.
-    #
-    # Closing the underlying SizedQueue signals workers to exit after draining
-    # remaining items, without blocking on a full-queue push.
-    #
-    # @param drain_timeout [Numeric] seconds to wait for workers to finish
-    # @return [self]
-    # @api private
-    def shutdown(drain_timeout: 30)
-      @shutdown = true
-      @queue.close
-      @workers.each { |t| t.join(drain_timeout) }
-      self
-    end
-
-    # --- Metrics ----------------------------------------------------------
-
-    # @return [Integer] number of operations currently executing on workers
-    # @api private
-    def active_count
-      @mutex.synchronize { @active_count }
-    end
-
-    # @return [Integer] number of operations waiting in the queue
-    # @api private
-    def queue_depth
-      @queue.size
-    end
-
-    # @return [Integer] number of operations that were abandoned due to timeout
-    # @api private
-    def abandoned_count
-      @mutex.synchronize { @abandoned_count }
-    end
-
-    # Average time (in seconds) that completed operations spent in the queue
-    # waiting for a worker.  Returns 0.0 when no operations have completed yet.
-    # @return [Float]
-    # @api private
-    def average_wait_seconds
-      @mutex.synchronize do
-        return 0.0 if @completed_count.zero?
-
-        @total_wait_ns / @completed_count.to_f / 1_000_000_000.0
-      end
-    end
-
-    # @return [Integer] configured maximum number of worker threads
-    attr_reader :pool_size
-
-    # @return [Integer] configured maximum queue depth
-    attr_reader :queue_size
-
-    # @return [String, Symbol, nil] pool name used in thread labels
-    attr_reader :name
-
-    private
-
-    SENTINEL = :shutdown
-    private_constant :SENTINEL
-
-    def spawn_worker(index = nil)
-      label = ["phronomy", "blocking-pool", @name, index].compact.join("-")
-      Thread.new do
-        Thread.current.name = label
-        loop do
-          op = begin
-            @queue.pop
-          rescue ClosedQueueError
-            break
-          end
-          # nil is returned by a closed, empty Queue on some Ruby versions
-          break if op.nil? || op == SENTINEL
-
-          run_operation(op)
-        end
-      end
-    end
-
-    def run_operation(op)
-      @mutex.synchronize { @active_count += 1 }
-
-      begin
-        op.execute!
-      ensure
-        @mutex.synchronize do
-          @active_count -= 1
-
-          if op.abandoned?
-            @logger&.warn { "BlockingAdapterPool: worker finished operation after caller timed out" }
-          end
-
-          @total_wait_ns += (op.wait_time * 1_000_000_000).to_i
-          @completed_count += 1
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/cancellation_scope.rb

@@ -1,123 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Represents a bounded execution scope that owns a {CancellationToken} and
-  # optionally a {Deadline}.
-  #
-  # +CancellationScope+ replaces ad-hoc +Timeout.timeout+ calls in agent and
-  # tool code.  All work performed within a scope should observe the scope's
-  # token; when the scope is cancelled (explicitly or by deadline expiry) the
-  # token is cancelled and all child tasks that check it will stop.
-  #
-  # @example Time-bounded invocation
-  #   scope = Phronomy::CancellationScope.new.deadline_in(30)
-  #   result = scope.pop_queue(completion_queue) do
-  #     raise Phronomy::TimeoutError, "timed out"
-  #   end
-  #
-  # @example Explicit cancellation
-  #   scope = Phronomy::CancellationScope.new
-  #   Phronomy::Runtime.instance.spawn(name: "worker") do
-  #     scope.token.raise_if_cancelled!
-  #     # ... do work ...
-  #   end
-  #   scope.cancel! if some_condition
-  class CancellationScope
-    # @return [CancellationToken] the token owned by this scope
-    attr_reader :token
-
-    # @return [Deadline, nil] the deadline attached to this scope, if any
-    attr_reader :deadline
-
-    # @param parent_token [CancellationToken, nil] when provided, cancellation of
-    #   the parent token is propagated to this scope's token via a callback
-    #   (for explicit cancel) and/or the Runtime timer queue (for monotonic
-    #   deadline expiry).  No polling thread is spawned.
-    # @api private
-    def initialize(parent_token: nil)
-      @token = Phronomy::CancellationToken.new
-      @deadline = nil
-
-      if parent_token
-        # Propagate explicit cancel() from parent to child via callback.
-        parent_token.on_cancel { @token.cancel! }
-
-        # Propagate monotonic-deadline expiry from parent to child via the
-        # timer queue (avoids a polling thread).
-        remaining = parent_token.remaining_monotonic_seconds
-        if !remaining.nil?
-          if remaining <= 0
-            @token.cancel!
-          else
-            Phronomy::Runtime.instance.timer_queue.schedule(seconds: remaining) do
-              @token.cancel!
-            end
-          end
-        end
-      end
-    end
-
-    # Attaches a deadline that will cancel this scope after +seconds+.
-    #
-    # @param seconds [Numeric] timeout duration
-    # @return [self]
-    # @api private
-    def deadline_in(seconds)
-      @deadline = Phronomy::Deadline.in(seconds)
-      @deadline.attach_to(@token)
-      self
-    end
-
-    # Cancels this scope immediately.
-    # @return [void]
-    # @api private
-    def cancel!
-      @token.cancel!
-    end
-
-    # Returns +true+ if this scope has been cancelled.
-    # @return [Boolean]
-    # @api private
-    def cancelled?
-      @token.cancelled?
-    end
-
-    # Returns the remaining time in seconds before the deadline expires,
-    # or +nil+ when no deadline is set.
-    # @return [Float, nil]
-    # @api private
-    def remaining_seconds
-      @deadline&.remaining_seconds
-    end
-
-    # Pops from +queue+ with a timeout derived from the attached deadline (or
-    # +fallback_timeout+ seconds when no deadline is set).  If the pop times out,
-    # the scope is cancelled and the block is called (or a {TimeoutError} raised).
-    #
-    # @param queue [Phronomy::AsyncQueue] the queue to pop from
-    # @param fallback_timeout [Numeric, nil] used when no deadline is attached
-    # @yield called when the operation times out
-    # @raise [Phronomy::TimeoutError] when no block is given and a timeout occurs
-    # @return [Object] the popped value
-    # @api private
-    def pop_queue(queue, fallback_timeout: nil)
-      timeout = @deadline&.remaining_seconds || fallback_timeout
-      result = if timeout
-        queue.pop(timeout: timeout)
-      else
-        queue.pop
-      end
-
-      if result.nil?
-        cancel!
-        if block_given?
-          yield
-        else
-          raise Phronomy::TimeoutError, "CancellationScope timed out"
-        end
-      end
-
-      result
-    end
-  end
-end

data/lib/phronomy/cancellation_token.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Provides cooperative cancellation for agent invocations.
-  #
-  # Pass a token to an agent via +config: { cancellation_token: token }+.
-  # The agent checks the token before each LLM call and raises
-  # {Phronomy::CancellationError} when the token is cancelled or the
-  # optional deadline has passed.
-  #
-  # A token may be shared across multiple agent invocations and across threads;
-  # all access to internal state is protected by a Mutex.
-  #
-  # @example Explicit cancel from another thread
-  #   token = Phronomy::CancellationToken.new
-  #   Thread.new { sleep 5; token.cancel! }
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Hard deadline via monotonic clock (recommended)
-  #   token = Phronomy::CancellationToken.timeout_after(30)
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Hard deadline via wall-clock (legacy)
-  #   token = Phronomy::CancellationToken.new(deadline: Time.now + 30)
-  #   result = agent.invoke("...", config: { cancellation_token: token })
-  #
-  # @example Propagate to parallel workers
-  #   token = Phronomy::CancellationToken.new
-  #   orchestrator.dispatch_parallel(task1, task2, cancellation_token: token)
-  class CancellationToken
-    # Returns a new token that will expire after +seconds+ seconds, measured
-    # with the monotonic clock (+Process::CLOCK_MONOTONIC+). Unlike constructing
-    # a token with +deadline: Time.now + seconds+, this factory is immune to NTP
-    # adjustments and DST transitions.
-    #
-    # @param seconds [Numeric] duration in seconds until the token expires.
-    # @return [CancellationToken]
-    # @api public
-    def self.timeout_after(seconds)
-      monotonic_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
-      new(monotonic_deadline: monotonic_deadline)
-    end
-
-    # @param deadline [Time, nil] optional wall-clock deadline; the token reports
-    #   +cancelled?+ as +true+ once +Time.now >= deadline+.  Prefer
-    #   {.timeout_after} for duration-based cancellation.
-    # @param monotonic_deadline [Float, nil] internal monotonic timestamp set by
-    #   {.timeout_after}; prefer that factory method over passing this directly.
-    # @api public
-    def initialize(deadline: nil, monotonic_deadline: nil)
-      @cancelled = false
-      @deadline = deadline
-      @monotonic_deadline = monotonic_deadline
-      @mutex = Mutex.new
-      @cancel_callbacks = []
-    end
-
-    # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
-    attr_reader :deadline
-
-    # Returns the remaining seconds until the monotonic deadline fires, or +nil+
-    # when no monotonic deadline is set.  Returns 0.0 if already past.
-    # @return [Float, nil]
-    # @api public
-    def remaining_monotonic_seconds
-      return nil if @monotonic_deadline.nil?
-      remaining = @monotonic_deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      [remaining, 0.0].max
-    end
-
-    # Registers a one-shot callback invoked when this token is explicitly
-    # cancelled via {#cancel!}.  If the token is already cancelled, the block
-    # is called immediately (still within the caller's thread).
-    #
-    # Callbacks are NOT fired for deadline-based cancellation (i.e. when
-    # {#cancelled?} returns +true+ due to +@monotonic_deadline+ expiry).  Use
-    # {Runtime#timer_queue} to schedule deadline callbacks.
-    #
-    # @yield called with no arguments when (or if) the token is cancelled
-    # @return [self]
-    # @api public
-    def on_cancel(&block)
-      already_cancelled = @mutex.synchronize do
-        if @cancelled
-          true
-        else
-          @cancel_callbacks << block
-          false
-        end
-      end
-      block.call if already_cancelled
-      self
-    end
-
-    # Mark the token as cancelled and fire any registered {#on_cancel} callbacks.
-    # Thread-safe; idempotent — calling multiple times has no additional effect.
-    # @return [self]
-    # @api public
-    def cancel!
-      callbacks = @mutex.synchronize do
-        return self if @cancelled
-        @cancelled = true
-        @cancel_callbacks.dup
-      end
-      callbacks.each(&:call)
-      self
-    end
-
-    # Returns +true+ when the token has been explicitly cancelled via {#cancel!},
-    # when the wall-clock deadline has passed, or when the monotonic deadline
-    # (set by {.timeout_after}) has elapsed. Thread-safe.
-    # @return [Boolean]
-    # @api public
-    def cancelled?
-      return true if @mutex.synchronize { @cancelled }
-      return true if !@deadline.nil? && Time.now >= @deadline
-      !@monotonic_deadline.nil? &&
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_deadline
-    end
-
-    # Raises {Phronomy::CancellationError} if the token is cancelled.
-    # A convenience method for cooperative cancellation checks inside tools,
-    # RAG loaders, and hooks, replacing the +if cancelled? then raise+ pattern.
-    #
-    # @param message [String] optional error message
-    # @return [nil] when the token is not cancelled
-    # @raise [Phronomy::CancellationError] when the token is cancelled
-    # @api public
-    def raise_if_cancelled!(message = "invocation cancelled")
-      raise Phronomy::CancellationError, message if cancelled?
-    end
-  end
-end