phronomy 0.23.0 → 0.24.0

data/lib/phronomy/persistence.rb

@@ -45,6 +45,89 @@ module Phronomy
     # @api public
     attr_reader :workflow_states
 
+    # Purpose-specific durable Handoff and Team repositories in atomic_all.
+    # @api public
+    attr_reader :handoff_states, :teams, :team_executions
+
+    # Read-only exact Agent execution result; never creates a live Agent owner.
+    # Result is nil until a result_ref exists; errors remain canonical data.
+    # @api public
+    def execution_result(execution_id)
+      assert_observation_thread!
+      execution = executions.load(execution_id)
+      {
+        execution_id: execution.execution_id, agent_id: execution.agent_id,
+        status: execution.status, phase: execution.phase,
+        result_ref: execution.result_ref, error_ref: execution.error_ref,
+        result: execution.result_ref && contents.fetch_text(execution.result_ref),
+        error: execution.error_ref && contents.fetch_json(execution.error_ref)
+      }.then { |value| Phronomy::Agent::Immutable.copy(value) }
+    end
+
+    # Follows one exact Handoff turn without loading any Agent or graph.
+    # A committed absent Target reservation remains active; failed reads raise.
+    # @api public
+    def handoff_result(execution_id, main_agent_id: nil)
+      assert_observation_thread!
+      anchor = main_agent_id&.to_s
+      seen = {}
+      current = execution_id.to_s
+      reserved_agent_id = nil
+      loop do
+        raise Phronomy::Persistence::SerializationError, "Cyclic durable Handoff chain" if seen[current]
+        seen[current] = true
+        begin
+          execution = executions.load(current)
+        rescue Phronomy::Persistence::NotFoundError
+          routing = handoff_states.load(anchor)
+          if routing && Array(routing.metadata["cancelled_execution_ids"]).include?(current)
+            return {execution_id: current, agent_id: reserved_agent_id, status: :cancelled, result: nil, error: nil}.freeze
+          end
+          if reserved_agent_id && routing && routing.phase != "stable" && routing.pending_target_execution_id == current
+            return {execution_id: current, agent_id: reserved_agent_id, status: :active,
+                    phase: :target_pending, reserved: true, result: nil, error: nil}.freeze
+          end
+          raise
+        end
+        anchor ||= execution.metadata.dig("coordination", "main_agent_id")
+        unless anchor && execution.metadata.dig("coordination", "main_agent_id") == anchor
+          raise Phronomy::Persistence::ConflictError, "Execution does not belong to this Handoff anchor"
+        end
+        return execution_result(current) unless execution.status == :handed_off
+        reserved_agent_id = execution.metadata.fetch("handoff_target_agent_id")
+        current = execution.metadata.fetch("handoff_target_execution_id")
+      end
+    end
+
+    # Lists retained active and terminal executions in lexical ID order.
+    # after is an exclusive ID cursor; discovery does not imply request dedup.
+    # @api public
+    def list_executions(agent_id, after: nil, limit: 100)
+      assert_observation_thread!
+      executions.list(agent_id, after: after, limit: limit)
+    end
+
+    # Read-only exact Team result, independent of current Team class/Proc wiring.
+    # @api public
+    def team_execution_result(team_execution_id)
+      assert_observation_thread!
+      execution = team_executions.load(team_execution_id)
+      {
+        team_execution_id: execution.team_execution_id, team_id: execution.team_id,
+        status: execution.status, phase: execution.phase,
+        result_ref: execution.result_ref, error_ref: execution.error_ref,
+        result: execution.result_ref && contents.fetch_json(execution.result_ref),
+        error: execution.error_ref && contents.fetch_json(execution.error_ref)
+      }.then { |value| Phronomy::Agent::Immutable.copy(value) }
+    end
+
+    # Lists retained Team runs; no continuation or callback delivery occurs.
+    # @api public
+    def list_team_executions(team_id, after: nil, limit: 100)
+      assert_observation_thread!
+      team_executions.list(team_id, after: after, limit: limit)
+    end
+
     # Initializes a Persistence backend from record-oriented storage
     # repositories.
     #
@@ -74,12 +157,15 @@ module Phronomy
     # advertised.
     #
     # @api public
-    def initialize(contents:, agents:, journals:, executions:, workflow_states:)
+    def initialize(contents:, agents:, journals:, executions:, workflow_states:, handoff_states:, teams:, team_executions:)
       @contents = contents
       @agents = RepositoryFacades::Agents.new(agents)
       @journals = RepositoryFacades::Journals.new(journals)
       @executions = RepositoryFacades::Executions.new(executions)
       @workflow_states = RepositoryFacades::WorkflowStates.new(workflow_states)
+      @handoff_states = RepositoryFacades::HandoffStates.new(handoff_states)
+      @teams = RepositoryFacades::Teams.new(teams)
+      @team_executions = RepositoryFacades::TeamExecutions.new(team_executions)
       validate_capabilities!
     end
 
@@ -141,6 +227,7 @@ module Phronomy
       journals:,
       executions:,
       workflow_states:,
+      handoff_states:, teams:, team_executions:,
       watermark:
     )
       RepositoryFacades::View.new(
@@ -149,6 +236,7 @@ module Phronomy
         journals: journals,
         executions: executions,
         workflow_states: workflow_states,
+        handoff_states: handoff_states, teams: teams, team_executions: team_executions,
         watermark: watermark
       )
     end
@@ -169,6 +257,12 @@ module Phronomy
 
     private
 
+    def assert_observation_thread!
+      if Phronomy::Runtime.in_event_loop_context?
+        raise Phronomy::EventLoopReentrancyError, "Persistence observation cannot block EventLoop"
+      end
+    end
+
     def validate_capabilities!
       missing = REQUIRED_CAPABILITIES.reject do |key, value|
         capabilities[key] == value

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

@@ -36,6 +36,7 @@ RSpec.shared_examples "a Persistence backend" do
         :journals,
         :executions,
         :workflow_states,
+        :handoff_states, :teams, :team_executions,
         :assert_agent_watermark!
       )
     end

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/version.rb

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

data/scripts/api_snapshot.rb

@@ -34,9 +34,9 @@ PUBLIC_API_ENTRIES = [
   Phronomy::Runnable,
   Phronomy::Agent::Context::Instruction::PromptTemplate,
   # Beta
-  Phronomy::MultiAgent::Handoff,
-  Phronomy::MultiAgent::HandoffPolicy,
-  Phronomy::MultiAgent::Runner,
+  Phronomy::Agent::Handoff,
+  Phronomy::Agent::HandoffPolicy,
+  Phronomy::Agent::HandoffRunner,
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Filter::Base,

data/sig/phronomy/handoff.rbs

@@ -0,0 +1,41 @@
+module Phronomy
+  module Agent
+    class Handoff
+      attr_reader source_agent: ::Phronomy::Agent::Base
+      attr_reader target_agent: ::Phronomy::Agent::Base
+      attr_reader policy: HandoffPolicy
+      attr_reader description: String
+
+      def initialize: (source_agent: ::Phronomy::Agent::Base, target_agent: ::Phronomy::Agent::Base, ?policy: HandoffPolicy, ?description: String?) -> void
+    end
+
+    class HandoffPolicy
+      CATEGORIES: Array[Symbol]
+      MODES: Array[Symbol]
+      DEFAULTS: Array[Symbol]
+
+      def self.define: () { () -> void } -> HandoffPolicy
+      def self.default: () -> HandoffPolicy
+
+      def rule: (Symbol | String) -> untyped
+      def required?: (Symbol | String) -> bool
+      def forbidden?: (Symbol | String) -> bool
+      def selectable?: (Symbol | String) -> bool
+      def default_include?: (Symbol | String) -> bool
+      def selectable_categories: () -> Array[Symbol]
+      def to_h: () -> Hash[String, Hash[String, String]]
+    end
+
+    class HandoffRunner
+      MAX_HANDOFFS: Integer
+
+      attr_reader main_agent: ::Phronomy::Agent::Base
+      attr_reader handoffs: Array[Handoff]
+
+      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[Handoff]) -> void
+      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def result: (String execution_id) -> Hash[Symbol, untyped]
+      def cancel: (String execution_id) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/phronomy/multi_agent.rbs

@@ -1,39 +1,35 @@
 module Phronomy
   module MultiAgent
-    class Handoff
-      attr_reader source_agent: ::Phronomy::Agent::Base
-      attr_reader target_agent: ::Phronomy::Agent::Base
-      attr_reader policy: HandoffPolicy
-      attr_reader description: String
-
-      def initialize: (source_agent: ::Phronomy::Agent::Base, target_agent: ::Phronomy::Agent::Base, ?policy: HandoffPolicy, ?description: String?) -> void
+    class Orchestrator < ::Phronomy::Agent::Base
+      def self.subagent: (Symbol | String name, singleton(::Phronomy::Agent::Base) agent_class, ?on_error: Symbol, ?inherit_knowledge: bool) -> untyped
+      def self.registered_subagents: () -> Hash[Symbol | String, untyped]
+      def resume: (String execution_id, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def dispatch_parallel: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]
+      def dispatch_parallel_async: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::Task[untyped]
+      def fan_out: (agent: singleton(::Phronomy::Agent::Base), inputs: Array[untyped], ?config: Hash[Symbol, untyped], ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]
+      def fan_out_async: (agent: singleton(::Phronomy::Agent::Base), inputs: Array[untyped], ?config: Hash[Symbol, untyped], ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::Task[untyped]
     end
 
-    class HandoffPolicy
-      CATEGORIES: Array[Symbol]
-      MODES: Array[Symbol]
-      DEFAULTS: Array[Symbol]
-
-      def self.define: () { () -> void } -> HandoffPolicy
-      def self.default: () -> HandoffPolicy
-
-      def rule: (Symbol | String) -> untyped
-      def required?: (Symbol | String) -> bool
-      def forbidden?: (Symbol | String) -> bool
-      def selectable?: (Symbol | String) -> bool
-      def default_include?: (Symbol | String) -> bool
-      def selectable_categories: () -> Array[Symbol]
-      def to_h: () -> Hash[String, Hash[String, String]]
-    end
-
-    class Runner
-      MAX_HANDOFFS: Integer
-
-      attr_reader main_agent: ::Phronomy::Agent::Base
-      attr_reader handoffs: Array[Handoff]
-
-      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[Handoff]) -> void
-      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    class TeamCoordinator
+      attr_reader team_id: String
+      attr_reader persistence: ::Phronomy::Persistence
+      def self.team_definition: (?id: String?, ?version: Integer?) -> Hash[Symbol, String | Integer]
+      def self.coordinator_model: (?String? value) -> String?
+      def self.coordinator_instructions: (?String? value) -> String?
+      def self.coordinator_provider: (?Symbol? value) -> Symbol?
+      def self.pool: (size: Integer, agent: singleton(::Phronomy::Agent::Base), ?on_error: Symbol) -> untyped
+      def self.schedule: () { (Array[untyped]) -> untyped } -> untyped
+      def self.aggregate: () { (Array[Hash[Symbol, untyped]]) -> untyped } -> untyped
+      def self.new: (?team_id: String, ?persistence: ::Phronomy::Persistence?, ?metadata: Hash[String, untyped], ?on_event: ^(untyped) -> untyped) -> instance
+      def self.create: (**untyped options) -> instance
+      def self.load: (String team_id, persistence: ::Phronomy::Persistence, ?on_event: ^(untyped) -> untyped) -> instance
+      def self.get: (String team_id) -> instance?
+      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> untyped
+      def stream: (untyped input, ?config: Hash[Symbol, untyped]) ?{ (Hash[Symbol, untyped]) -> untyped } -> untyped
+      def resume: (String team_execution_id, ?config: Hash[Symbol, untyped]) -> untyped
+      def result: (String team_execution_id) -> Hash[Symbol, untyped]
+      def executions: (?after: String?, ?limit: Integer) -> Array[untyped]
+      def cancel: (String team_execution_id) -> Hash[Symbol, untyped]
     end
   end
 end

data/sig/phronomy/persistence.rbs

@@ -25,6 +25,7 @@ module Phronomy
     def load: (String execution_id) -> untyped
     def save: (String execution_id, expected_revision: Integer, execution: untyped) -> untyped
     def list_active: (String agent_id) -> Array[untyped]
+    def list: (String agent_id, ?after: String?, ?limit: Integer) -> Array[untyped]
     def delete: (String execution_id) -> untyped
     def delete_for_agent: (String agent_id) -> untyped
     def assert_idle!: (String agent_id) -> untyped
@@ -58,6 +59,7 @@ module Phronomy
     def load: (String execution_id) -> Persistence::DurableRecord
     def save: (String execution_id, expected_revision: Integer, next_revision: Integer, agent_id: String, active: bool, record: Persistence::DurableRecord) -> Persistence::DurableRecord
     def list_active: (String agent_id) -> Array[Persistence::DurableRecord]
+    def list: (String agent_id, ?after: String?, ?limit: Integer) -> Array[Persistence::DurableRecord]
     def delete: (String execution_id) -> untyped
     def delete_for_agent: (String agent_id) -> untyped
     def assert_idle!: (String agent_id) -> untyped
@@ -69,6 +71,54 @@ module Phronomy
     def delete: (String workflow_instance_id, expected_revision: Integer) -> untyped
   end
 
+  interface _HandoffStateRepository
+    def load: (String main_agent_id) -> untyped
+    def save: (String main_agent_id, expected_revision: Integer?, state: untyped) -> untyped
+    def delete: (String main_agent_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _TeamRepository
+    def create: (untyped root) -> untyped
+    def load: (String team_id) -> untyped
+    def save: (String team_id, expected_revision: Integer, root: untyped) -> untyped
+    def delete: (String team_id) -> untyped
+  end
+
+  interface _TeamExecutionRepository
+    def create_active: (untyped execution) -> untyped
+    def load: (String team_execution_id) -> untyped
+    def save: (String team_execution_id, expected_revision: Integer, execution: untyped) -> untyped
+    def list_active: (String team_id) -> Array[untyped]
+    def list: (String team_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+    def delete: (String team_execution_id) -> untyped
+    def delete_for_team: (String team_id) -> untyped
+    def assert_idle!: (String team_id) -> untyped
+  end
+
+  interface _BackendHandoffStateRecordRepository
+    def load: (String main_agent_id) -> Persistence::DurableRecord?
+    def save: (String main_agent_id, expected_revision: Integer?, next_revision: Integer, active_agent_id: String, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def delete: (String main_agent_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _BackendTeamRecordRepository
+    def create: (team_id: String, team_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def load: (String team_id) -> Persistence::DurableRecord
+    def save: (String team_id, expected_revision: Integer, next_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def delete: (String team_id) -> untyped
+  end
+
+  interface _BackendTeamExecutionRecordRepository
+    def create_active: (team_execution_id: String, team_id: String, execution_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def load: (String team_execution_id) -> Persistence::DurableRecord
+    def save: (String team_execution_id, expected_revision: Integer, next_revision: Integer, team_id: String, active: bool, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def list_active: (String team_id) -> Array[Persistence::DurableRecord]
+    def list: (String team_id, ?after: String?, ?limit: Integer) -> Array[Persistence::DurableRecord]
+    def delete: (String team_execution_id) -> untyped
+    def delete_for_team: (String team_id) -> untyped
+    def assert_idle!: (String team_id) -> untyped
+  end
+
   interface _BackendWatermark
     def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
   end
@@ -79,6 +129,9 @@ module Phronomy
     def journals: () -> _JournalRepository
     def executions: () -> _ExecutionRepository
     def workflow_states: () -> _WorkflowStateRepository
+    def handoff_states: () -> _HandoffStateRepository
+    def teams: () -> _TeamRepository
+    def team_executions: () -> _TeamExecutionRepository
     def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
   end
 
@@ -118,11 +171,19 @@ module Phronomy
     attr_reader journals: _JournalRepository
     attr_reader executions: _ExecutionRepository
     attr_reader workflow_states: _WorkflowStateRepository
-
-    def initialize: (contents: _ContentRepository, agents: _BackendAgentRecordRepository, journals: _BackendJournalRecordRepository, executions: _BackendExecutionRecordRepository, workflow_states: _BackendWorkflowStateRecordRepository) -> void
+    attr_reader handoff_states: _HandoffStateRepository
+    attr_reader teams: _TeamRepository
+    attr_reader team_executions: _TeamExecutionRepository
+    def handoff_result: (String execution_id, ?main_agent_id: String?) -> Hash[Symbol, untyped]
+    def execution_result: (String execution_id) -> Hash[Symbol, untyped]
+    def list_executions: (String agent_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+    def team_execution_result: (String team_execution_id) -> Hash[Symbol, untyped]
+    def list_team_executions: (String team_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+
+    def initialize: (contents: _ContentRepository, agents: _BackendAgentRecordRepository, journals: _BackendJournalRecordRepository, executions: _BackendExecutionRecordRepository, workflow_states: _BackendWorkflowStateRecordRepository, handoff_states: _BackendHandoffStateRecordRepository, teams: _BackendTeamRecordRepository, team_executions: _BackendTeamExecutionRecordRepository) -> void
     def capabilities: () -> Hash[Symbol, bool]
     def transaction: () { (_PersistenceTransactionView) -> untyped } -> untyped
-    def build_transaction_view: (contents: _ContentRepository, agents: _BackendAgentRecordRepository, journals: _BackendJournalRecordRepository, executions: _BackendExecutionRecordRepository, workflow_states: _BackendWorkflowStateRecordRepository, watermark: _BackendWatermark) -> _PersistenceTransactionView
+    def build_transaction_view: (contents: _ContentRepository, agents: _BackendAgentRecordRepository, journals: _BackendJournalRecordRepository, executions: _BackendExecutionRecordRepository, workflow_states: _BackendWorkflowStateRecordRepository, handoff_states: _BackendHandoffStateRecordRepository, teams: _BackendTeamRecordRepository, team_executions: _BackendTeamExecutionRecordRepository, watermark: _BackendWatermark) -> _PersistenceTransactionView
     def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -150,7 +150,17 @@ files:
 - docs/decisions/025-process-local-agent-ownership-and-runtime-admission.md
 - docs/decisions/026-workflow-runtime-admission-and-durable-terminal-barrier.md
 - docs/decisions/027-llm-adapter-provider-boundary.md
+- docs/decisions/028-preparing-recovery-replay-contract.md
+- docs/decisions/029-semantic-completion-and-application-effect-boundary.md
+- docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md
+- docs/decisions/031-durable-multi-agent-coordination.md
 - docs/decisions/README.md
+- docs/design/durable-semantic-coordination/CHANGELOG_V2_REVISION_2.md
+- docs/design/durable-semantic-coordination/CONTINUATION_DECISION_REFACTOR.md
+- docs/design/durable-semantic-coordination/IMPLEMENTATION_DESIGN_V2.md
+- docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md
+- docs/design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md
+- docs/design/durable-semantic-coordination/RESPONSIBILITY_BOUNDARY_REVIEW.md
 - docs/features.md
 - docs/getting-started.md
 - docs/mcp-client.md
@@ -158,6 +168,7 @@ files:
 - docs/migrations/0.16.md
 - docs/migrations/0.19.md
 - docs/migrations/0.22.md
+- docs/migrations/durable-semantic-coordination-v2.md
 - docs/persistence-backends.md
 - docs/runtime-and-concurrency.md
 - examples/README.md
@@ -186,7 +197,18 @@ files:
 - lib/phronomy/agent/context_policy.rb
 - lib/phronomy/agent/context_policy_input.rb
 - lib/phronomy/agent/context_policy_input_builder.rb
+- lib/phronomy/agent/exact_execution.rb
+- lib/phronomy/agent/execution_cancellation.rb
 - lib/phronomy/agent/execution_coordinator.rb
+- lib/phronomy/agent/handoff.rb
+- lib/phronomy/agent/handoff_capability_factory.rb
+- lib/phronomy/agent/handoff_context.rb
+- lib/phronomy/agent/handoff_execution_coordinator.rb
+- lib/phronomy/agent/handoff_policy.rb
+- lib/phronomy/agent/handoff_projection.rb
+- lib/phronomy/agent/handoff_request.rb
+- lib/phronomy/agent/handoff_runner.rb
+- lib/phronomy/agent/handoff_state.rb
 - lib/phronomy/agent/immutable.rb
 - lib/phronomy/agent/journal_projection.rb
 - lib/phronomy/agent/journal_record.rb
@@ -233,6 +255,7 @@ files:
 - lib/phronomy/engine/runtime.rb
 - lib/phronomy/engine/runtime/agent_ownership_registry.rb
 - lib/phronomy/engine/runtime/shutdown_result.rb
+- lib/phronomy/engine/runtime/team_ownership_registry.rb
 - lib/phronomy/engine/runtime/timer_queue.rb
 - lib/phronomy/engine/runtime/timer_service.rb
 - lib/phronomy/engine/task.rb
@@ -254,21 +277,14 @@ files:
 - lib/phronomy/llm_context_window/token_estimator.rb
 - lib/phronomy/metrics.rb
 - lib/phronomy/multi_agent/admission_registry.rb
-- lib/phronomy/multi_agent/coordination_state.rb
-- lib/phronomy/multi_agent/coordinator.rb
-- lib/phronomy/multi_agent/execution_coordinator.rb
+- lib/phronomy/multi_agent/durable_subagent_coordinator.rb
 - lib/phronomy/multi_agent/fan_out_invocation.rb
 - lib/phronomy/multi_agent/fan_out_session_builder.rb
-- lib/phronomy/multi_agent/handoff.rb
-- lib/phronomy/multi_agent/handoff_capability_factory.rb
-- lib/phronomy/multi_agent/handoff_context.rb
-- lib/phronomy/multi_agent/handoff_policy.rb
-- lib/phronomy/multi_agent/handoff_projection.rb
-- lib/phronomy/multi_agent/handoff_request.rb
 - lib/phronomy/multi_agent/orchestrator.rb
 - lib/phronomy/multi_agent/parallel_tool_chat.rb
-- lib/phronomy/multi_agent/runner.rb
 - lib/phronomy/multi_agent/team_coordinator.rb
+- lib/phronomy/multi_agent/team_execution.rb
+- lib/phronomy/multi_agent/team_root.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
@@ -304,6 +320,7 @@ files:
 - lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
 - lib/phronomy/testing/persistence_contract/an_agent_repository.rb
 - lib/phronomy/testing/persistence_contract/an_execution_repository.rb
+- lib/phronomy/testing/persistence_contract/coordination_repositories.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/base.rb
@@ -350,6 +367,7 @@ files:
 - sig/phronomy.rbs
 - sig/phronomy/agent.rbs
 - sig/phronomy/extensions.rbs
+- sig/phronomy/handoff.rbs
 - sig/phronomy/llm_adapter.rbs
 - sig/phronomy/multi_agent.rbs
 - sig/phronomy/persistence.rbs