phronomy 0.6.0 → 0.7.1

data/lib/phronomy/cancellation_scope.rb

@@ -0,0 +1,123 @@
+# 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

@@ -0,0 +1,133 @@
+# 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

data/lib/phronomy/concurrency_gate.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # A counting semaphore that enforces a concurrency cap across a named
+  # resource category (e.g. agent tasks, tool tasks, LLM calls).
+  #
+  # When +max_concurrent+ is +nil+ the gate is a no-op and all callers
+  # pass through immediately without acquiring a slot.
+  #
+  # Backpressure behaviour when the gate is full is controlled by the
+  # +on_full:+ keyword:
+  #   +:reject+  — raise {Phronomy::BackpressureError} immediately
+  #   +:wait+    — block the calling fiber/thread until a slot is free
+  #   +:timeout+ — like +:wait+ but raises {Phronomy::BackpressureError}
+  #               after +timeout:+ seconds if no slot becomes available
+  #
+  # @example
+  #   gate = Phronomy::ConcurrencyGate.new(max_concurrent: 5, name: :agent)
+  #   gate.acquire(on_full: :reject) do
+  #     run_agent_task
+  #   end
+  class ConcurrencyGate
+    # @param max_concurrent [Integer, nil] concurrency cap; nil = unlimited
+    # @param name [Symbol, String, nil] human-readable label used in error messages
+    # @api private
+    def initialize(max_concurrent:, name: nil)
+      @max = max_concurrent
+      @name = name
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @count = 0
+    end
+
+    # Returns the configured cap (or nil when unlimited).
+    attr_reader :max
+
+    # Returns the name label.
+    attr_reader :name
+
+    # Returns the number of slots currently in use.
+    def current_count
+      @mutex.synchronize { @count }
+    end
+
+    # Acquires a slot, executes +block+, then releases the slot.
+    # When the gate is unlimited (max is nil) the block runs directly.
+    #
+    # @param on_full [:reject, :wait, :timeout] backpressure strategy
+    # @param timeout [Numeric, nil] seconds before +:timeout+ gives up
+    # @yield
+    # @return block return value
+    # @raise [Phronomy::BackpressureError] when +:reject+ or +:timeout+ fires
+    # @api private
+    def acquire(on_full: :wait, timeout: nil, &block)
+      return block.call if @max.nil?
+
+      _acquire_slot(on_full: on_full, timeout: timeout)
+      begin
+        block.call
+      ensure
+        _release_slot
+      end
+    end
+
+    private
+
+    def _acquire_slot(on_full:, timeout:)
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler
+        _acquire_slot_coop(scheduler, on_full: on_full, timeout: timeout)
+      else
+        _acquire_slot_threaded(on_full: on_full, timeout: timeout)
+      end
+    end
+
+    def _acquire_slot_coop(scheduler, on_full:, timeout:)
+      # In cooperative mode all tasks run on the same thread, so no mutex needed.
+      deadline = timeout ? (scheduler.virtual_time + timeout) : nil
+      @coop_signal ||= scheduler.new_signal
+
+      loop do
+        if @count < @max
+          @count += 1
+          return
+        end
+
+        case on_full
+        when :reject
+          raise Phronomy::BackpressureError,
+            "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
+            "increase max_concurrent_#{@name}_tasks or retry later"
+        when :timeout
+          if deadline && scheduler.virtual_time >= deadline
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+          end
+          scheduler.wait_for_signal(@coop_signal)
+          if deadline && scheduler.virtual_time >= deadline
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+          end
+        else # :wait
+          scheduler.wait_for_signal(@coop_signal)
+        end
+      end
+    end
+
+    def _acquire_slot_threaded(on_full:, timeout:)
+      deadline = timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout) : nil
+
+      @mutex.synchronize do
+        loop do
+          if @count < @max
+            @count += 1
+            return
+          end
+
+          case on_full
+          when :reject
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
+              "increase max_concurrent_#{@name}_tasks or retry later"
+          when :timeout
+            remaining = deadline ? (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) : nil
+            if remaining && remaining <= 0
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+            end
+            @cond.wait(@mutex, remaining || nil)
+            # re-check deadline after wakeup
+            if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+            end
+          else # :wait
+            @cond.wait(@mutex)
+          end
+        end
+      end
+    end
+
+    def _release_slot
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @coop_signal
+        @count -= 1
+        scheduler.raise_signal(@coop_signal)
+      else
+        @mutex.synchronize do
+          @count -= 1
+          @cond.signal
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/configuration.rb

@@ -33,16 +33,182 @@ module Phronomy
     # @see Phronomy::EventLoop
     attr_accessor :event_loop
 
-    # When true (default), user input and LLM output are recorded in trace spans.
+    # When true, user input and LLM output are recorded in trace spans.
+    # Defaults to false; set to true only in environments where PII capture is acceptable.
     # Set to false in privacy-sensitive environments to prevent PII from reaching
     # the tracing backend (OTel, Langfuse, etc.).
     attr_accessor :trace_pii
 
+    # Optional logger for framework diagnostic messages (e.g. unreachable-state warnings).
+    # Must respond to +#warn(message)+.  When nil (default), messages are written to +$stderr+
+    # via +Kernel#warn+.
+    # @example
+    #   Phronomy.configure { |c| c.logger = Rails.logger }
+    attr_accessor :logger
+
+    # Grace period (in seconds) before the EventLoop background thread is force-killed
+    # after a cooperative stop request.  Applies both to the overall thread join
+    # and to the drain-and-cancel phase when +stop(drain: true)+ is used.
+    # Default: 5 seconds.
+    # @see Phronomy::EventLoop#stop
+    attr_accessor :event_loop_stop_grace_seconds
+
+    # Global state store for workflow persistence.
+    # When set, WorkflowRunner routes all state reads and writes through this store.
+    # Must be an instance of a class that inherits from Phronomy::StateStore::Base.
+    # Defaults to +nil+ (no persistence — state lives only for the duration of invoke).
+    # @example
+    #   Phronomy.configure { |c| c.state_store = Phronomy::StateStore::InMemory.new }
+    attr_accessor :state_store
+
+    # Maximum byte length of a tool result returned to the LLM.
+    # When a tool returns a String longer than this limit, the string is truncated
+    # and a warning is logged.  Set to +nil+ (default) to disable truncation.
+    # @example
+    #   Phronomy.configure { |c| c.tool_result_max_size = 8192 }
+    attr_accessor :tool_result_max_size
+
+    # LLM adapter used by Agent::Base to perform LLM calls.
+    # Must be an instance of a class that inherits from
+    # {Phronomy::LLMAdapter::Base}.  Defaults to
+    # {Phronomy::LLMAdapter::RubyLLM} which delegates to +chat.ask+ via
+    # {BlockingAdapterPool}.
+    # Set to a custom adapter to swap in an alternative LLM client without
+    # changing any agent code.
+    # @example
+    #   Phronomy.configure { |c| c.llm_adapter = MyAsyncLLMAdapter.new }
+    attr_accessor :llm_adapter
+
+    # Default backpressure strategy for {BlockingAdapterPool#submit} when the
+    # queue is full.  One of +:wait+ (block until a slot is available),
+    # +:raise+ (raise {Phronomy::BackpressureError}), or +:timeout+ (raise
+    # {Phronomy::TimeoutError} after +backpressure_timeout+ seconds).
+    # @return [:wait, :raise, :timeout]
+    attr_accessor :backpressure
+
+    # Seconds to wait before raising {Phronomy::TimeoutError} when
+    # +backpressure+ is +:timeout+.
+    # @return [Numeric, nil]
+    attr_accessor :backpressure_timeout
+
+    # Warn when an event spends longer than this many seconds waiting in the
+    # EventLoop queue before being dispatched (starvation detection).
+    # Set to +nil+ to disable the warning.
+    # @return [Numeric, nil]
+    attr_accessor :event_loop_starvation_threshold_seconds
+
+    # Warn when processing a single event on the EventLoop thread takes longer
+    # than this many seconds (long-running task / blocking-on-loop detection).
+    # Set to +nil+ to disable the warning.
+    # @return [Numeric, nil]
+    attr_accessor :event_loop_dispatch_threshold_seconds
+
+    # When true, enables all blocking operation diagnostics (Issue #279).
+    # Equivalent to setting all diagnostic thresholds to their defaults.
+    # @return [Boolean]
+    attr_accessor :scheduler_debug
+
+    # Wall-clock threshold (milliseconds) after which a task that has not
+    # yielded the scheduler emits a warning log.  nil disables the check.
+    # @return [Float, nil]
+    attr_accessor :blocking_detect_threshold_ms
+
+    # Maximum number of concurrent agent tasks (invoke_async calls in-flight).
+    # nil = unlimited (default).  When at capacity, behaviour is controlled by
+    # +backpressure+ (:wait, :raise/:reject, :timeout).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_agent_tasks
+
+    # Maximum number of concurrent tool tasks (parallel tool calls in-flight).
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_tool_tasks
+
+    # Maximum number of concurrent workflow tasks.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_workflow_tasks
+
+    # Maximum number of concurrent LLM calls in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_llm_calls
+
+    # Upper bound on the number of streaming token chunks that may be buffered
+    # in the {AsyncQueue} used by {Agent#stream} before the LLM producer is
+    # throttled.  When nil (default), the queue is unbounded.
+    # @return [Integer, nil]
+    attr_accessor :stream_queue_max_size
+
+    # Maximum number of concurrent RAG knowledge-source fetches in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_rag_fetches
+
+    # Maximum number of concurrent vector-store searches in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_vector_searches
+
+    # Scheduler starvation threshold (milliseconds).
+    # When a task waits more than this many milliseconds after calling
+    # +runtime.yield+ before being resumed, the wait is counted as a starvation
+    # event.  Used by the fairness regression test and by the
+    # +tasks_waiting_over_threshold+ metric on {Phronomy::Runtime}.
+    # Default: 50ms.
+    # @return [Numeric]
+    attr_accessor :starvation_threshold_ms
+
+    # Scheduler backend to use for new {Phronomy::Runtime} instances.
+    #
+    # | Value | Scheduler | Typical use |
+    # |-------|-----------|-------------|
+    # | +:thread+ | {Runtime::ThreadScheduler} | **Default** — production-ready; one OS thread per task |
+    # | +:immediate+ | {Runtime::FakeScheduler} | Tests — tasks run synchronously, no extra threads |
+    # | +:fiber+ | {Runtime::DeterministicScheduler} (autorun) | **EXPERIMENTAL** — Fiber-based cooperative scheduler; do not use as production default |
+    # | +:cooperative+ | {Runtime::FakeScheduler} | **Deprecated** — alias for +:immediate+; do not use in new code |
+    #
+    # The default is +:thread+. The +:fiber+ backend remains experimental and opt-in;
+    # it will not become the default until integration test coverage is production grade
+    # and virtual-time/timeout semantics are fully resolved (see Issues #350, #347, #348).
+    #
+    # When this setting is changed, the change only takes effect on the NEXT
+    # call to {Runtime.instance} that auto-creates a new instance (i.e. after the
+    # previous instance has been replaced or reset).  To replace the current
+    # instance immediately call +Phronomy::Runtime.instance = nil+ first.
+    #
+    # @return [:thread, :immediate, :fiber]
+    attr_accessor :runtime_backend
+
+    # When +true+, calling {Agent#invoke} from inside a scheduler task
+    # raises {SchedulerReentrancyError}.  When +false+ (default), a warning
+    # is logged instead so that existing callers have time to migrate.
+    # @return [Boolean]
+    attr_accessor :strict_runtime_guards
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
-      @trace_pii = true
+      @trace_pii = false
       @event_loop = false
+      @event_loop_stop_grace_seconds = 5
+      @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+      @backpressure = :wait
+      @backpressure_timeout = nil
+      @event_loop_starvation_threshold_seconds = nil
+      @event_loop_dispatch_threshold_seconds = nil
+      @scheduler_debug = false
+      @blocking_detect_threshold_ms = nil
+      @max_concurrent_agent_tasks = nil
+      @max_concurrent_tool_tasks = nil
+      @max_concurrent_workflow_tasks = nil
+      @max_concurrent_llm_calls = nil
+      @stream_queue_max_size = nil
+      @max_concurrent_rag_fetches = nil
+      @max_concurrent_vector_searches = nil
+      @starvation_threshold_ms = 50
+      @runtime_backend = :thread
+      @strict_runtime_guards = false
     end
   end
 end

data/lib/phronomy/context/assembler.rb

@@ -35,12 +35,14 @@ module Phronomy
       # @param type    [Symbol, String]
       # @param trusted [Boolean]
       # @return [String]
+      # @api private
       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]
       #   when nil no token trimming is performed
+      # @api private
       def initialize(budget: nil)
         @budget = budget
         @instruction = nil
@@ -53,6 +55,7 @@ module Phronomy
       #
       # @param text [String]
       # @return [self]
+      # @api private
       def add_instruction(text)
         @instruction = text.to_s
         self
@@ -67,6 +70,7 @@ module Phronomy
       # @param source  [String, nil]     optional source label (e.g. filename); included in the
       #   XML tag so the LLM can produce grounded citations. Omitted when nil.
       # @return [self]
+      # @api private
       def add_knowledge(text, type:, trusted: false, source: nil)
         @knowledge_chunks << {text: text.to_s, type: type.to_s, trusted: trusted, source: source}
         self
@@ -76,6 +80,7 @@ module Phronomy
       #
       # @param messages [Array] message-like objects with #role and #content
       # @return [self]
+      # @api private
       def add_messages(messages)
         @messages = Array(messages)
         self
@@ -86,6 +91,7 @@ module Phronomy
       # @return [Hash{Symbol => Object}]
       #   :system   [String, nil]  combined system prompt (instruction + knowledge XML tags)
       #   :messages [Array]        conversation messages, trimmed to budget if set
+      # @api private
       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

data/lib/phronomy/context/compaction_context.rb

@@ -45,6 +45,7 @@ module Phronomy
       # @param thread_id [String, nil] used when saving compaction records
       # @param memory [Object, nil] memory object; must respond to #save_compaction
       #   for compaction records to be persisted
+      # @api private
       def initialize(message_elements:, budget:, thread_id: nil, memory: nil)
         @message_elements = message_elements.dup
         @budget = budget
@@ -67,6 +68,7 @@ module Phronomy
       # @yieldparam elements [Array<Hash>] the selected message elements
       # @yieldreturn [String] summary text to replace the selected messages
       # @return [Array] the updated result_messages array
+      # @api private
       def compact(range)
         # Normalise: Integer index → single-element Array; Range → Array slice.
         raw = @message_elements[range]

data/lib/phronomy/context/context_version_cache.rb

@@ -25,6 +25,7 @@ module Phronomy
       #
       # @param fingerprint [String] SHA-256 hex digest to compare
       # @return [Boolean]
+      # @api private
       def valid?(fingerprint)
         !@fingerprint.nil? && !@system_text.nil? && @fingerprint == fingerprint
       end
@@ -33,6 +34,7 @@ module Phronomy
       #
       # @param fingerprint  [String] new SHA-256 hex digest
       # @param system_text  [String] fully assembled system prompt text
+      # @api private
       def update(fingerprint:, system_text:)
         @fingerprint = fingerprint
         @system_text = system_text.to_s