phronomy 0.22.0 → 0.24.0

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+RSpec.shared_context "coordination repository values" do
+  let(:coordination_team) do
+    now = Time.now.utc.iso8601(6)
+    Phronomy::MultiAgent::TeamRoot.new(team_id: SecureRandom.uuid,
+      team_definition_id: "contract-team", team_definition_version: 1,
+      team_revision: 0, lifecycle_status: "idle", created_at: now, updated_at: now, metadata: {})
+  end
+  let(:coordination_run) do
+    now = Time.now.utc.iso8601(6)
+    Phronomy::MultiAgent::TeamExecution.new(team_execution_id: SecureRandom.uuid,
+      team_id: coordination_team.team_id, execution_revision: 0, status: "active", phase: "coordinator",
+      input_ref: nil, coordinator: {}, tasks: [], workers: [], assignments: [], result_ref: nil,
+      error_ref: nil, created_at: now, updated_at: now, metadata: {})
+  end
+  let(:coordination_handoff) do
+    now = Time.now.utc.iso8601(6)
+    Phronomy::Agent::HandoffState.new(main_agent_id: SecureRandom.uuid, handoff_revision: 1,
+      active_agent_id: "contract-target", active_handoff_context_ref: nil, phase: "target_pending",
+      pending_source_execution_id: "source-execution", pending_target_execution_id: "target-execution",
+      created_at: now, updated_at: now, metadata: {})
+  end
+end
+
+RSpec.shared_examples "a Handoff state repository" do
+  include_context "coordination repository values"
+
+  it "returns nil only for an authoritative absent Handoff anchor" do
+    expect(persistence.handoff_states.load(SecureRandom.uuid)).to be_nil
+  end
+
+  it "round-trips the immutable Handoff snapshot and rejects stale routing CAS" do
+    value = coordination_handoff
+    persistence.handoff_states.save(value.main_agent_id, expected_revision: nil, state: value)
+    loaded = persistence.handoff_states.load(value.main_agent_id)
+    expect(loaded.to_h).to eq(value.to_h)
+    expect(loaded).to be_frozen
+    updated = value.with(phase: "stable")
+    persistence.handoff_states.save(value.main_agent_id, expected_revision: 1, state: updated)
+    expect do
+      persistence.handoff_states.save(value.main_agent_id, expected_revision: 1, state: updated)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+    expect(persistence.handoff_states.load(value.main_agent_id).handoff_revision).to eq(2)
+  end
+
+  it "rejects a snapshot for a different routing anchor" do
+    expect do
+      persistence.handoff_states.save("other", expected_revision: nil, state: coordination_handoff)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
+  end
+end
+
+RSpec.shared_examples "a Team repository" do
+  include_context "coordination repository values"
+
+  it "round-trips a Team lineage and rejects duplicate creation" do
+    persistence.teams.create(coordination_team)
+    expect(persistence.teams.load(coordination_team.team_id).to_h).to eq(coordination_team.to_h)
+    expect { persistence.teams.create(coordination_team) }.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rejects a stale Team revision" do
+    persistence.teams.create(coordination_team)
+    updated = coordination_team.with(lifecycle_status: "active")
+    persistence.teams.save(coordination_team.team_id, expected_revision: 0, root: updated)
+    expect do
+      persistence.teams.save(coordination_team.team_id, expected_revision: 0, root: updated)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "raises NotFoundError for an absent Team" do
+    expect { persistence.teams.load(SecureRandom.uuid) }.to raise_error(Phronomy::Persistence::NotFoundError)
+  end
+end
+
+RSpec.shared_examples "a Team execution repository" do
+  include_context "coordination repository values"
+  before { persistence.teams.create(coordination_team) }
+
+  it "atomically admits at most one active run per Team" do
+    persistence.team_executions.create_active(coordination_run)
+    other = coordination_run.with(team_execution_id: SecureRandom.uuid, execution_revision: 0)
+    expect { persistence.team_executions.create_active(other) }.to raise_error(Phronomy::AgentBusyError)
+    expect(persistence.team_executions.list_active(coordination_team.team_id).map(&:team_execution_id)).to eq([coordination_run.team_execution_id])
+  end
+
+  it "releases admission after terminal CAS while retaining discoverable outcomes" do
+    persistence.team_executions.create_active(coordination_run)
+    completed = coordination_run.with(status: "completed", phase: "completed")
+    persistence.team_executions.save(coordination_run.team_execution_id, expected_revision: 0, execution: completed)
+    other = coordination_run.with(team_execution_id: SecureRandom.uuid, execution_revision: 0)
+    persistence.team_executions.create_active(other)
+    ids = [completed.team_execution_id, other.team_execution_id].sort
+    expect(persistence.team_executions.list(coordination_team.team_id, limit: 1).map(&:team_execution_id)).to eq(ids.first(1))
+    expect(persistence.team_executions.list(coordination_team.team_id, after: ids.first).map(&:team_execution_id)).to eq(ids.last(1))
+    expect(persistence.team_executions.list("other-team")).to be_empty
+    expect do
+      persistence.team_executions.save(completed.team_execution_id, expected_revision: 0, execution: completed)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+    expect do
+      persistence.team_executions.save(completed.team_execution_id, expected_revision: 1,
+        execution: completed.with(status: "active", phase: "coordinator"))
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+  end
+
+  it "rolls the new three repositories back with the existing transaction domain" do
+    handoff = coordination_handoff
+    root_id = "coordination-rollback-agent-#{SecureRandom.uuid}"
+    content_ref = nil
+    expect do
+      persistence.transaction do |tx|
+        tx.team_executions.create_active(coordination_run)
+        tx.teams.save(coordination_team.team_id, expected_revision: 0, root: coordination_team.with(lifecycle_status: "active"))
+        tx.handoff_states.save(handoff.main_agent_id, expected_revision: nil, state: handoff)
+        content_ref = tx.contents.put_text("coordination-rollback-#{SecureRandom.uuid}")
+        root = Phronomy::Agent::AgentRoot.create(agent_id: root_id, agent_definition_id: "rollback", agent_definition_version: 1)
+        tx.agents.create(root)
+        tx.journals.append(root_id, expected_position: 0, records: [])
+        record = Phronomy::Agent::JournalRecord.new(agent_id: root_id, kind: :input_received, channel: :external)
+        tx.executions.create_active(Phronomy::Agent::AgentExecution.start(agent_root: root, input_record: record))
+        tx.workflow_states.save(root_id, expected_revision: nil, snapshot: {fields: {value: "committed"}, phase: "pause"})
+        raise "rollback all eight"
+      end
+    end.to raise_error(RuntimeError, "rollback all eight")
+    expect(persistence.teams.load(coordination_team.team_id).team_revision).to eq(0)
+    expect(persistence.handoff_states.load(handoff.main_agent_id)).to be_nil
+    expect(persistence.team_executions.list(coordination_team.team_id)).to be_empty
+    expect { persistence.agents.load(root_id) }.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect(persistence.executions.list(root_id)).to be_empty
+    expect(persistence.workflow_states.load(root_id)).to be_nil
+    expect(persistence.contents.exist?(content_ref)).to be(false)
+  end
+end

data/lib/phronomy/testing/persistence_contract.rb

@@ -27,6 +27,9 @@ module Phronomy
         "a Journal repository",
         "an Execution repository",
         "a workflow state repository",
+        "a Handoff state repository",
+        "a Team repository",
+        "a Team execution repository",
         "a Persistence backend"
       ].freeze
     end
@@ -39,3 +42,5 @@ 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"
+
+require_relative "persistence_contract/coordination_repositories"

data/lib/phronomy/tools/agent.rb

@@ -161,7 +161,7 @@ module Phronomy
       end
 
       def settle_async_error(task, error)
-        if error.is_a?(Phronomy::ToolError) || error.is_a?(Phronomy::CancellationError)
+        if error.is_a?(Phronomy::ToolError) || error.is_a?(Phronomy::CancellationError) || error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
           task.fail(error)
           return task
         end

data/lib/phronomy/tracing/automatic.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tracing
+    # Framework-private automatic instrumentation for the small D02-F03
+    # logical-operation coverage set.
+    #
+    # This helper deliberately does not define trace-context propagation,
+    # durable span state, or backend-native parent/child semantics.
+    # @api private
+    module Automatic
+      REDACTED = "[REDACTED]"
+      SENSITIVE_METADATA_KEYS = %i[user_id session_id].freeze
+
+      Handle = Data.define(:name, :tracer, :span, :trace_pii)
+      private_constant :Handle
+
+      module_function
+
+      def start(name, input: nil, **metadata)
+        trace_pii = false
+        configuration = Phronomy.configuration
+        trace_pii = !!configuration.trace_pii
+        tracer = configuration.tracer
+        span = tracer.start_span(
+          name,
+          input: traced_payload(input, trace_pii: trace_pii),
+          **safe_metadata(metadata, trace_pii: trace_pii)
+        )
+        Handle.new(
+          name: name.to_s.freeze,
+          tracer: tracer,
+          span: span,
+          trace_pii: trace_pii
+        )
+      rescue => error
+        report_failure(:start, name, error, include_message: trace_pii)
+        nil
+      end
+
+      def finish(handle, output: nil, usage: nil, error: nil)
+        return nil unless handle
+
+        attributes = {
+          output: traced_payload(output, trace_pii: handle.trace_pii),
+          usage: usage,
+          error: traced_error(error, trace_pii: handle.trace_pii)
+        }.freeze
+
+        if Phronomy::Runtime.in_event_loop_context?
+          submit_finish(handle, attributes)
+        else
+          finish_now(handle, attributes)
+        end
+        nil
+      rescue => trace_error
+        # simplecov:disable
+        report_failure(
+          :finish,
+          handle&.name || "unknown",
+          trace_error,
+          include_message: handle ? handle.trace_pii : false
+        )
+        nil
+        # simplecov:enable
+      end
+
+      def observe_task(task, name, input: nil, **metadata)
+        handle = start(name, input: input, **metadata)
+        task.on_complete do |value, error|
+          finish(
+            handle,
+            output: value,
+            usage: task_usage(value),
+            error: error
+          )
+        end
+        task
+      end
+
+      def trace(name, input: nil, **metadata)
+        handle = start(name, input: input, **metadata)
+        result = yield
+        finish(handle, output: result, usage: task_usage(result))
+        result
+      rescue => operation_error
+        finish(handle, error: operation_error) if defined?(handle)
+        raise
+      end
+
+      def traced_payload(value, trace_pii:)
+        return value if trace_pii
+        return nil if value.nil?
+
+        REDACTED
+      end
+      private_class_method :traced_payload
+
+      def safe_metadata(metadata, trace_pii:)
+        metadata.each_with_object({}) do |(key, value), safe|
+          next if value.nil?
+
+          normalized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+          next if !trace_pii && SENSITIVE_METADATA_KEYS.include?(normalized_key)
+
+          safe[key] = value
+        end
+      end
+      private_class_method :safe_metadata
+
+      def traced_error(error, trace_pii:)
+        return nil unless error
+        return error if trace_pii
+
+        redacted = error.exception(REDACTED)
+        redacted.set_backtrace([])
+        redacted
+      rescue
+        fallback = StandardError.new(REDACTED)
+        fallback.set_backtrace([])
+        fallback
+      end
+      private_class_method :traced_error
+
+      def task_usage(value)
+        return nil unless value.is_a?(Hash)
+
+        value[:usage] || value["usage"]
+      end
+      private_class_method :task_usage
+
+      def submit_finish(handle, attributes)
+        Phronomy::Runtime.instance.offload.submit(on_full: :raise) do
+          finish_now(handle, attributes)
+        end
+        nil
+      rescue => error
+        report_failure(
+          :finish,
+          handle.name,
+          error,
+          include_message: handle.trace_pii
+        )
+        nil
+      end
+      private_class_method :submit_finish
+
+      def finish_now(handle, attributes)
+        handle.tracer.finish_span(handle.span, **attributes)
+        nil
+      rescue => error
+        report_failure(
+          :finish,
+          handle.name,
+          error,
+          include_message: handle.trace_pii
+        )
+        nil
+      end
+      private_class_method :finish_now
+
+      def report_failure(stage, name, error, include_message:)
+        detail = include_message ? ": #{error.message}" : ""
+        message =
+          "[Phronomy] automatic tracing #{stage} failed for " \
+          "#{name}: #{error.class}#{detail}"
+        logger = Phronomy.configuration.logger
+        logger ? logger.warn(message) : Kernel.warn(message)
+        nil
+      rescue
+        nil
+      end
+      private_class_method :report_failure
+    end
+  end
+end

data/lib/phronomy/tracing/base.rb

@@ -12,8 +12,17 @@ module Phronomy
     #     c.tracer = MyTracer.new
     #   end
     #
-    # The tracer is then automatically used by Chain and Agent components
-    # via the #trace helper.
+    # The configured tracer instance may be shared by independent Phronomy
+    # operations. Phronomy does not serialize calls to that instance; #trace,
+    # #start_span, and #finish_span may therefore be entered concurrently.
+    # Custom tracer implementations must not assume exclusive single-operation use
+    # and must protect mutable shared state they own.
+    #
+    # This contract does not guarantee a particular OS thread, EventLoop,
+    # OffloadPool worker, or async-context affinity. Framework-owned automatic
+    # instrumentation uses this same start_span / finish_span SPI for a small
+    # set of logical operations. Phronomy guarantees portable semantic
+    # correlation metadata, not one backend-native parent/child span tree.
     class Base
       # Wraps a block in a span. Yields the span to the block.
       # Calls #finish_span with the output on success or with the error on failure.

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -13,8 +13,8 @@ module Phronomy
     # (+POST /api/public/ingestion+).  No external gem is required — only
     # Ruby standard-library network primitives are used.
     #
-    # Ingestion errors are silently swallowed so that a Langfuse outage never
-    # breaks the application.
+    # Ingestion failures are reported as warnings and are not re-raised, so a
+    # Langfuse outage does not fail the traced application operation.
     #
     # @example Configure globally
     #   Phronomy.configure do |c|
@@ -37,6 +37,7 @@ module Phronomy
         @secret_key = secret_key
         @host = host.chomp("/")
         @http = nil
+        @http_mutex = Mutex.new
       end
 
       # Returns a plain Hash that records the span start state.
@@ -91,16 +92,23 @@ module Phronomy
         req["Authorization"] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
         req.body = JSON.generate({batch: events})
 
-        @http ||= build_http(uri)
-        @http.request(req)
-      rescue IOError, Errno::ECONNRESET, Errno::EPIPE => e
-        # Connection was reset; drop the cached connection and warn.
-        @http = nil
-        warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
-        nil
-      rescue => e
-        warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
-        nil
+        # Net::HTTP persistent connections are mutable and are not used
+        # concurrently through one configured LangfuseTracer instance. This
+        # protects the adapter's own shared connection cache; it does not
+        # serialize Phronomy tracing calls or impose serialization on custom
+        # Tracing::Base implementations.
+        @http_mutex.synchronize do
+          @http ||= build_http(uri)
+          @http.request(req)
+        rescue IOError, Errno::ECONNRESET, Errno::EPIPE => e
+          # Connection was reset; drop the cached connection and warn.
+          @http = nil
+          warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
+          nil
+        rescue => e
+          warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
+          nil
+        end
       end
 
       def build_http(uri)

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -43,16 +43,16 @@ module Phronomy
 
     # Sends an event to an active Workflow execution without blocking.
     #
-    # +thread_id+ is the logical/durable Workflow identity. EventLoop resolves it
+    # +workflow_instance_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 Workflow is not live
     #   or Runtime shutdown has begun
     # @api public
-    def signal(thread_id:, event:, payload: nil)
+    def signal(workflow_instance_id:, event:, payload: nil)
       @runner.signal(
-        thread_id: thread_id,
+        workflow_instance_id: workflow_instance_id,
         event: event,
         payload: payload
       )
@@ -62,9 +62,6 @@ module Phronomy
 
     def _apply_invocation_context(config, invocation_context)
       effective = config.merge(invocation_context: invocation_context)
-      if effective[:thread_id].nil? && invocation_context.thread_id
-        effective = effective.merge(thread_id: invocation_context.thread_id)
-      end
       if effective[:cancellation_token].nil?
         token = invocation_context.effective_timeout_token
         effective = effective.merge(cancellation_token: token) if token

data/lib/phronomy/workflow_context.rb

@@ -19,6 +19,13 @@ module Phronomy
 
     module ClassMethods
       def field(name, type: :replace, default: nil)
+        # workflow_instance_id is framework-owned metadata; do not declare it as a field.
+        if name.to_sym == :workflow_instance_id
+          raise ArgumentError,
+            "WorkflowContext field :workflow_instance_id is reserved for " \
+            "framework-owned Workflow identity metadata. " \
+            "Use a different field name for application state."
+        end
         if default.is_a?(Array) || default.is_a?(Hash)
           raise ArgumentError,
             "Mutable default for field #{name.inspect} must be wrapped in a Proc " \
@@ -40,7 +47,7 @@ module Phronomy
       end
     end
 
-    attr_reader :thread_id
+    attr_reader :workflow_instance_id
 
     def phase
       @phase || :__end__
@@ -50,8 +57,10 @@ module Phronomy
       phase != :__end__
     end
 
-    def set_graph_metadata(thread_id: nil, phase: nil)
-      @thread_id = thread_id unless thread_id.nil?
+    # Workflow identity is explicit domain metadata. FSMSession supplies this
+    # metadata without a generic thread/session identity bridge.
+    def set_graph_metadata(workflow_instance_id: nil, phase: nil)
+      @workflow_instance_id = workflow_instance_id unless workflow_instance_id.nil?
       @phase = phase unless phase.nil?
       self
     end
@@ -75,7 +84,7 @@ module Phronomy
           attrs.fetch(name, default)
         )
       end
-      @thread_id = nil
+      @workflow_instance_id = nil
       @phase = :__end__
     end
 
@@ -107,7 +116,7 @@ module Phronomy
 
       new_context = self.class.new(**new_attrs)
       new_context.set_graph_metadata(
-        thread_id: @thread_id,
+        workflow_instance_id: @workflow_instance_id,
         phase: @phase
       )
       new_context

data/lib/phronomy/workflow_recovery.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # ACS-15 Workflow-side Persistence F1 reconciliation. Workflow hydration and
+  # orchestration remain owned by WorkflowRunner; this module only replaces the
+  # terminal durable barrier so response loss is reconciled from authoritative
+  # durable pre/post state instead of being treated as an ordinary failed save.
+  # @api private
+  module WorkflowRecovery
+    private
+
+    def begin_terminal_persistence_on_event_loop(
+      execution,
+      terminal_type:,
+      context:,
+      event_sink:
+    )
+      runtime = Phronomy::Runtime.instance
+      event_loop = runtime.event_loop
+      assert_event_loop!(event_loop)
+      event_loop.mark_workflow_admission(
+        execution.workflow_instance_id,
+        owner_token: execution.owner_token,
+        state: :persisting_terminal
+      )
+
+      operation = Phronomy::WorkflowRunner::WorkflowTerminalPersistenceCommand.new(
+        repository: execution.repository,
+        workflow_instance_id: execution.workflow_instance_id.to_s.freeze,
+        expected_revision: execution.expected_revision,
+        snapshot: deep_immutable_copy(snapshot_for(context))
+      )
+
+      task = runtime.offload.submit(on_full: :raise) do
+        revision = operation.repository.save(
+          operation.workflow_instance_id,
+          expected_revision: operation.expected_revision,
+          snapshot: operation.snapshot
+        )
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :success,
+          revision: revision,
+          error: nil
+        )
+      rescue Phronomy::Persistence::ConflictError,
+        Phronomy::Persistence::NotFoundError,
+        Phronomy::Persistence::SerializationError,
+        Phronomy::Persistence::UnsupportedBackendError => error
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :known_failure,
+          revision: nil,
+          error: error
+        )
+      rescue => error
+        reconcile_workflow_terminal_f1(operation, error)
+      end
+
+      task.on_complete do |result, operation_error|
+        delivery = if operation_error
+          Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+            outcome: :outcome_unknown,
+            revision: nil,
+            error: operation_error
+          )
+        else
+          result
+        end
+        accepted = event_sink.post(:workflow_terminal_persistence_result, delivery)
+        unless accepted
+          Phronomy.configuration.logger&.warn(
+            "[Phronomy] EventLoop rejected Workflow terminal persistence result " \
+            "for #{execution.workflow_instance_id.inspect}"
+          )
+        end
+      end
+      terminal_type
+    end
+
+    def reconcile_workflow_terminal_f1(operation, original_error)
+      record = operation.repository.load(operation.workflow_instance_id)
+      case Phronomy::Recovery.compare_revisioned_snapshot(
+        record: record,
+        expected_pre_revision: operation.expected_revision,
+        intended_snapshot: operation.snapshot
+      )
+      when :post_state
+        revision = Phronomy::Recovery.fetch_value(record, :revision)
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :success,
+          revision: revision,
+          error: nil
+        )
+      when :pre_state
+        # The uncertain save is now known not to have committed. Do not blindly
+        # retry it here; surface a known failure through the ordinary terminal
+        # barrier semantics.
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :known_failure,
+          revision: nil,
+          error: original_error
+        )
+      else
+        conflict = Phronomy::Persistence::ConflictError.new(
+          "Workflow terminal Persistence outcome conflicts with both expected " \
+          "pre-state and intended post-state for #{operation.workflow_instance_id.inspect}"
+        )
+        Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+          outcome: :outcome_unknown,
+          revision: nil,
+          error: conflict
+        )
+      end
+    rescue => reconciliation_error
+      Phronomy::WorkflowRunner::WorkflowTerminalPersistenceResult.new(
+        outcome: :outcome_unknown,
+        revision: nil,
+        error: reconciliation_error
+      )
+    end
+  end
+end
+
+Phronomy::WorkflowRunner.prepend(Phronomy::WorkflowRecovery)