phronomy 0.19.0 → 0.21.0

data/lib/phronomy/engine/task.rb

@@ -3,20 +3,29 @@
 module Phronomy
   # A thread-free asynchronous completion handle.
   #
-  # Task no longer executes work. Execution belongs to EventLoop/FSMSession or
-  # OffloadPool. Task only represents completion, failure, cancellation,
-  # callbacks and a blocking wait for external callers.
+  # Task does not execute work. Execution belongs to EventLoop/FSMSession or
+  # OffloadPool. Task represents completion, failure, cancellation, callbacks,
+  # and a blocking wait for callers outside EventLoop.
+  #
+  # Framework components own Task settlement. Application code should observe a
+  # Task through {#wait_result}, {#on_complete}, {#map}, and state readers rather
+  # than calling {#complete}, {#fail}, or {#cancel!}. Operation-wide cancellation
+  # is supplied through the CancellationToken accepted by the API that created
+  # the Task.
   class Task
     STATES = %i[pending completed failed cancelled].freeze
     TERMINAL_STATES = %i[completed failed cancelled].freeze
     private_constant :TERMINAL_STATES
 
+    # Creates an unsettled completion handle for framework-owned execution.
+    # @api private
     def self.deferred(name: nil, parent: nil)
       new(name: name, parent: parent)
     end
 
     attr_reader :name, :parent
 
+    # @api private
     def initialize(name: nil, parent: nil)
       @name = name
       @parent = parent
@@ -30,20 +39,35 @@ module Phronomy
       parent&.register_child(self)
     end
 
+    # @return [Symbol] :pending, :completed, :failed, or :cancelled
+    # @api public
     def status
       @mutex.synchronize { @status }
     end
 
+    # @return [Boolean] whether the Task has reached a terminal state
+    # @api public
     def done?
       @mutex.synchronize { TERMINAL_STATES.include?(@status) }
     end
 
+    # @return [Boolean] whether the Task has not yet reached a terminal state
+    # @api public
     def alive?
       !done?
     end
 
-    # Blocks the calling thread until settlement. EventLoop is never allowed to
-    # wait for a Task; it must continue through explicit events instead.
+    # Blocks the calling thread until settlement.
+    #
+    # EventLoop is never allowed to wait for a Task; framework continuation must
+    # proceed through explicit events. The optional timeout is waiter-local: it
+    # does not settle or cancel the Task.
+    #
+    # @param timeout [Numeric, nil] maximum seconds this caller will block
+    # @return [Object] the completed value
+    # @raise [Phronomy::TimeoutError] when the waiter-local timeout expires
+    # @raise [Exception] the error that settled the Task
+    # @api public
     def wait_result(timeout: nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
@@ -71,8 +95,9 @@ module Phronomy
       value
     end
 
-    # Compatibility wait that does not re-raise the task error.
+    # Compatibility wait that does not re-raise the Task error.
     # Returns self when settled, nil on timeout.
+    # @api private
     def join(limit = nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
@@ -96,8 +121,15 @@ module Phronomy
 
     # Registers an independent completion notification.
     #
+    # The callback execution thread is not guaranteed. It may be the caller that
+    # registers after settlement, an OffloadPool worker, or a framework control
+    # thread. Callbacks must therefore be thread-safe and should complete quickly.
     # A callback failure is logged and does not suppress delivery to other
     # completion callbacks or change the Task's already-settled result.
+    #
+    # @yield [value, error]
+    # @return [self]
+    # @api public
     def on_complete(&callback)
       raise ArgumentError, "on_complete requires a block" unless callback
 
@@ -113,15 +145,25 @@ module Phronomy
       self
     end
 
+    # Settles this Task successfully. Framework-owned settlement API.
+    # @api private
     def complete(value = nil)
       settle!(:completed, value: value)
     end
 
+    # Settles this Task with a failure. Framework-owned settlement API.
+    # @api private
     def fail(error)
       raise ArgumentError, "error is required" unless error
       settle!(:failed, error: error)
     end
 
+    # Settles this Task as cancelled. Framework-owned settlement API.
+    #
+    # This method does not propagate backwards into a CancellationToken that may
+    # have been used to create the Task. Tokens can be shared across operations;
+    # operation-wide cancellation is owned by the creating API.
+    # @api private
     def cancel!(error = Phronomy::CancellationError.new("Task cancelled"))
       changed = settle!(:cancelled, error: error)
       if changed
@@ -131,6 +173,8 @@ module Phronomy
       self
     end
 
+    # Creates a derived Task by transforming this Task's successful result.
+    # @api public
     def map(&block)
       raise ArgumentError, "map requires a block" unless block
 

data/lib/phronomy/invocation_context.rb

@@ -3,10 +3,9 @@
 module Phronomy
   # Carries all per-invocation context values through the call stack.
   #
-  # +InvocationContext+ is a plain value object (struct-like, frozen on
-  # creation) that replaces ad-hoc +Thread.current[...]+ propagation.
-  # Pass it explicitly wherever context needs to cross a method boundary
-  # or be handed to a child {Task} / {TaskGroup}.
+  # +InvocationContext+ is a plain struct-like value carrier that replaces
+  # ad-hoc +Thread.current[...]+ propagation.
+  # Pass it explicitly wherever context needs to cross a method boundary.
   #
   # @example Build a context for a new agent invocation
   #   ctx = Phronomy::InvocationContext.new(
@@ -14,40 +13,12 @@ module Phronomy
   #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30)
   #   )
   #   agent.invoke("Hello", invocation_context: ctx)
+  #
+  # @api public
   class InvocationContext
-    # @return [String, nil] conversation / workflow thread identifier
-    attr_reader :thread_id
-
-    # @return [String, nil] session identifier (e.g. Rails session id)
-    attr_reader :session_id
-
-    # @return [String, nil] end-user identifier for tracing / audit
-    attr_reader :user_id
-
-    # @return [CancellationToken, nil]
-    attr_reader :cancellation_token
-
-    # @return [Deadline, nil]
-    attr_reader :deadline
-
-    # @return [Object, nil] OpenTelemetry / tracing span
-    attr_reader :tracer_span
-
-    # @return [Integer, nil] max tokens the agent may consume this invocation
-    attr_reader :token_budget
-
-    # @return [#call, nil] invocation-specific Tool approval policy. The callable
-    #   receives Phronomy::Agent::ApprovalEvaluationRequest.
-    attr_reader :approval_policy
-
-    # @return [Object, nil] redaction policy applied to tool args / results
-    attr_reader :redaction_policy
-
-    # @return [String, nil] unique identifier for this task in the trace tree
-    attr_reader :task_id
-
-    # @return [String, nil] task_id of the parent span / task
-    attr_reader :parent_task_id
+    attr_reader :thread_id, :session_id, :user_id, :cancellation_token,
+      :deadline, :tracer_span, :token_budget, :approval_policy,
+      :redaction_policy, :task_id, :parent_task_id
 
     # @param thread_id [String, nil]
     # @param session_id [String, nil]
@@ -56,11 +27,11 @@ module Phronomy
     # @param deadline [Deadline, nil]
     # @param tracer_span [Object, nil]
     # @param token_budget [Integer, nil]
-    # @param approval_policy [#call, nil] invocation-specific Tool approval policy
+    # @param approval_policy [#call, nil]
     # @param redaction_policy [Object, nil]
     # @param task_id [String, nil]
     # @param parent_task_id [String, nil]
-    # @api private
+    # @api public
     def initialize(
       thread_id: nil,
       session_id: nil,
@@ -88,10 +59,6 @@ module Phronomy
     end
 
     # Returns a new +InvocationContext+ with the given attributes merged in.
-    # All other attributes are carried over unchanged.
-    #
-    # @param overrides [Hash] keyword arguments to override
-    # @return [InvocationContext]
     # @api private
     def merge(**overrides)
       InvocationContext.new(
@@ -110,21 +77,13 @@ module Phronomy
     end
 
     # Convenience: returns the cancellation token or a new never-cancelled token.
-    # @return [CancellationToken]
     # @api private
     def effective_cancellation_token
       @cancellation_token || Phronomy::Concurrency::CancellationToken.new
     end
 
     # Returns the cancellation token to use for an invocation, taking both the
-    # explicit +cancellation_token+ and the +deadline+ into account.
-    #
-    # - When +cancellation_token+ is set, it is returned unchanged.
-    # - When only +deadline+ is set, a new {CancellationToken} is created and
-    #   the deadline is attached to it via {Deadline#attach_to}.
-    # - When neither is set, returns +nil+.
-    #
-    # @return [CancellationToken, nil]
+    # explicit cancellation_token and deadline into account.
     # @api private
     def effective_timeout_token
       return @cancellation_token if @cancellation_token

data/lib/phronomy/llm_adapter/base.rb

@@ -2,56 +2,57 @@
 
 module Phronomy
   module LLMAdapter
-    # Abstract base class for LLM adapters.
+    # Beta extension SPI for LLM call adapters.
     #
-    # Subclasses must implement {#complete} and {#stream}. The adapter or the
+    # External adapters implement {#complete} and {#stream}. The adapter or the
     # underlying provider client owns transport timeout, retry, backoff, and
-    # rate-limit behavior. Phronomy supplies cooperative cancellation and
-    # isolates synchronous provider calls in {OffloadPool}.
+    # rate-limit behavior. Phronomy owns cooperative cancellation and isolates
+    # synchronous provider calls in {OffloadPool}.
     #
-    # The agent pipeline calls {#complete_async} / {#stream_async} which wrap
-    # those methods in an {OffloadPool} submission.
+    # The Agent pipeline calls the framework-owned {#complete_async} and
+    # {#stream_async} wrappers. Adapter implementers do not need to depend on
+    # EventLoop, FSMSession, OffloadPool, AgentInvocation, or ExecutionCoordinator.
+    #
+    # The current input to this SPI is the configured/materialized chat runtime
+    # object. Formalizing this SPI therefore does not imply a provider-neutral
+    # replacement for RubyLLMMaterializer.
+    #
+    # @api public
     class Base
       # Performs a blocking (non-streaming) LLM completion.
-      # Implementors must call +chat.ask(message)+ (or equivalent) and
-      # return the response object.
       #
-      # @param chat    [Object] the configured chat session object
-      # @param message [String] the user message
+      # Implementors call the configured chat/runtime client and return its
+      # response object. Transport/retry policy remains adapter-owned.
+      #
+      # @param chat    [Object] the configured/materialized chat runtime object
+      # @param message [String, nil] user message, or nil to continue without adding a new user turn
       # @param config  [Hash] invocation config (e.g. +:cancellation_token+)
       # @return [Object] LLM response object
       # @raise [NotImplementedError]
-      # @api private
+      # @api public
       def complete(chat, message, config: {})
         raise NotImplementedError, "#{self.class}#complete is not implemented"
       end
 
       # Performs a blocking streaming LLM completion.
-      # Implementors must call +chat.ask(message) { |chunk| block.call(chunk) }+
-      # (or equivalent) and return the response object.
       #
-      # @param chat    [Object] the configured chat session object
-      # @param message [String] the user message
+      # @param chat    [Object] the configured/materialized chat runtime object
+      # @param message [String, nil] user message, or nil to continue without adding a new user turn
       # @param config  [Hash] invocation config
       # @yield [chunk] streaming chunk from the LLM
       # @return [Object] LLM response object
       # @raise [NotImplementedError]
-      # @api private
+      # @api public
       def stream(chat, message, config: {}, &block)
         raise NotImplementedError, "#{self.class}#stream is not implemented"
       end
 
-      # Submits a non-streaming LLM call to {OffloadPool} and returns
-      # an {OffloadPool::PendingOperation}.
+      # Submits a non-streaming LLM call to {OffloadPool}.
       #
       # Transport timeout and retry remain the responsibility of the adapter or
       # provider client; Phronomy does not attach an additional operation timeout.
       #
-      # @param chat    [Object] configured chat session
-      # @param message [String] user message
-      # @param config  [Hash] invocation config
-      # @param pool    [OffloadPool] pool to submit to
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task] caller-facing completion handle
       # @api private
       def complete_async(chat, message, config: {}, pool: default_pool)
         token = config[:cancellation_token]
@@ -60,18 +61,14 @@ module Phronomy
         end
       end
 
-      # Submits a streaming LLM call to {OffloadPool} and returns
-      # an {OffloadPool::PendingOperation}.
-      #
-      # The block is invoked on an OffloadPool worker thread. Agent code must
-      # pass only a lightweight internal sink that posts a value to EventLoop;
-      # Application callbacks must never be passed directly to this method.
+      # Submits a streaming LLM call to {OffloadPool}.
       #
-      # Transport timeout and retry remain the responsibility of the adapter or
-      # provider client; Phronomy does not attach an additional operation timeout.
+      # The block is invoked on an OffloadPool worker thread. Agent code must pass
+      # only a lightweight internal sink that posts a value to EventLoop;
+      # application callbacks must never be passed directly to this method.
       #
       # @yield [chunk] streaming chunk on the worker thread
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task] caller-facing completion handle
       # @api private
       def stream_async(chat, message, config: {}, pool: default_pool, &block)
         raise ArgumentError, "stream_async requires a block" unless block

data/lib/phronomy/llm_adapter/ruby_llm.rb

@@ -2,42 +2,43 @@
 
 module Phronomy
   module LLMAdapter
-    # LLM adapter that delegates to the RubyLLM blocking client.
+    # Default LLMAdapter SPI implementation backed by RubyLLM.
     #
-    # This is the default adapter used by Phronomy agents. It wraps
-    # +chat.ask+ (and its streaming variant) so that the synchronous provider
-    # call runs inside {OffloadPool} rather than on the EventLoop thread.
+    # The synchronous +chat.ask+ / +chat.complete+ calls are invoked through the
+    # framework-owned async bridge in {LLMAdapter::Base}, so adapter consumers do
+    # not need to manage OffloadPool themselves.
     #
     # @example Explicitly configuring this adapter
     #   Phronomy.configure do |c|
     #     c.llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
     #   end
+    #
+    # @api public
     class RubyLLM < Base
       # Delegates to +chat.ask(message)+ or +chat.complete+ when message is nil.
       #
       # Passing +nil+ for +message+ is used by the ReAct loop for continuation
       # turns where the user message has already been added to the chat history
-      # (e.g. after a tool result) and the LLM should continue without a new
-      # user turn.
+      # (for example after a Tool result).
       #
       # @param chat    [Object]      RubyLLM chat session
       # @param message [String, nil] user message, or nil to continue the chat
-      # @param config  [Hash]        invocation config (not used directly by this impl)
+      # @param config  [Hash]        invocation config (not used directly here)
       # @return [Object] RubyLLM response
-      # @api private
+      # @api public
       def complete(chat, message, config: {})
         message ? chat.ask(message) : chat.complete
       end
 
-      # Delegates to +chat.ask(message) { |chunk| block.call(chunk) }+ or
-      # +chat.complete(&block)+ when message is nil.
+      # Delegates to +chat.ask(message) { |chunk| ... }+ or +chat.complete(&block)+
+      # when message is nil.
       #
       # @param chat    [Object]      RubyLLM chat session
       # @param message [String, nil] user message, or nil to continue the chat
       # @param config  [Hash]        invocation config
-      # @yield [chunk] streaming chunk forwarded from +chat.ask+ / +chat.complete+
+      # @yield [chunk] streaming chunk forwarded from RubyLLM
       # @return [Object] RubyLLM response
-      # @api private
+      # @api public
       def stream(chat, message, config: {}, &block)
         message ? chat.ask(message, &block) : chat.complete(&block)
       end

data/lib/phronomy/llm_adapter.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Namespace for LLM adapter implementations.
+  # Namespace for LLM call adapters.
   #
-  # An LLMAdapter decouples Phronomy's agent pipeline from direct
-  # dependency on the RubyLLM blocking client. All LLM calls in
-  # {Agent::Base} are routed through the adapter so that:
+  # The public extension boundary is {LLMAdapter::Base#complete} and
+  # {LLMAdapter::Base#stream}. Those methods receive Phronomy's currently
+  # materialized chat/runtime object and perform the provider call. Phronomy owns
+  # the async/offload bridge around that synchronous contract.
   #
-  # - Synchronous provider work can be submitted to {OffloadPool} for bounded
-  #   off-EventLoop execution.
-  # - Alternative LLM clients can be swapped in without changing agent code.
+  # This SPI does not by itself make the complete input-materialization pipeline
+  # provider-neutral: the current Agent pipeline still materializes the canonical
+  # LLM input through RubyLLM-specific runtime objects before invoking the adapter.
   #
   # @example Configuring a custom adapter
   #   Phronomy.configure do |c|
   #     c.llm_adapter = MyCustomAdapter.new
   #   end
+  #
+  # @api public
   module LLMAdapter
   end
 end

data/lib/phronomy/output_parser/base.rb

@@ -14,7 +14,11 @@ module Phronomy
         parse(input.is_a?(String) ? input : input.to_s)
       end
 
-      # Implement in subclasses.
+      # Extension point implemented by custom parsers.
+      #
+      # @param text [String]
+      # @return [Object]
+      # @api public
       def parse(text)
         raise NotImplementedError, "#{self.class}#parse is not implemented"
       end

data/lib/phronomy/persistence.rb

@@ -5,9 +5,53 @@ module Phronomy
     class ConflictError < Phronomy::Error; end
     class NotFoundError < Phronomy::Error; end
     class UnsupportedBackendError < Phronomy::Error; end
+    class SerializationError < Phronomy::Error; end
 
-    attr_reader :contents, :agents, :journals, :executions, :workflow_states
+    REQUIRED_CAPABILITIES = {
+      atomic_all: true,
+      atomic_admission: true,
+      optimistic_revision: true
+    }.freeze
 
+    # Durable repository accessors supplied by a Persistence backend.
+    #
+    # The repository objects are part of the Backend SPI. They may be private
+    # implementation classes owned by the backend; they do not need to inherit
+    # from Phronomy repository base classes.
+    #
+    # @return [Object] content-addressed immutable content repository
+    # @api public
+    attr_reader :contents
+
+    # @return [Object] AgentRoot repository
+    # @api public
+    attr_reader :agents
+
+    # @return [Object] append-only Agent Journal repository
+    # @api public
+    attr_reader :journals
+
+    # @return [Object] AgentExecution repository
+    # @api public
+    attr_reader :executions
+
+    # @return [Object] durable Workflow snapshot repository
+    # @api public
+    attr_reader :workflow_states
+
+    # Initializes a Persistence backend with its durable repositories.
+    #
+    # Subclasses normally construct backend-specific repository objects and then
+    # call +super+. The backend must advertise every capability in
+    # {REQUIRED_CAPABILITIES}; construction fails fast otherwise.
+    #
+    # @param contents [Object]
+    # @param agents [Object]
+    # @param journals [Object]
+    # @param executions [Object]
+    # @param workflow_states [Object]
+    # @raise [UnsupportedBackendError] when a required capability is missing
+    # @api public
     def initialize(contents:, agents:, journals:, executions:, workflow_states:)
       @contents = contents
       @agents = agents
@@ -17,18 +61,67 @@ module Phronomy
       validate_capabilities!
     end
 
+    # Declares storage semantics provided by this backend.
+    #
+    # Required meanings:
+    # - +atomic_all+: all durable repositories can participate in one atomic
+    #   transaction domain.
+    # - +atomic_admission+: Agent execution admission is atomic; at most one
+    #   active/suspended execution may be admitted for one Agent. This does not
+    #   mean cross-process Workflow admission or distributed locking.
+    # - +optimistic_revision+: Agent, Execution, Workflow revision checks and
+    #   Journal position checks provide compare-and-swap conflict detection.
+    #
+    # @return [Hash{Symbol => Boolean}]
+    # @api public
     def capabilities
-      {atomic_all: false, atomic_admission: false}.freeze
+      {
+        atomic_all: false,
+        atomic_admission: false,
+        optimistic_revision: false
+      }.freeze
     end
 
+    # Executes one atomic durable transaction.
+    #
+    # The object yielded to the block is a transaction-scoped Persistence view.
+    # It must respond to +contents+, +agents+, +journals+, +executions+,
+    # +workflow_states+, and +assert_agent_watermark!+. It may be +self+, but
+    # backends are free to yield a separate transaction view backed by a checked
+    # out connection/session.
+    #
+    # If the block raises, mutations made through the transaction view must not
+    # be committed. Storage failures whose commit outcome is fundamentally
+    # unknown remain backend/database failures; Phronomy does not claim
+    # exactly-once semantics for such failures.
+    #
+    # @yieldparam transaction_view [Object]
+    # @return [Object] the block result
+    # @raise [UnsupportedBackendError] when atomic transactions are unavailable
+    # @api public
     def transaction
       raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
     end
 
     # Verifies that a live Agent still owns the durable base it hydrated.
-    # Backends should implement this as a revision/position precondition check,
-    # not as a state reload returned to the caller.
-    # @api private
+    #
+    # This is a Backend SPI operation invoked by Phronomy at durable barriers.
+    # Ordinary application code should not call it directly. The backend must
+    # compare the stored Agent revision and current Journal position against the
+    # supplied watermark in the same storage consistency view used by subsequent
+    # writes in the surrounding transaction.
+    #
+    # The method is a precondition check only. It must not reload or return
+    # replacement mutable Agent state; the live Agent remains the logical owner.
+    #
+    # @param agent_id [String]
+    # @param agent_revision [Integer]
+    # @param journal_position [Integer]
+    # @return [true]
+    # @raise [NotFoundError] when the Agent does not exist
+    # @raise [ConflictError] when either durable watermark component differs
+    # @raise [UnsupportedBackendError] when the backend does not implement the check
+    # @api public
     def assert_agent_watermark!(agent_id:, agent_revision:, journal_position:)
       raise UnsupportedBackendError,
         "#{self.class} does not provide Agent durable-watermark checks"
@@ -37,8 +130,9 @@ module Phronomy
     private
 
     def validate_capabilities!
-      required = {atomic_all: true, atomic_admission: true}
-      missing = required.reject { |key, value| capabilities[key] == value }
+      missing = REQUIRED_CAPABILITIES.reject do |key, value|
+        capabilities[key] == value
+      end
       return if missing.empty?
 
       raise UnsupportedBackendError,

data/lib/phronomy/testing/persistence_contract/a_content_store.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "a persistence content store" do
+  let(:content_store) { persistence.contents }
+
+  it "returns the same content_id for the same bytes" do
+    first = content_store.put("same".b, canonicalization_version: 1)
+    second = content_store.put("same".b, canonicalization_version: 1)
+
+    expect(second).to eq(first)
+  end
+
+  it "round-trips binary bytes" do
+    bytes = "\x00\xFFpayload".b
+    content_id = content_store.put(bytes, canonicalization_version: 1)
+
+    expect(content_store.fetch(content_id)).to eq(bytes)
+    expect(content_store.exist?(content_id)).to be(true)
+  end
+
+  it "raises NotFoundError for a missing content_id" do
+    expect do
+      content_store.fetch("sha256:#{"0" * 64}")
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "isolates durable bytes from mutation of fetched values" do
+    content_id = content_store.put("immutable".b, canonicalization_version: 1)
+    fetched = content_store.fetch(content_id)
+    fetched << "-caller-change"
+
+    expect(content_store.fetch(content_id)).to eq("immutable".b)
+  end
+
+  it "supports UTF-8 text helpers" do
+    content_id = content_store.put_text("Grüße")
+
+    expect(content_store.fetch_text(content_id)).to eq("Grüße")
+  end
+
+  it "supports canonical JSON helpers" do
+    value = {
+      "z" => [1, true, nil],
+      "a" => {"message" => "hello"}
+    }
+    content_id = content_store.put_json(value)
+
+    expect(content_store.fetch_json(content_id)).to eq(value)
+  end
+end