phronomy 0.22.0 → 0.23.0

data/lib/phronomy/persistence.rb

@@ -13,51 +13,73 @@ module Phronomy
       optimistic_revision: true
     }.freeze
 
-    # Durable repository accessors supplied by a Persistence backend.
+    # Content-addressed immutable content repository. ContentStore has its own
+    # codec/canonicalization boundary and is not wrapped in DurableRecord.
     #
-    # 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
+    # @return [Object]
     # @api public
     attr_reader :contents
 
-    # @return [Object] AgentRoot repository
+    # Runtime/domain-facing AgentRoot repository. The backend repository supplied
+    # to #initialize is record-oriented; this facade owns encode/decode.
+    #
+    # @return [Object]
     # @api public
     attr_reader :agents
 
-    # @return [Object] append-only Agent Journal repository
+    # Runtime/domain-facing append-only Agent Journal repository.
+    #
+    # @return [Object]
     # @api public
     attr_reader :journals
 
-    # @return [Object] AgentExecution repository
+    # Runtime/domain-facing AgentExecution repository.
+    #
+    # @return [Object]
     # @api public
     attr_reader :executions
 
-    # @return [Object] durable Workflow snapshot repository
+    # Runtime/domain-facing durable Workflow snapshot repository.
+    #
+    # @return [Object]
     # @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
+    # Initializes a Persistence backend from record-oriented storage
+    # repositories.
+    #
+    # Except for +contents+, backend repositories exchange
+    # {Phronomy::Persistence::DurableRecord} values. Phronomy's repository
+    # facades own current-format validation and domain-object encode/decode.
+    #
+    # Identity, revision, admission, and index metadata needed by a Backend is
+    # passed explicitly as repository arguments. A Backend must not inspect
+    # DurableRecord#payload to rediscover Phronomy domain semantics.
+    #
+    # Required raw repository shapes:
+    # - agents:
+    #   create(agent_id:, agent_revision:, record:), load(id),
+    #   save(id, expected_revision:, next_revision:, record:), delete(id)
+    # - journals:
+    #   append(id, expected_position:, records:, record_ids:), read/head/delete
+    # - executions:
+    #   create_active(execution_id:, agent_id:, execution_revision:, record:),
+    #   load(id), save(id, expected_revision:, next_revision:, agent_id:,
+    #   active:, record:), list_active/delete/delete_for_agent/assert_idle!
+    # - workflow_states:
+    #   load(id), save(id, expected_revision:, next_revision:, record:), delete
+    #
+    # Subclasses normally construct backend-specific raw repository objects and
+    # call +super+. Construction fails fast when required capabilities are not
+    # advertised.
+    #
     # @api public
     def initialize(contents:, agents:, journals:, executions:, workflow_states:)
       @contents = contents
-      @agents = agents
-      @journals = journals
-      @executions = executions
-      @workflow_states = workflow_states
+      @agents = RepositoryFacades::Agents.new(agents)
+      @journals = RepositoryFacades::Journals.new(journals)
+      @executions = RepositoryFacades::Executions.new(executions)
+      @workflow_states = RepositoryFacades::WorkflowStates.new(workflow_states)
       validate_capabilities!
     end
 
@@ -84,11 +106,9 @@ module Phronomy
 
     # 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.
+    # The yielded object is a transaction-scoped Persistence view exposing the
+    # same domain-facing repository facades. Its underlying backend repositories
+    # remain DurableRecord-oriented.
     #
     # If the block raises, mutations made through the transaction view must not
     # be committed. Storage failures whose commit outcome is fundamentally
@@ -103,6 +123,36 @@ module Phronomy
       raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
     end
 
+    # Backend SPI helper for transaction implementations whose transaction-scoped
+    # raw repositories differ from the root repository objects.
+    #
+    # +watermark+ is a transaction-scoped object responding to
+    # +assert_agent_watermark!+. The returned view owns the same Phronomy codec
+    # facades as the root Persistence instance, so backend authors never need to
+    # instantiate RepositoryFacades directly.
+    #
+    # Backends whose repository objects are already transaction-scoped may yield
+    # +self+ and need not call this helper.
+    #
+    # @api public
+    def build_transaction_view(
+      contents:,
+      agents:,
+      journals:,
+      executions:,
+      workflow_states:,
+      watermark:
+    )
+      RepositoryFacades::View.new(
+        contents: contents,
+        agents: agents,
+        journals: journals,
+        executions: executions,
+        workflow_states: workflow_states,
+        watermark: watermark
+      )
+    end
+
     # Verifies that a live Agent still owns the durable base it hydrated.
     #
     # This is a Backend SPI operation invoked by Phronomy at durable barriers.
@@ -111,16 +161,6 @@ module Phronomy
     # 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,

data/lib/phronomy/recovery.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Small private Recovery semantic/primitives layer shared by Agent and
+  # Workflow recovery. Entity-specific orchestration remains outside this module.
+  # @api private
+  module Recovery
+    RESUMABLE = :resumable
+    RECONCILABLE = :reconcilable
+    RESOLUTION_REQUIRED = :resolution_required
+    DISPOSITIONS = [RESUMABLE, RECONCILABLE, RESOLUTION_REQUIRED].freeze
+
+    ALLOWED_OUTCOMES = %i[succeeded failed not_performed].freeze
+    # Internal shorthand used by the Agent Recovery implementation. This is not
+    # a public API constant; both names refer to the same frozen value.
+    OUTCOMES = ALLOWED_OUTCOMES
+
+    MISSING = Object.new.freeze
+
+    Classification = Data.define(
+      :disposition, :reason, :subject, :allowed_outcomes, :facts
+    ) do
+      def initialize(
+        disposition:,
+        reason:,
+        subject: nil,
+        allowed_outcomes: [],
+        facts: {}
+      )
+        normalized = disposition.to_sym
+        unless Phronomy::Recovery::DISPOSITIONS.include?(normalized)
+          raise ArgumentError, "unknown Recovery disposition: #{disposition.inspect}"
+        end
+        super(
+          disposition: normalized,
+          reason: reason.to_sym,
+          subject: subject && Phronomy::Recovery.normalize_subject(subject),
+          allowed_outcomes: Array(allowed_outcomes).map(&:to_sym).freeze,
+          facts: Phronomy::Agent::Immutable.copy(facts || {})
+        )
+      end
+    end
+
+    module_function
+
+    def normalize_outcome(outcome)
+      normalized = outcome.to_sym
+      unless OUTCOMES.include?(normalized)
+        raise ArgumentError, "unsupported Recovery outcome: #{outcome.inspect}"
+      end
+      normalized
+    end
+
+    def validate_resolution_material!(outcome:, result_present:, error_present:)
+      normalized = normalize_outcome(outcome)
+      case normalized
+      when :succeeded
+        raise ArgumentError, "Recovery :succeeded requires result:" unless result_present
+        raise ArgumentError, "Recovery :succeeded forbids error:" if error_present
+      when :failed
+        raise ArgumentError, "Recovery :failed requires error:" unless error_present
+        raise ArgumentError, "Recovery :failed forbids result:" if result_present
+      when :not_performed
+        if result_present || error_present
+          raise ArgumentError, "Recovery :not_performed accepts neither result: nor error:"
+        end
+      end
+      true
+    end
+
+    def normalize_subject(subject)
+      hash = subject.to_h.transform_keys(&:to_sym)
+      type = hash.fetch(:type).to_sym
+      normalized = {type: type}
+      case type
+      when :llm_call
+        normalized[:llm_call_id] = required_id(hash, :llm_call_id)
+      when :tool_invocation
+        normalized[:tool_invocation_id] = required_id(hash, :tool_invocation_id)
+      when :persistence_operation
+        # Persistence operation references are structural only. Do not introduce
+        # a generic durable operation/recovery identity here.
+        normalized[:entity] = hash.fetch(:entity).to_sym
+      else
+        raise ArgumentError, "unsupported Recovery subject type: #{type.inspect}"
+      end
+      normalized.freeze
+    end
+
+    def subject_key(subject)
+      normalized = normalize_subject(subject)
+      case normalized.fetch(:type)
+      when :llm_call
+        "llm_call:#{normalized.fetch(:llm_call_id)}"
+      when :tool_invocation
+        "tool_invocation:#{normalized.fetch(:tool_invocation_id)}"
+      when :persistence_operation
+        "persistence_operation:#{normalized.fetch(:entity)}"
+      end
+    end
+
+    def subject_equal?(left, right)
+      normalize_subject(left) == normalize_subject(right)
+    rescue ArgumentError, KeyError
+      false
+    end
+
+    # Compare authoritative current state with a known pre/post revision pair.
+    # This is deliberately small: callers still validate entity-specific content.
+    def compare_revisions(current_revision:, expected_pre_revision:, intended_post_revision:)
+      current = current_revision
+      return :post_state if current == intended_post_revision
+      return :pre_state if current == expected_pre_revision
+
+      :conflict
+    end
+
+    # Generic F1 helper for revisioned snapshot repositories such as Workflow.
+    # Some repositories return a newly allocated revision only after save, so
+    # callers may not know the intended post revision in advance. In that case
+    # the intended snapshot plus a revision different from the expected pre
+    # revision identifies the post-state.
+    def compare_revisioned_snapshot(
+      record:,
+      expected_pre_revision:,
+      intended_snapshot:,
+      intended_post_revision: nil
+    )
+      return :pre_state if record.nil? && expected_pre_revision.nil?
+      return :conflict if record.nil?
+
+      revision = fetch_value(record, :revision)
+      snapshot = fetch_value(record, :snapshot)
+      normalized_snapshot = normalize_value(snapshot)
+      normalized_intended = normalize_value(intended_snapshot)
+
+      if intended_post_revision
+        if revision == intended_post_revision &&
+            normalized_snapshot == normalized_intended
+          return :post_state
+        end
+      elsif normalized_snapshot == normalized_intended &&
+          revision != expected_pre_revision
+        return :post_state
+      end
+
+      return :pre_state if revision == expected_pre_revision
+
+      :conflict
+    end
+
+    def normalize_value(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, child), result|
+          result[key.to_s] = normalize_value(child)
+        end
+      when Array
+        value.map { |child| normalize_value(child) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+
+    def fetch_value(record, key)
+      return nil unless record
+      return record.public_send(key) if record.respond_to?(key)
+      return record[key] if record.respond_to?(:key?) && record.key?(key)
+      string_key = key.to_s
+      return record[string_key] if record.respond_to?(:key?) && record.key?(string_key)
+
+      nil
+    end
+
+    def required_id(hash, key)
+      value = hash.fetch(key)
+      text = value.to_s
+      raise ArgumentError, "#{key} must not be empty" if text.empty?
+
+      text.freeze
+    end
+    private_class_method :required_id
+  end
+end

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

@@ -8,7 +8,7 @@ RSpec.shared_examples "a Journal repository" do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "journal-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
   end
 
@@ -106,7 +106,7 @@ RSpec.shared_examples "a Journal repository" do
         expected_position: 0,
         records: [record]
       )
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    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

@@ -7,7 +7,7 @@ RSpec.shared_examples "a Persistence backend" do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "backend-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
   end
 

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

@@ -17,15 +17,15 @@ RSpec.shared_examples "a workflow state repository" do
     workflow_contract_value(record, :revision)
   end
 
-  it "returns nil for an unknown thread_id" do
+  it "returns nil for an unknown workflow_instance_id" do
     expect(repository.load("missing-#{SecureRandom.uuid}")).to be_nil
   end
 
   it "uses optimistic revisions for save" do
-    thread_id = "t1-#{SecureRandom.uuid}"
+    workflow_instance_id = "t1-#{SecureRandom.uuid}"
     expect(
       repository.save(
-        thread_id,
+        workflow_instance_id,
         expected_revision: nil,
         snapshot: {fields: {value: 1}, phase: "pause"}
       )
@@ -33,7 +33,7 @@ RSpec.shared_examples "a workflow state repository" do
 
     expect(
       repository.save(
-        thread_id,
+        workflow_instance_id,
         expected_revision: 1,
         snapshot: {fields: {value: 2}, phase: "__end__"}
       )
@@ -41,16 +41,16 @@ RSpec.shared_examples "a workflow state repository" do
   end
 
   it "rejects a stale expected_revision" do
-    thread_id = "t1-#{SecureRandom.uuid}"
+    workflow_instance_id = "t1-#{SecureRandom.uuid}"
     repository.save(
-      thread_id,
+      workflow_instance_id,
       expected_revision: nil,
       snapshot: {fields: {value: 1}, phase: "pause"}
     )
 
     expect do
       repository.save(
-        thread_id,
+        workflow_instance_id,
         expected_revision: nil,
         snapshot: {fields: {value: 2}, phase: "__end__"}
       )
@@ -58,14 +58,14 @@ RSpec.shared_examples "a workflow state repository" do
   end
 
   it "returns a snapshot representation accepted by WorkflowRunner" do
-    thread_id = "t1-#{SecureRandom.uuid}"
+    workflow_instance_id = "t1-#{SecureRandom.uuid}"
     repository.save(
-      thread_id,
+      workflow_instance_id,
       expected_revision: nil,
       snapshot: {fields: {value: 1}, phase: "pause"}
     )
 
-    record = repository.load(thread_id)
+    record = repository.load(workflow_instance_id)
     snapshot = workflow_contract_snapshot(record)
     fields = workflow_contract_value(snapshot, :fields)
 
@@ -75,14 +75,14 @@ RSpec.shared_examples "a workflow state repository" do
   end
 
   it "isolates stored snapshots from caller mutation" do
-    thread_id = "t1-#{SecureRandom.uuid}"
+    workflow_instance_id = "t1-#{SecureRandom.uuid}"
     repository.save(
-      thread_id,
+      workflow_instance_id,
       expected_revision: nil,
       snapshot: {fields: {values: [1]}, phase: "pause"}
     )
 
-    loaded = repository.load(thread_id)
+    loaded = repository.load(workflow_instance_id)
     snapshot = workflow_contract_snapshot(loaded)
     fields = workflow_contract_value(snapshot, :fields)
     values = workflow_contract_value(fields, :values)
@@ -93,7 +93,7 @@ RSpec.shared_examples "a workflow state repository" do
       nil
     end
 
-    reloaded = repository.load(thread_id)
+    reloaded = repository.load(workflow_instance_id)
     reloaded_fields = workflow_contract_value(
       workflow_contract_snapshot(reloaded),
       :fields
@@ -102,18 +102,18 @@ RSpec.shared_examples "a workflow state repository" do
   end
 
   it "deletes only at the expected revision" do
-    thread_id = "t1-#{SecureRandom.uuid}"
+    workflow_instance_id = "t1-#{SecureRandom.uuid}"
     repository.save(
-      thread_id,
+      workflow_instance_id,
       expected_revision: nil,
       snapshot: {fields: {}, phase: "pause"}
     )
 
     expect do
-      repository.delete(thread_id, expected_revision: 99)
+      repository.delete(workflow_instance_id, expected_revision: 99)
     end.to raise_error(Phronomy::Persistence::ConflictError)
 
-    repository.delete(thread_id, expected_revision: 1)
-    expect(repository.load(thread_id)).to be_nil
+    repository.delete(workflow_instance_id, expected_revision: 1)
+    expect(repository.load(workflow_instance_id)).to be_nil
   end
 end

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

@@ -8,7 +8,7 @@ RSpec.shared_examples "an Agent repository" do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "contract-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
   end
 
@@ -62,7 +62,7 @@ RSpec.shared_examples "an Agent repository" do
     other = Phronomy::Agent::AgentRoot.create(
       agent_id: "other-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     ).with(agent_revision: 1)
 
     expect do
@@ -71,7 +71,7 @@ RSpec.shared_examples "an Agent repository" do
         expected_revision: 0,
         root: other
       )
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 
   it "requires revision to advance exactly once" do

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

@@ -8,7 +8,7 @@ RSpec.shared_examples "an Execution repository" do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "execution-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
   end
 
@@ -66,7 +66,7 @@ RSpec.shared_examples "an Execution repository" do
     other_root = Phronomy::Agent::AgentRoot.create(
       agent_id: "execution-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
     persistence.agents.create(other_root)
 
@@ -116,7 +116,7 @@ RSpec.shared_examples "an Execution repository" do
     other_root = Phronomy::Agent::AgentRoot.create(
       agent_id: "execution-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
     persistence.agents.create(other_root)
     other = build_contract_execution(other_root).with(
@@ -131,7 +131,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: other
       )
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 
   it "requires execution revision to advance exactly once" do
@@ -186,7 +186,7 @@ RSpec.shared_examples "an Execution repository" do
     other_root = Phronomy::Agent::AgentRoot.create(
       agent_id: "execution-agent-#{SecureRandom.uuid}",
       agent_definition_id: "contract-agent",
-      definition_version: 1
+      agent_definition_version: 1
     )
     persistence.agents.create(other_root)
     own = build_contract_execution(execution_agent_root)