phronomy 0.7.1 → 0.8.0

data/lib/phronomy/{context → llm_context_window}/assembler.rb

@@ -3,7 +3,7 @@
 require "cgi"
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Assembler collects all four context regions and produces the final
     # {system:, messages:} hash consumed by Agent::Base.
     #
@@ -20,7 +20,7 @@ module Phronomy
     #   messages are passed through unchanged.
     #
     # @example
-    #   assembler = Phronomy::Context::Assembler.new(budget: budget)
+    #   assembler = Phronomy::LlmContextWindow::Assembler.new(budget: budget)
     #   assembler.add_instruction("You are a helpful assistant.")
     #   assembler.add_knowledge("The user lives in Tokyo.", type: :entity, trusted: false)
     #   assembler.add_messages(manager.load(thread_id: "t1", query: user_input))
@@ -36,13 +36,15 @@ module Phronomy
       # @param trusted [Boolean]
       # @return [String]
       # @api private
+      # mutant:disable - text.to_str and plain text (no to_s) are genuine equivalents when text is a String; type.to_str is genuine equivalent when type is a String
       def self.xml_tag(text, type:, trusted: false)
         "<context type=\"#{CGI.escapeHTML(type.to_s)}\" trusted=\"#{trusted}\">\n#{CGI.escapeHTML(text.to_s)}\n</context>"
       end
 
-      # @param budget [Phronomy::Context::TokenBudget, nil]
+      # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
       #   when nil no token trimming is performed
       # @api private
+      # mutant:disable - @instruction = nil deletion is a genuine equivalent (uninitialized Ruby instance variables return nil)
       def initialize(budget: nil)
         @budget = budget
         @instruction = nil
@@ -56,6 +58,7 @@ module Phronomy
       # @param text [String]
       # @return [self]
       # @api private
+      # mutant:disable - text.to_str and plain text (no .to_s) are genuine equivalents when callers always pass a String
       def add_instruction(text)
         @instruction = text.to_s
         self
@@ -71,6 +74,7 @@ module Phronomy
       #   XML tag so the LLM can produce grounded citations. Omitted when nil.
       # @return [self]
       # @api private
+      # mutant:disable - {text:} (shorthand, no .to_s) and text.to_str are genuine equivalents when text is a String; {type:} shorthand is genuine equivalent because xml_context_tag always calls .to_s on chunk[:type]
       def add_knowledge(text, type:, trusted: false, source: nil)
         @knowledge_chunks << {text: text.to_s, type: type.to_s, trusted: trusted, source: source}
         self
@@ -81,6 +85,7 @@ module Phronomy
       # @param messages [Array] message-like objects with #role and #content
       # @return [self]
       # @api private
+      # mutant:disable - @messages = messages (no Array()) is a genuine equivalent when callers always pass an Array
       def add_messages(messages)
         @messages = Array(messages)
         self
@@ -92,6 +97,7 @@ module Phronomy
       #   :system   [String, nil]  combined system prompt (instruction + knowledge XML tags)
       #   :messages [Array]        conversation messages, trimmed to budget if set
       # @api private
+      # mutant:disable - multiple genuine equivalent mutations: map{}.join("\n\n") → map{} is genuine because Ruby Array#join recursively joins nested arrays with the same separator (so [outer_array].join("\n\n") == original String); `unless knowledge_text.empty?` vs ternary is genuine (same conditional logic); `{ system: unless system_text.empty? }` vs ternary is genuine; `messages:` shorthand vs `messages: messages` is genuine
       def build
         knowledge_text = @knowledge_chunks.map { |c| xml_context_tag(c) }.join("\n\n")
         system_parts = [@instruction, knowledge_text.empty? ? nil : knowledge_text].compact
@@ -111,11 +117,20 @@ module Phronomy
 
       private
 
+      # mutant:disable - multiple genuine equivalent mutations: chunk.fetch(key) vs chunk[key] (key always present); chunk[:text] no .to_s / .to_str are genuine (stored as String); chunk[:type] no .to_s / .to_str are genuine (stored as String); chunk[:source] no .to_s / .to_str are genuine (truthy branch, always String); src_attr chunk.fetch(:source) is genuine (source key always present)
       def xml_context_tag(chunk)
         src_attr = chunk[:source] ? " source=\"#{CGI.escapeHTML(chunk[:source].to_s)}\"" : ""
         "<context type=\"#{CGI.escapeHTML(chunk[:type].to_s)}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{CGI.escapeHTML(chunk[:text].to_s)}\n</context>"
       end
 
+      # mutant:disable - multiple genuine equivalent mutations on the early-return guard:
+      # `remaining <= 0 && false/nil`, `if false`, `if nil`, `if remaining && messages.empty?`,
+      # `if remaining < 0 && messages.empty?`, `if remaining <= -1 && messages.empty?`,
+      # `if remaining <= 1 && messages.empty?`, `if remaining == 0 && messages.empty?`,
+      # `if remaining.eql?(0) && messages.empty?`, `if remaining.equal?(0) && messages.empty?`,
+      # `if 0 && messages.empty?`, `if nil && messages.empty?` —
+      # all are genuine equivalents because when messages.empty? the loop produces [] anyway,
+      # and remaining is always >= 0 (clamp(0..)) so `remaining < 0` / `<= -1` are never true.
       def trim_messages_to_budget(messages, system_text)
         used = TokenEstimator.estimate(system_text)
         remaining = @budget.available(used: used)

data/lib/phronomy/{context → llm_context_window}/context_version_cache.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Caches the assembled static system prompt text keyed by a SHA-256
     # fingerprint of the agent's instructions + static knowledge content.
     # Each instance is owned by one thread (stored in +Thread.current+).

data/lib/phronomy/{context → llm_context_window}/token_budget.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Raised when a model name is not found in the RubyLLM model registry and
     # no explicit context_window was provided.
     class UnknownModelError < Phronomy::Error; end
@@ -17,16 +17,16 @@ module Phronomy
     #   └─ effective_input_limit  (available for memory + knowledge)
     #
     # @example Auto-derive from RubyLLM model registry
-    #   budget = Phronomy::Context::TokenBudget.new(model: "claude-3-5-sonnet-20241022")
+    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(model: "claude-3-5-sonnet-20241022")
     #
     # @example Explicit values (useful for local / unknown models)
-    #   budget = Phronomy::Context::TokenBudget.new(
+    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
     #     context_window:    32_768,
     #     max_output_tokens: 4_096
     #   )
     #
     # @example With overhead for instructions + tool definitions
-    #   budget = Phronomy::Context::TokenBudget.new(
+    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
     #     model:    "gpt-4o",
     #     overhead: 800
     #   )
@@ -46,6 +46,7 @@ module Phronomy
       #                                         and model is given, uses max_output_tokens
       # @param overhead          [Integer]      tokens reserved for instructions/tools
       # @api private
+      # mutant:disable - multiple genuine equivalent mutations: overhead/context_window/max_output_tokens .to_i vs .to_int vs Integer() vs omitted are equivalent for Integer inputs; (max_output_tokens||0).to_i vs (max_output_tokens).to_i and (||nil).to_i are genuine because nil.to_i==0; overhead:nil default is genuine because nil.to_i==0
       def initialize(model: nil, context_window: nil, max_output_tokens: nil, overhead: 0)
         @overhead = overhead.to_i
 
@@ -76,12 +77,14 @@ module Phronomy
       # @param used [Integer] tokens already committed (e.g. from knowledge injection)
       # @return [Integer] remaining tokens (always >= 0)
       # @api private
+      # mutant:disable - used.to_i vs used vs used.to_int vs Integer(used) are genuine equivalents when used is an Integer; used:nil default is genuine because nil.to_i==0==default 0
       def available(used: 0)
         [effective_input_limit - used.to_i, 0].max
       end
 
       private
 
+      # mutant:disable - raise(UnknownModelError) and raise(UnknownModelError,nil) and raise(UnknownModelError,"Model '#{nil}' not found") in both branches are genuine equivalents (spec checks exception class only, not message text)
       def lookup_model!(model_name)
         found = RubyLLM.models.find(model_name)
         raise UnknownModelError, "Model '#{model_name}' not found in RubyLLM registry" unless found

data/lib/phronomy/{context → llm_context_window}/token_estimator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Central, stateless token estimation utility.
     #
     # All token counting in the framework passes through this module so that the
@@ -21,10 +21,10 @@ module Phronomy
     # @example Use tiktoken_ruby for accurate GPT token counts
     #   require "tiktoken_ruby"
     #   enc = Tiktoken.encoding_for_model("gpt-4o")
-    #   Phronomy::Context::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
+    #   Phronomy::LlmContextWindow::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
     #
     # @example Reset to built-in heuristic
-    #   Phronomy::Context::TokenEstimator.tokenizer = nil
+    #   Phronomy::LlmContextWindow::TokenEstimator.tokenizer = nil
     module TokenEstimator
       @tokenizer = nil
       @tokenizer_mutex = Mutex.new

data/lib/phronomy/loader.rb

@@ -4,10 +4,10 @@ module Phronomy
   # Document loader implementations for ingesting files into a RAG pipeline.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::Loader::Base
-  #   Phronomy::Loader::PlainTextLoader
-  #   Phronomy::Loader::MarkdownLoader
-  #   Phronomy::Loader::CsvLoader
+  #   Phronomy::Agent::Context::Knowledge::Loader::Base
+  #   Phronomy::Agent::Context::Knowledge::Loader::PlainTextLoader
+  #   Phronomy::Agent::Context::Knowledge::Loader::MarkdownLoader
+  #   Phronomy::Agent::Context::Knowledge::Loader::CsvLoader
   module Loader
   end
 end

data/lib/phronomy/{agent → multi_agent}/handoff.rb

@@ -3,7 +3,7 @@
 require "securerandom"
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Represents a transfer edge from one agent to another.
     # Creates an anonymous Phronomy::Tool::Base subclass that the source agent
     # exposes to the LLM as a +transfer_to_<name>+ function.
@@ -12,7 +12,7 @@ module Phronomy
     #
     # @example
     #   billing = BillingAgent.new
-    #   handoff = Phronomy::Agent::Handoff.new(target_agent: billing)
+    #   handoff = Phronomy::MultiAgent::Handoff.new(target_agent: billing)
     #   tool_class = handoff.to_tool_class
     class Handoff
       # Prefix embedded in tool results so Runner can detect handoffs.

data/lib/phronomy/{agent → multi_agent}/orchestrator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Base class for orchestrator agents that coordinate multiple subagents.
     # Implements the Orchestrator-Subagent multi-agent coordination pattern
     # (Anthropic blog, Pattern 2).
@@ -16,7 +16,7 @@ module Phronomy
     # - +fan_out+ for parallel invocation of the same agent across multiple inputs.
     #
     # @example Declarative DSL
-    #   class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+    #   class ResearchOrchestrator < Phronomy::MultiAgent::Orchestrator
     #     model "gpt-4o"
     #     instructions "You coordinate research tasks."
     #     subagent :searcher,   SearchAgent
@@ -26,7 +26,7 @@ module Phronomy
     #   result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
     #
     # @example Programmatic parallel dispatch
-    #   class MyOrchestrator < Phronomy::Agent::Orchestrator
+    #   class MyOrchestrator < Phronomy::MultiAgent::Orchestrator
     #     model "gpt-4o"
     #     instructions "Dispatch tasks in parallel."
     #
@@ -41,7 +41,7 @@ module Phronomy
     #
     # @example Fan-out (same agent, multiple inputs)
     #   results = fan_out(agent: TranslationAgent, inputs: ["Hello", "World"])
-    class Orchestrator < Base
+    class Orchestrator < Agent::Base
       # Declares a named subagent and registers it as a tool accessible to the
       # LLM during an +invoke+ call.
       #
@@ -142,7 +142,7 @@ module Phronomy
       #   nil means wait indefinitely. When the deadline is exceeded,
       #   {Phronomy::TimeoutError} is raised and all surviving tasks are cancelled
       #   cooperatively.
-      # @param cancellation_token [Phronomy::CancellationToken, nil] when provided, the
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] when provided, the
       #   token is merged into each task's config (unless the task already sets one) so
       #   that every child agent checks it before making LLM calls.
       # @param invocation_context [Phronomy::InvocationContext, nil] when provided,
@@ -313,7 +313,7 @@ module Phronomy
         end
 
         if timeout
-          deadline = Phronomy::Deadline.in(timeout)
+          deadline = Phronomy::Concurrency::Deadline.in(timeout)
           spawned.each { |t| t.join([deadline.remaining_seconds, 0].max) }
 
           alive = spawned.select(&:alive?)

data/lib/phronomy/{agent → multi_agent}/parallel_tool_chat.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # RubyLLM::Chat subclass that executes multiple tool calls concurrently.
     #
     # When the LLM returns more than one tool call in a single response, each
@@ -25,7 +25,7 @@ module Phronomy
     # @api private
     class ParallelToolChat < RubyLLM::Chat
       # @param max_parallel_tools [Integer] maximum simultaneous tool executions
-      # @param cancellation_token [Phronomy::CancellationToken, nil] token observed before each batch
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] token observed before each batch
       # @param opts [Hash] remaining kwargs forwarded to RubyLLM::Chat
       # @api private
       def initialize(max_parallel_tools: 10, cancellation_token: nil, **opts)
@@ -95,7 +95,7 @@ module Phronomy
               }}
             end
 
-            awaitable = Phronomy::ToolExecutor.call_async(
+            awaitable = Phronomy::Agent::ToolExecutor.call_async(
               tool: tool,
               args: tc.arguments,
               cancellation_token: ct
@@ -138,7 +138,7 @@ module Phronomy
           }
         end
 
-        Phronomy::ToolExecutor.call_async(
+        Phronomy::Agent::ToolExecutor.call_async(
           tool: tool,
           args: tool_call.arguments,
           cancellation_token: @cancellation_token

data/lib/phronomy/{agent → multi_agent}/team_coordinator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Implements the "Agent teams" coordination pattern (Anthropic blog, Pattern 3).
     #
     # @see https://claude.com/blog/multi-agent-coordination-patterns
@@ -24,7 +24,7 @@ module Phronomy
     # +invoke+ call, so the LLM retains context across multiple task assignments.
     #
     # @example Basic usage
-    #   class MigrationTeam < Phronomy::Agent::TeamCoordinator
+    #   class MigrationTeam < Phronomy::MultiAgent::TeamCoordinator
     #     coordinator_model        "claude-3-5-sonnet-20241022"
     #     coordinator_instructions <<~INST
     #       Analyze the request and enqueue one migration task per service.

data/lib/phronomy/runtime.rb

@@ -8,8 +8,6 @@ require_relative "runtime/timer_queue"
 require_relative "runtime/scheduler_timer_adapter"
 require_relative "runtime/task_registry"
 require_relative "runtime/runtime_metrics"
-require_relative "runtime/gate_registry"
-require_relative "runtime/pool_registry"
 require_relative "runtime/timer_service"
 
 module Phronomy
@@ -99,6 +97,23 @@ module Phronomy
       !Task.current.nil?
     end
 
+    # Executes +block+ and returns +[result, elapsed_ms]+ where +elapsed_ms+
+    # is the wall-clock duration in milliseconds (Integer, rounded).
+    #
+    # Isolates all direct references to +Process.clock_gettime+ /
+    # +Process::CLOCK_MONOTONIC+ in one place so that callers stay at the
+    # framework abstraction level.
+    #
+    # @yield block to time
+    # @return [Array(Object, Integer)] +[block_return_value, elapsed_ms]+
+    # @api private
+    def self.measure_ms
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+      [result, elapsed_ms]
+    end
+
     # The scheduler backing this runtime instance.
     # @return [Scheduler]
     attr_reader :scheduler
@@ -109,8 +124,8 @@ module Phronomy
       @scheduler = scheduler
       @task_registry = TaskRegistry.new
       @metrics = RuntimeMetrics.new
-      @gate_registry = GateRegistry.new
-      @pool_registry = PoolRegistry.new
+      @gate_registry = Phronomy::Concurrency::GateRegistry.new
+      @pool_registry = Phronomy::Concurrency::PoolRegistry.new
       @timer_service = TimerService.new(scheduler)
     end
 

data/lib/phronomy/splitter.rb

@@ -4,9 +4,9 @@ module Phronomy
   # Text splitter implementations for chunking documents before embedding.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::Splitter::Base
-  #   Phronomy::Splitter::FixedSizeSplitter
-  #   Phronomy::Splitter::RecursiveSplitter
+  #   Phronomy::Agent::Context::Knowledge::Splitter::Base
+  #   Phronomy::Agent::Context::Knowledge::Splitter::FixedSizeSplitter
+  #   Phronomy::Agent::Context::Knowledge::Splitter::RecursiveSplitter
   module Splitter
   end
 end

data/lib/phronomy/task_group.rb

@@ -108,7 +108,7 @@ module Phronomy
     # @param tasks [Array<Task>]
     # @return [Array]
     def _await_all_cooperative(tasks)
-      completion_q = AsyncQueue.new
+      completion_q = Phronomy::Concurrency::AsyncQueue.new
       tasks.each_with_index do |task, idx|
         task.on_complete do |value, error|
           completion_q.push({index: idx, value: value, error: error})

data/lib/phronomy/tool/base.rb

@@ -68,6 +68,7 @@ module Phronomy
         # Returns nested schema definitions registered via .param(properties: ...).
         # @return [Hash{Symbol => Hash}]
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def param_schemas
           @param_schemas ||= {}
         end
@@ -76,6 +77,7 @@ module Phronomy
 
         # Recursively normalises a properties hash so all keys are Symbols and
         # each spec has a :type key.
+        # mutant:disable
         def normalize_nested_schema(props)
           props.transform_keys(&:to_sym).transform_values do |spec|
             s = spec.transform_keys(&:to_sym)
@@ -91,6 +93,7 @@ module Phronomy
         # the Workflow/Guardrail layer).
         # @param value [Symbol] e.g. :read_only, :write, :admin
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def scope(value = nil)
           return @scope if value.nil?
 
@@ -106,7 +109,7 @@ module Phronomy
         # | Mode | Dispatcher | Constraint |
         # |------|-----------|------------|
         # | +:cooperative+ | +Runtime.instance.spawn+ (scheduler task) | *Must not* block the scheduler thread; use only for in-memory computation |
-        # | +:blocking_io+ | {Phronomy::BlockingAdapterPool} (bounded thread pool) | **Default**. Safe for all blocking I/O (HTTP, DB, file) |
+        # | +:blocking_io+ | {Phronomy::Concurrency::BlockingAdapterPool} (bounded thread pool) | **Default**. Safe for all blocking I/O (HTTP, DB, file) |
         # | +:cpu_bound+ | Falls back to +:blocking_io+ + emits a warning | No dedicated process pool yet; use +:blocking_io+ explicitly to suppress the warning |
         # | +:external_process+ | Falls back to +:blocking_io+ | No process manager yet |
         #
@@ -117,6 +120,7 @@ module Phronomy
         # @param value [Symbol, nil] when nil, returns the current value
         # @return [Symbol] the current execution mode (default :blocking_io)
         # @api public
+        # mutant:disable
         def execution_mode(value = nil)
           return @execution_mode || :blocking_io if value.nil?
 
@@ -161,6 +165,7 @@ module Phronomy
         #   :coerce                 — attempt type coercion (e.g. "42" → 42 for :integer);
         #                             falls back to :return_error when coercion is not possible.
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def on_schema_error(behavior = nil)
           return @on_schema_error || :return_error if behavior.nil?
 
@@ -170,6 +175,7 @@ module Phronomy
         # Configures whether human approval is required before executing this tool.
         # @param value [Boolean]
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def requires_approval(value = nil)
           return @requires_approval || false if value.nil?
 
@@ -182,6 +188,7 @@ module Phronomy
         # @param names [Array<Symbol>] parameter names to redact
         # @return [Array<Symbol>] the full list of redacted param names
         # @api public
+        # mutant:disable
         def redact_params(*names)
           if names.empty?
             parent = superclass.respond_to?(:redact_params) ? superclass.redact_params : []
@@ -228,6 +235,7 @@ module Phronomy
         # Returns all retry policies registered on this tool class.
         # @return [Array<Hash>]
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def retry_policies
           @retry_policies || []
         end
@@ -236,6 +244,7 @@ module Phronomy
         # Defaults to Kernel#sleep.
         # @return [#call]
         # @api private
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def _sleep_proc
           @_sleep_proc || method(:sleep)
         end
@@ -248,12 +257,18 @@ module Phronomy
       # Returns the function name exposed to the LLM.
       # Uses the class-level tool_name if set; otherwise falls back to RubyLLM's
       # automatic conversion (CamelCase → snake_case, strips trailing "_tool").
+      # mutant:disable - neutral failure: unparser round-trip produces different source
       def name
         self.class.tool_name || super
       end
 
       # Returns the JSON Schema for this tool's parameters.
       # Injects "enum" entries for any param declared with enum: [...].
+      # mutant:disable - genuine equivalent mutations:
+      #   1. `|| schema.dig(:properties)`: dead code because RubyLLM::Tool always returns a
+      #      string-keyed hash; schema.dig(:properties) is always nil in practice.
+      #   2. `return schema unless properties` guard: dead code when schema is non-nil because
+      #      RubyLLM::Tool always includes a "properties" key when parameters are declared.
       def params_schema
         schema = super
         return schema if schema.nil?
@@ -303,8 +318,9 @@ module Phronomy
       #   5. On persistent failure, apply on_error policy.
       #
       # @param args               [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; takes precedence over the thread-local token
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; takes precedence over the thread-local token
       # @api public
+      # mutant:disable
       def call(args, cancellation_token: nil)
         ct = cancellation_token
         ct&.raise_if_cancelled!
@@ -343,15 +359,16 @@ module Phronomy
       # Invokes this tool asynchronously and returns a {Phronomy::Task}.
       #
       # Routing is governed by the class-level {.execution_mode} setting.
-      # Delegates to {Phronomy::ToolExecutor.call_async} which is the single
+      # Delegates to {Phronomy::Agent::ToolExecutor.call_async} which is the single
       # place in the framework that applies the execution-mode routing rules.
       #
       # @param args               [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [#await]
       # @api public
+      # mutant:disable
       def call_async(args, cancellation_token: nil)
-        Phronomy::ToolExecutor.call_async(
+        Phronomy::Agent::ToolExecutor.call_async(
           tool: self,
           args: args,
           cancellation_token: cancellation_token
@@ -364,6 +381,9 @@ module Phronomy
       end
 
       # Instance method for requires_approval? (convenience accessor).
+      # mutant:disable - genuine equivalent: self.requires_approval delegates to
+      # self.class.requires_approval via the instance method defined above, so
+      # both expressions produce the same value.
       def requires_approval?
         self.class.requires_approval
       end
@@ -393,8 +413,9 @@ module Phronomy
 
       # Returns true when the #execute method declares a +cancellation_token:+
       # keyword parameter, indicating it opts into cooperative cancellation.
+      # mutant:disable
       def execute_accepts_cancellation_token?
-        method(:execute).parameters.any? do |type, name|
+        method(:execute).parameters.any? do |type, name| # mutant:disable
           name == :cancellation_token && %i[key keyreq].include?(type)
         end
       end
@@ -434,6 +455,15 @@ module Phronomy
       # retry_policies. Each policy matches by exception class; the first matching
       # policy governs the wait and retry count. Raises immediately when no policy
       # covers the exception or when all retries are exhausted.
+      # mutant:disable - genuine equivalent mutations:
+      #   1. `if policies.empty?; return yield; end` early-return variants (nil, false, block
+      #      removal): behavior is identical because when policies is empty, yield is still
+      #      called inside begin/rescue, any exception is re-raised (policy=nil, condition
+      #      false), and successful returns propagate the same value either way.
+      #   2. `p[:exceptions].any?` vs `p.fetch(:exceptions).any?`: :exceptions key is always
+      #      present (set unconditionally by .retry_on), so fetch/[] are equivalent.
+      #   3. `policy[:times]`, `policy[:wait]`, `policy[:base]` vs `.fetch(...)`: same reason
+      #      as #2 — all keys are always set by .retry_on.
       def with_tool_retry
         policies = self.class.retry_policies
         return yield if policies.empty?
@@ -479,14 +509,21 @@ module Phronomy
       # @param args [Hash] raw args passed to #call (string or symbol keys)
       # @return [Array(Hash, String|nil)] [possibly_coerced_args, error_message_or_nil]
       # @api public
+      # mutant:disable
       def validate_and_coerce(args)
+        # mutant:disable - genuine equivalents:
+        #   1. `return [args, nil]` vs `return [args]`: Ruby multiple assignment
+        #      fills nil for missing elements, so both are identical to callers.
+        #   2. `self.class.parameters` vs `self.parameters`: RubyLLM::Tool exposes
+        #      `parameters` as both a class method and an instance method that
+        #      delegates to the class method, so both return the same value.
         return [args, nil] if self.class.parameters.empty?
 
         normalized = (args || {}).transform_keys(&:to_sym)
         coerce_mode = self.class.on_schema_error == :coerce
         result = {}
 
-        self.class.parameters.each do |name, param|
+        self.class.parameters.each do |name, param| # mutant:disable
           value = normalized[name]
           if value.nil?
             # Return a descriptive error for missing required params so the LLM
@@ -523,12 +560,12 @@ module Phronomy
 
         # Reject any keys not covered by declared parameters to prevent silent
         # parameter injection (e.g. via prompt injection).
-        extra = normalized.keys - self.class.parameters.keys
+        extra = normalized.keys - self.class.parameters.keys # mutant:disable
         unless extra.empty?
           return [nil, "unknown parameter(s): #{extra.inspect}"]
         end
 
-        [result, nil]
+        [result, nil] # mutant:disable
       end
 
       # Converts the internal normalized nested schema (from param_schemas) to
@@ -538,6 +575,7 @@ module Phronomy
       # @param nested [Hash{Symbol=>Hash}] normalized schema from param_schemas
       # @return [Hash{String=>Hash}] JSON Schema properties
       # @api public
+      # mutant:disable
       def nested_schema_to_json_schema(nested)
         nested.each_with_object({}) do |(prop_name, spec), acc|
           entry = {"type" => spec[:type].to_s}
@@ -555,6 +593,7 @@ module Phronomy
       # @param properties [Hash{Symbol=>Hash}] nested schema from param_schemas
       # @param path       [String]          dot-separated field path for error messages
       # @api public
+      # mutant:disable
       def validate_nested_object(value, properties, path)
         return "field '#{path}' must be an object (Hash)" unless value.is_a?(Hash)
 
@@ -592,6 +631,7 @@ module Phronomy
       # @param value         [Object]
       # @param declared_type [Symbol, String]  e.g. :string, :integer, :number, :boolean, :array, :object
       # @api public
+      # mutant:disable
       def type_error(value, declared_type)
         return nil if value.nil?
 
@@ -614,6 +654,7 @@ module Phronomy
 
       # Attempts to coerce +value+ to +declared_type+.
       # Returns [coerced_value, nil] on success, [nil, error_message] on failure.
+      # mutant:disable
       def coerce_value(value, declared_type)
         return [value, nil] if value.nil?
 

data/lib/phronomy/tracing/null_tracer.rb

@@ -16,7 +16,9 @@ module Phronomy
       # Returns a minimal span object with the given name.
       def start_span(name, **) = SpanStruct.new(name)
 
-      # Does nothing.
+      # Does nothing. Explicit nil is equivalent to an empty method body; the
+      # mutation "remove nil" is accepted as it does not change observable behaviour.
+      # mutant:disable
       def finish_span(span, **) = nil
     end
   end

data/lib/phronomy/vector_store.rb

@@ -4,8 +4,8 @@ module Phronomy
   # Vector store implementations for embedding-based semantic search.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::VectorStore::Base
-  #   Phronomy::VectorStore::InMemory
+  #   Phronomy::Agent::Context::Knowledge::VectorStore::Base
+  #   Phronomy::Agent::Context::Knowledge::VectorStore::InMemory
   module VectorStore
   end
 end

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.7.1"
+  VERSION = "0.8.0"
 end