phronomy 0.27.0 → 0.28.0

data/lib/phronomy/storage/async/async_client.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Storage
+    # Asynchronous execution of a synchronous raw storage backend.
+    #
+    # A transaction opens, runs and closes on one worker. Return values rather
+    # than transaction views: a bound view is closed when the block finishes.
+    # Timeout includes queue wait. Timeout/cancellation settles TaskResult but
+    # does not interrupt running I/O or guarantee rollback of a started write.
+    # Construction starts no Runtime; the default pool is resolved per operation.
+    # An explicitly injected pool remains owned by its caller.
+    #
+    # @api public
+    class AsyncClient
+      # @param backend [Storage::Backend] synchronous raw SPI 2 backend
+      # @param pool [Concurrency::OffloadPool, nil] optional execution pool
+      # @api public
+      def initialize(backend:, pool: nil)
+        Backend.validate_capabilities!(backend)
+        @backend = backend
+        @pool = pool
+      end
+
+      # Executes the entire transaction on one worker without waiting for queue
+      # capacity. Explicit nested backend transactions retain savepoint semantics.
+      #
+      # @param cancellation_token [Concurrency::CancellationToken, nil]
+      # @param timeout [Numeric, nil] operation-wide submit timeout
+      # @yieldparam view [Storage::View] view valid only within this transaction
+      # @return [Phronomy::TaskResult] the pool's original completion handle
+      # @api public
+      def transaction_async(cancellation_token: nil, timeout: nil, &operation)
+        raise ArgumentError, "transaction_async requires a block" unless operation
+
+        Phronomy::Execution.submit(pool: default_pool, timeout: timeout, cancellation_token: cancellation_token, on_full: :raise) do
+          @backend.transaction(&operation)
+        end
+      end
+
+      # Submit an existing domain-owned synchronous storage unit unchanged.
+      # It may already open transactions or perform reads/reconciliation. Do not
+      # add a transaction, timeout or cancellation condition around that unit.
+      # The owner supplies its current runtime's pool and applies the result.
+      #
+      # @api private
+      def self.submit(pool:, &operation)
+        raise ArgumentError, "storage submit requires a block" unless operation
+
+        Phronomy::Execution.submit(pool: pool, on_full: :raise, &operation)
+      end
+
+      private
+
+      def default_pool
+        @pool
+      end
+    end
+  end
+end

data/lib/phronomy/storage/backend.rb

@@ -30,8 +30,9 @@ module Phronomy
       def self.validate_capabilities!(backend)
         capabilities = backend.respond_to?(:capabilities) ? backend.capabilities : {}
         missing = REQUIRED_CAPABILITIES.reject { |key, value| capabilities.is_a?(Hash) && capabilities[key] == value }
-        unless missing.empty? && backend.respond_to?(:view) && backend.respond_to?(:transaction)
-          raise UnsupportedBackendError, "Persistence requires Storage SPI 2: #{missing.keys.join(", ")}"
+        missing_methods = %i[view transaction transaction_open?].reject { |name| backend.respond_to?(name) }
+        unless missing.empty? && missing_methods.empty?
+          raise UnsupportedBackendError, "Persistence requires Storage SPI 2: #{(missing.keys + missing_methods).join(", ")}"
         end
       end
 
@@ -40,6 +41,11 @@ module Phronomy
         REQUIRED_CAPABILITIES.transform_values { |value| (value == true) ? false : value }.freeze
       end
 
+      # Whether this synchronous context is already inside a backend transaction.
+      # Lets higher-level scopes reject claiming ownership of somebody else's commit.
+      # @api public
+      def transaction_open? = !current_view.nil?
+
       # All declared resources participate in one atomic transaction domain.
       # Record and stream revisions provide compare-and-swap conflict detection.
       # This does not

data/lib/phronomy/testing/eval/metrics.rb

@@ -19,7 +19,7 @@ module Phronomy
         end
 
         def total_usage
-          @results.map(&:usage).compact.reduce(Phronomy::TokenUsage.zero, :+)
+          @results.map(&:usage).compact.reduce(Phronomy::LLMAdapter::TokenUsage.zero, :+)
         end
 
         def average_latency_ms

data/lib/phronomy/testing/eval/scorer/llm_judge.rb

@@ -5,6 +5,19 @@ module Phronomy
     module Eval
       module Scorer
         class LlmJudge < Base
+          CLIENT_FACTORIES = {}
+          private_constant :CLIENT_FACTORIES
+
+          # One-time boot binding, not an application extension registry. The
+          # factory runs for each score, after its Request has been prepared.
+          # @api private
+          def self.install_client_factory(factory)
+            raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
+
+            CLIENT_FACTORIES.replace(client: factory).freeze
+            nil
+          end
+
           DEFAULT_PROMPT = <<~PROMPT
             You are an impartial judge evaluating the quality of an AI assistant response.
             Rate the response on a scale from 0.0 (completely wrong or unhelpful) to 1.0 (perfect).
@@ -32,9 +45,12 @@ module Phronomy
               expected: expected.to_s,
               actual: actual.to_s
             )
-            response = Phronomy::Runtime.instance.offload.submit do
-              RubyLLM.chat(model: @model, provider: @provider, assume_model_exists: @assume_model_exists).ask(prompt)
-            end.wait_result
+            request = Phronomy::LLMAdapter::Request.new(
+              model_config: {"model" => @model, "provider" => @provider&.to_s,
+                             "assume_model_exists" => @assume_model_exists}.compact,
+              message: prompt
+            )
+            response = CLIENT_FACTORIES.fetch(:client).call.complete_async(request).wait_result
             response.content.to_s.strip.scan(/-?\d+\.?\d*/).first.to_f.clamp(0.0, 1.0)
           rescue => error
             raise if @raise_on_error

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 RSpec.shared_examples "a persistence content store" do
-  let(:content_store) { persistence.contents }
+  let(:content_store) { stores.agent.contents }
 
   it "returns the same content_id for the same bytes" do
     first = content_store.put("same".b, canonicalization_version: 1)
@@ -21,7 +21,7 @@ RSpec.shared_examples "a persistence content store" do
   it "raises NotFoundError for a missing content_id" do
     expect do
       content_store.fetch("sha256:#{"0" * 64}")
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 
   it "isolates durable bytes from mutation of fetched values" do

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

@@ -3,7 +3,7 @@
 require "securerandom"
 
 RSpec.shared_examples "a Journal repository" do
-  let(:journal_repository) { persistence.journals }
+  let(:journal_repository) { stores.agent.journals }
   let(:journal_agent_root) do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "journal-agent-#{SecureRandom.uuid}",
@@ -25,7 +25,7 @@ RSpec.shared_examples "a Journal repository" do
   end
 
   before do
-    persistence.agents.create(journal_agent_root)
+    stores.agent.agents.create(journal_agent_root)
   end
 
   it "appends records at the expected position and assigns durable sequences" do
@@ -51,7 +51,7 @@ RSpec.shared_examples "a Journal repository" do
         expected_position: 1,
         records: [record]
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects a duplicate record_id already present in the Journal" do
@@ -76,7 +76,7 @@ RSpec.shared_examples "a Journal repository" do
         expected_position: 1,
         records: [duplicate]
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects duplicate record_ids within one append" do
@@ -94,7 +94,7 @@ RSpec.shared_examples "a Journal repository" do
         expected_position: 0,
         records: records
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects records belonging to another Agent" do
@@ -106,7 +106,7 @@ RSpec.shared_examples "a Journal repository" do
         expected_position: 0,
         records: [record]
       )
-    end.to raise_error(Phronomy::Storage::SerializationError)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 
   it "reads records in sequence order and supports after/limit" do

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

@@ -27,26 +27,25 @@ RSpec.shared_examples "a Persistence backend" do
 
   it "advertises every required capability" do
     Phronomy::Storage::Backend::REQUIRED_CAPABILITIES.each do |name, required_value|
-      expect(persistence.backend.capabilities[name]).to eq(required_value)
+      expect(stores.coordinator.backend.capabilities[name]).to eq(required_value)
     end
   end
 
-  it "yields a transaction view that exposes the complete durable SPI" do
-    persistence.transaction do |tx|
-      expect(tx).to respond_to(
-        :contents,
-        :agents,
-        :journals,
-        :executions,
-        :workflow_states,
-        :handoff_states, :teams, :team_executions,
-        :assert_agent_watermark!
-      )
+  it "binds each domain to its own record protocol in one common scope" do
+    stores.coordinator.atomic do |scope|
+      stores.agent.participate(scope) do |records|
+        expect(records).to respond_to(:contents, :agents, :journals, :executions, :retentions, :cancellations, :assert_agent_watermark!)
+        expect(records).not_to respond_to(:teams, :team_executions, :workflow_states)
+      end
+      stores.multi_agent.participate(scope) do |records|
+        expect(records).to respond_to(:contents, :teams, :team_executions, :handoff_states)
+        expect(records).not_to respond_to(:agents, :executions, :workflow_states)
+      end
     end
   end
 
   it "returns the transaction block result" do
-    expect(persistence.transaction { |_tx| :contract_result }).to eq(:contract_result)
+    expect(stores.agent.transaction { |_tx| :contract_result }).to eq(:contract_result)
   end
 
   it "commits changes across durable repositories as one transaction" do
@@ -55,7 +54,7 @@ RSpec.shared_examples "a Persistence backend" do
     workflow_id = "workflow-#{SecureRandom.uuid}"
     content_id = nil
 
-    persistence.transaction do |tx|
+    stores.agent.transaction do |tx, scope|
       content_id = tx.contents.put_text("committed")
       tx.agents.create(root)
       appended = tx.journals.append(
@@ -73,11 +72,13 @@ RSpec.shared_examples "a Persistence backend" do
         ]
       )
       tx.executions.create_active(execution)
-      tx.workflow_states.save(
-        workflow_id,
-        expected_revision: nil,
-        snapshot: {fields: {value: "committed"}, phase: "pause"}
-      )
+      scope.participate(persistence: stores.coordinator, adapter: Phronomy::Workflow::Persistence::StateRepository) do |workflow|
+        workflow.save(
+          workflow_id,
+          expected_revision: nil,
+          snapshot: {fields: {value: "committed"}, phase: "pause"}
+        )
+      end
 
       updated_root = root.with(
         agent_revision: 1,
@@ -87,12 +88,12 @@ RSpec.shared_examples "a Persistence backend" do
       tx.agents.save(root.agent_id, expected_revision: 0, root: updated_root)
     end
 
-    expect(persistence.contents.exist?(content_id)).to be(true)
-    expect(persistence.agents.load(root.agent_id).agent_revision).to eq(1)
-    expect(persistence.journals.head(root.agent_id)).to eq(1)
-    expect(persistence.executions.load(execution.execution_id).execution_id)
+    expect(stores.agent.contents.exist?(content_id)).to be(true)
+    expect(stores.agent.agents.load(root.agent_id).agent_revision).to eq(1)
+    expect(stores.agent.journals.head(root.agent_id)).to eq(1)
+    expect(stores.agent.executions.load(execution.execution_id).execution_id)
       .to eq(execution.execution_id)
-    expect(persistence.workflow_states.load(workflow_id)).not_to be_nil
+    expect(stores.workflow.load(workflow_id)).not_to be_nil
   end
 
   it "rolls back all durable repositories when the transaction block raises" do
@@ -102,7 +103,7 @@ RSpec.shared_examples "a Persistence backend" do
     content_id = nil
 
     expect do
-      persistence.transaction do |tx|
+      stores.agent.transaction do |tx, scope|
         content_id = tx.contents.put_text("temporary-#{SecureRandom.uuid}")
         tx.agents.create(root)
         tx.journals.append(
@@ -120,32 +121,34 @@ RSpec.shared_examples "a Persistence backend" do
           ]
         )
         tx.executions.create_active(execution)
-        tx.workflow_states.save(
-          workflow_id,
-          expected_revision: nil,
-          snapshot: {fields: {value: "temporary"}, phase: "pause"}
-        )
+        scope.participate(persistence: stores.coordinator, adapter: Phronomy::Workflow::Persistence::StateRepository) do |workflow|
+          workflow.save(
+            workflow_id,
+            expected_revision: nil,
+            snapshot: {fields: {value: "temporary"}, phase: "pause"}
+          )
+        end
         raise "rollback-contract"
       end
     end.to raise_error("rollback-contract")
 
-    expect(persistence.contents.exist?(content_id)).to be(false)
+    expect(stores.agent.contents.exist?(content_id)).to be(false)
     expect do
-      persistence.agents.load(root.agent_id)
-    end.to raise_error(Phronomy::Storage::NotFoundError)
-    expect(persistence.journals.head(root.agent_id)).to eq(0)
+      stores.agent.agents.load(root.agent_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect(stores.agent.journals.head(root.agent_id)).to eq(0)
     expect do
-      persistence.executions.load(execution.execution_id)
-    end.to raise_error(Phronomy::Storage::NotFoundError)
-    expect(persistence.workflow_states.load(workflow_id)).to be_nil
+      stores.agent.executions.load(execution.execution_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect(stores.workflow.load(workflow_id)).to be_nil
   end
 
   it "accepts the current Agent revision and Journal position watermark" do
     root = backend_agent_root
-    persistence.agents.create(root)
+    stores.agent.agents.create(root)
 
     expect(
-      persistence.assert_agent_watermark!(
+      stores.agent.assert_agent_watermark!(
         agent_id: root.agent_id,
         agent_revision: root.agent_revision,
         journal_position: root.journal_position
@@ -155,23 +158,23 @@ RSpec.shared_examples "a Persistence backend" do
 
   it "raises ConflictError when the durable Agent revision has advanced" do
     root = backend_agent_root
-    persistence.agents.create(root)
+    stores.agent.agents.create(root)
     advanced = root.with(agent_revision: 1)
-    persistence.agents.save(root.agent_id, expected_revision: 0, root: advanced)
+    stores.agent.agents.save(root.agent_id, expected_revision: 0, root: advanced)
 
     expect do
-      persistence.assert_agent_watermark!(
+      stores.agent.assert_agent_watermark!(
         agent_id: root.agent_id,
         agent_revision: 0,
         journal_position: 0
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "raises ConflictError when the durable Journal position has advanced" do
     root = backend_agent_root
-    persistence.agents.create(root)
-    persistence.journals.append(
+    stores.agent.agents.create(root)
+    stores.agent.journals.append(
       root.agent_id,
       expected_position: 0,
       records: [
@@ -186,23 +189,23 @@ RSpec.shared_examples "a Persistence backend" do
     )
 
     expect do
-      persistence.assert_agent_watermark!(
+      stores.agent.assert_agent_watermark!(
         agent_id: root.agent_id,
         agent_revision: 0,
         journal_position: 0
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rolls back earlier writes when a watermark precondition fails" do
     root = backend_agent_root
-    persistence.agents.create(root)
+    stores.agent.agents.create(root)
     advanced = root.with(agent_revision: 1)
-    persistence.agents.save(root.agent_id, expected_revision: 0, root: advanced)
+    stores.agent.agents.save(root.agent_id, expected_revision: 0, root: advanced)
     temporary_content_id = nil
 
     expect do
-      persistence.transaction do |tx|
+      stores.agent.transaction do |tx, scope|
         temporary_content_id = tx.contents.put_text(
           "watermark-rollback-#{SecureRandom.uuid}"
         )
@@ -212,8 +215,8 @@ RSpec.shared_examples "a Persistence backend" do
           journal_position: 0
         )
       end
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
 
-    expect(persistence.contents.exist?(temporary_content_id)).to be(false)
+    expect(stores.agent.contents.exist?(temporary_content_id)).to be(false)
   end
 end

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

@@ -3,7 +3,7 @@
 require "securerandom"
 
 RSpec.shared_examples "a workflow state repository" do
-  let(:repository) { persistence.workflow_states }
+  let(:repository) { stores.workflow }
 
   def workflow_contract_value(hash, key)
     hash.key?(key) ? hash[key] : hash[key.to_s]
@@ -54,7 +54,7 @@ RSpec.shared_examples "a workflow state repository" do
         expected_revision: nil,
         snapshot: {fields: {value: 2}, phase: "__end__"}
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "returns a snapshot representation accepted by WorkflowRunner" do
@@ -111,7 +111,7 @@ RSpec.shared_examples "a workflow state repository" do
 
     expect do
       repository.delete(workflow_instance_id, expected_revision: 99)
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
 
     repository.delete(workflow_instance_id, expected_revision: 1)
     expect(repository.load(workflow_instance_id)).to be_nil

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

@@ -3,7 +3,7 @@
 require "securerandom"
 
 RSpec.shared_examples "an Agent repository" do
-  let(:agent_repository) { persistence.agents }
+  let(:agent_repository) { stores.agent.agents }
   let(:agent_root) do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "contract-agent-#{SecureRandom.uuid}",
@@ -22,13 +22,13 @@ RSpec.shared_examples "an Agent repository" do
 
     expect do
       agent_repository.create(agent_root)
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "raises NotFoundError for a missing Agent" do
     expect do
       agent_repository.load("missing-#{SecureRandom.uuid}")
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 
   it "saves only at the expected revision" do
@@ -54,7 +54,7 @@ RSpec.shared_examples "an Agent repository" do
 
     expect do
       agent_repository.save(agent_root.agent_id, expected_revision: 0, root: stale)
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects an Agent identity mismatch" do
@@ -71,7 +71,7 @@ RSpec.shared_examples "an Agent repository" do
         expected_revision: 0,
         root: other
       )
-    end.to raise_error(Phronomy::Storage::SerializationError)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 
   it "requires revision to advance exactly once" do
@@ -84,7 +84,7 @@ RSpec.shared_examples "an Agent repository" do
         expected_revision: 0,
         root: skipped
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "deletes idempotently" do
@@ -94,6 +94,6 @@ RSpec.shared_examples "an Agent repository" do
 
     expect do
       agent_repository.load(agent_root.agent_id)
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 end

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

@@ -3,7 +3,7 @@
 require "securerandom"
 
 RSpec.shared_examples "an Execution repository" do
-  let(:execution_repository) { persistence.executions }
+  let(:execution_repository) { stores.agent.executions }
   let(:execution_agent_root) do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "execution-agent-#{SecureRandom.uuid}",
@@ -27,7 +27,7 @@ RSpec.shared_examples "an Execution repository" do
   end
 
   before do
-    persistence.agents.create(execution_agent_root)
+    stores.agent.agents.create(execution_agent_root)
   end
 
   it "creates and loads an active execution" do
@@ -40,7 +40,7 @@ RSpec.shared_examples "an Execution repository" do
   it "raises NotFoundError for a missing execution" do
     expect do
       execution_repository.load("missing-#{SecureRandom.uuid}")
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 
   it "rejects a duplicate execution_id" do
@@ -49,7 +49,7 @@ RSpec.shared_examples "an Execution repository" do
 
     expect do
       execution_repository.create_active(execution)
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "admits at most one active or suspended execution for one Agent" do
@@ -68,7 +68,7 @@ RSpec.shared_examples "an Execution repository" do
       agent_definition_id: "contract-agent",
       agent_definition_version: 1
     )
-    persistence.agents.create(other_root)
+    stores.agent.agents.create(other_root)
 
     expect do
       execution_repository.create_active(build_contract_execution(execution_agent_root))
@@ -107,7 +107,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: updated
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects an execution identity mismatch" do
@@ -118,7 +118,7 @@ RSpec.shared_examples "an Execution repository" do
       agent_definition_id: "contract-agent",
       agent_definition_version: 1
     )
-    persistence.agents.create(other_root)
+    stores.agent.agents.create(other_root)
     other = build_contract_execution(other_root).with(
       execution_revision: 1,
       status: :active,
@@ -131,7 +131,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: other
       )
-    end.to raise_error(Phronomy::Storage::SerializationError)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 
   it "requires execution revision to advance exactly once" do
@@ -149,7 +149,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: skipped
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "lists active executions for one Agent" do
@@ -179,7 +179,7 @@ RSpec.shared_examples "an Execution repository" do
 
     expect do
       execution_repository.load(execution.execution_id)
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 
   it "deletes all executions for one Agent without deleting other Agents' executions" do
@@ -188,7 +188,7 @@ RSpec.shared_examples "an Execution repository" do
       agent_definition_id: "contract-agent",
       agent_definition_version: 1
     )
-    persistence.agents.create(other_root)
+    stores.agent.agents.create(other_root)
     own = build_contract_execution(execution_agent_root)
     other = build_contract_execution(other_root)
     execution_repository.create_active(own)