phronomy 0.18.0 → 0.20.0

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

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "an Execution repository" do
+  let(:execution_repository) { persistence.executions }
+  let(:execution_agent_root) do
+    Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+  end
+
+  def build_contract_execution(root)
+    input_record = Phronomy::Agent::JournalRecord.new(
+      agent_id: root.agent_id,
+      kind: :input_received,
+      channel: :external,
+      role: :user,
+      context_candidate: false
+    )
+    Phronomy::Agent::AgentExecution.start(
+      agent_root: root,
+      input_record: input_record
+    )
+  end
+
+  before do
+    persistence.agents.create(execution_agent_root)
+  end
+
+  it "creates and loads an active execution" do
+    execution = build_contract_execution(execution_agent_root)
+
+    expect(execution_repository.create_active(execution).to_h).to eq(execution.to_h)
+    expect(execution_repository.load(execution.execution_id).to_h).to eq(execution.to_h)
+  end
+
+  it "raises NotFoundError for a missing execution" do
+    expect do
+      execution_repository.load("missing-#{SecureRandom.uuid}")
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "rejects a duplicate execution_id" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+
+    expect do
+      execution_repository.create_active(execution)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "admits at most one active or suspended execution for one Agent" do
+    first = build_contract_execution(execution_agent_root)
+    second = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(first)
+
+    expect do
+      execution_repository.create_active(second)
+    end.to raise_error(Phronomy::AgentBusyError)
+  end
+
+  it "allows different Agents to have active executions" do
+    other_root = Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+    persistence.agents.create(other_root)
+
+    expect do
+      execution_repository.create_active(build_contract_execution(execution_agent_root))
+      execution_repository.create_active(build_contract_execution(other_root))
+    end.not_to raise_error
+  end
+
+  it "saves only at the expected execution revision" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    updated = execution.with(status: :active, phase: :calling_llm)
+
+    expect(
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: updated
+      ).to_h
+    ).to eq(updated.to_h)
+    expect(execution_repository.load(execution.execution_id).execution_revision).to eq(1)
+  end
+
+  it "rejects a stale execution revision" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    updated = execution.with(status: :active, phase: :calling_llm)
+    execution_repository.save(
+      execution.execution_id,
+      expected_revision: 0,
+      execution: updated
+    )
+
+    expect do
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: updated
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects an execution identity mismatch" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    other_root = Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+    persistence.agents.create(other_root)
+    other = build_contract_execution(other_root).with(
+      execution_revision: 1,
+      status: :active,
+      phase: :calling_llm
+    )
+
+    expect do
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: other
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "requires execution revision to advance exactly once" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    skipped = execution.with(
+      execution_revision: 2,
+      status: :active,
+      phase: :calling_llm
+    )
+
+    expect do
+      execution_repository.save(
+        execution.execution_id,
+        expected_revision: 0,
+        execution: skipped
+      )
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "lists active executions for one Agent" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+
+    expect(execution_repository.list_active(execution_agent_root.agent_id).map(&:execution_id))
+      .to eq([execution.execution_id])
+  end
+
+  it "asserts idle state and rejects active Agents" do
+    expect do
+      execution_repository.assert_idle!(execution_agent_root.agent_id)
+    end.not_to raise_error
+
+    execution_repository.create_active(build_contract_execution(execution_agent_root))
+
+    expect do
+      execution_repository.assert_idle!(execution_agent_root.agent_id)
+    end.to raise_error(Phronomy::AgentBusyError)
+  end
+
+  it "deletes one execution" do
+    execution = build_contract_execution(execution_agent_root)
+    execution_repository.create_active(execution)
+    execution_repository.delete(execution.execution_id)
+
+    expect do
+      execution_repository.load(execution.execution_id)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+
+  it "deletes all executions for one Agent without deleting other Agents' executions" do
+    other_root = Phronomy::Agent::AgentRoot.create(
+      agent_id: "execution-agent-#{SecureRandom.uuid}",
+      agent_definition_id: "contract-agent",
+      definition_version: 1
+    )
+    persistence.agents.create(other_root)
+    own = build_contract_execution(execution_agent_root)
+    other = build_contract_execution(other_root)
+    execution_repository.create_active(own)
+    execution_repository.create_active(other)
+
+    execution_repository.delete_for_agent(execution_agent_root.agent_id)
+
+    expect(execution_repository.list_active(execution_agent_root.agent_id)).to be_empty
+    expect(execution_repository.load(other.execution_id).execution_id).to eq(other.execution_id)
+  end
+end

data/lib/phronomy/testing/persistence_contract.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "phronomy"
+
+begin
+  require "rspec/core"
+  require "rspec/expectations"
+rescue LoadError => error
+  raise LoadError,
+    "Phronomy Persistence contract support requires RSpec. " \
+    "Add `rspec` to the backend project's development/test dependencies before " \
+    "requiring `phronomy/testing/persistence_contract`.",
+    error.backtrace
+end
+
+module Phronomy
+  module Testing
+    # Explicitly loaded RSpec shared examples for Persistence backend authors.
+    #
+    # This namespace is intentionally excluded from Phronomy's production
+    # Zeitwerk eager-load path. Requiring this file is the opt-in boundary that
+    # loads RSpec and the backend conformance suite.
+    module PersistenceContract
+      SHARED_EXAMPLES = [
+        "a persistence content store",
+        "an Agent repository",
+        "a Journal repository",
+        "an Execution repository",
+        "a workflow state repository",
+        "a Persistence backend"
+      ].freeze
+    end
+  end
+end
+
+require_relative "persistence_contract/a_content_store"
+require_relative "persistence_contract/an_agent_repository"
+require_relative "persistence_contract/a_journal_repository"
+require_relative "persistence_contract/an_execution_repository"
+require_relative "persistence_contract/a_workflow_state_repository"
+require_relative "persistence_contract/a_persistence_backend"

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -8,8 +8,8 @@ module Phronomy
   class Workflow
     include Phronomy::Runnable
 
-    def self.define(context_class, state_store: nil, &block)
-      builder = Builder.new(context_class, state_store: state_store)
+    def self.define(context_class, persistence: nil, &block)
+      builder = Builder.new(context_class, persistence: persistence)
       builder.instance_eval(&block)
       builder.build
     end
@@ -41,12 +41,13 @@ module Phronomy
       @runner.send_event(state: state, event: event, input: input)
     end
 
-    # Sends an event to an active Workflow session without blocking.
+    # Sends an event to an active Workflow execution without blocking.
     #
-    # This method is safe to call from an Agent/Tool listener running on the
-    # EventLoop thread because it only enqueues a later dispatch.
+    # +thread_id+ is the logical/durable Workflow identity. EventLoop resolves it
+    # to the currently owning Runtime-only fsm_session_id. InvocationContext's
+    # application session_id is unrelated to this routing.
     #
-    # @return [Boolean] true when admitted; false when the session is not live
+    # @return [Boolean] true when admitted; false when the Workflow is not live
     #   or Runtime shutdown has begun
     # @api public
     def signal(thread_id:, event:, payload: nil)
@@ -76,9 +77,9 @@ module Phronomy
     class Builder
       FINISH = Phronomy::WorkflowRunner::FINISH
 
-      def initialize(context_class, state_store: nil)
+      def initialize(context_class, persistence: nil)
         @context_class = context_class
-        @state_store = state_store
+        @persistence = persistence
         @initial = nil
         @declared_states = []
         @entry_actions = {}
@@ -167,7 +168,7 @@ module Phronomy
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
           wait_state_names: @wait_state_names.dup,
-          state_store: @state_store
+          persistence: @persistence
         )
         Workflow.new(runner)
       end