phronomy 0.26.0 → 0.27.0

data/lib/phronomy/{agent → multi_agent}/handoff_runner.rb

@@ -3,8 +3,8 @@
 require "time"
 
 module Phronomy
-  module Agent
-    # Durable Agent-domain responsibility routing within one Persistence instance.
+  module MultiAgent
+    # Coordinates durable handoffs across Agents using one Persistence instance.
     # @api public
     class HandoffRunner
       MAX_HANDOFFS = 20
@@ -16,7 +16,7 @@ module Phronomy
       def initialize(main_agent:, handoffs: [])
         @main_agent, @handoffs = main_agent, Array(handoffs).freeze
         @persistence = main_agent.persistence
-        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Handoff) }
+        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Phronomy::Agent::Handoff) }
         @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |a| [a.agent_id, a] }.freeze
         unless @agents.values.all? { |a| a.persistence.equal?(@persistence) }
           raise Phronomy::ConfigurationError, "Durable Handoff graph requires one Persistence instance"
@@ -24,8 +24,9 @@ module Phronomy
         if @handoffs.group_by { |h| [h.source_agent.agent_id, h.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
           raise ArgumentError, "Duplicate Source/Target Handoff edges"
         end
-        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| HandoffCapabilityFactory.build(h) }.freeze }.freeze
+        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| Phronomy::Agent::HandoffCapabilityFactory.build(h) }.freeze }.freeze
         @runtime = Phronomy::Runtime.instance
+        @admissions = Phronomy::MultiAgent::AdmissionRegistry.for(@runtime)
       end
 
       # @api public
@@ -41,7 +42,7 @@ module Phronomy
           raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime"
         end
         config = config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
-        @runtime.__admit_multi_agent(main_agent)
+        @admissions.admit!(main_agent)
         admitted = true
         state = load_state
         count = 0
@@ -49,7 +50,7 @@ module Phronomy
           active = @agents.fetch(state.active_agent_id) do
             raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}"
           end
-          context = state.active_handoff_context_ref && HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
+          context = state.active_handoff_context_ref && Phronomy::Agent::HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
           wiring = config.merge(phronomy_handoff_bindings: @bindings.fetch(active.agent_id, []),
             phronomy_handoff_context: context,
             phronomy_coordination: {"kind" => "handoff", "main_agent_id" => main_agent.agent_id, "handoff_revision" => state.handoff_revision}).freeze
@@ -61,11 +62,11 @@ module Phronomy
             else
               exact = unfinished.fetch(0)
               unless unfinished.size == 1 && exact.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-                raise Phronomy::Persistence::ConflictError, "Active Agent execution belongs to another coordination turn"
+                raise Phronomy::Storage::ConflictError, "Active Agent execution belongs to another coordination turn"
               end
               wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(exact.execution_id)
               stored_input = @persistence.contents.fetch_text(exact.metadata.fetch("current_input_ref"))
-              ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
+              Phronomy::Agent::ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
             end
           else
             source = @persistence.executions.load(state.pending_source_execution_id)
@@ -77,7 +78,7 @@ module Phronomy
               raise Phronomy::ConfigurationError, "Handoff Target definition mismatch"
             end
             wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(state.pending_target_execution_id)
-            ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
+            Phronomy::Agent::ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
               input: context.responsibility, config: wiring).wait_result
           end
           execution = @persistence.executions.load(result.fetch(:execution_id))
@@ -90,7 +91,7 @@ module Phronomy
           if execution.active?
             raise Phronomy::ExecutionRehydrationRequiredError, "Handoff execution requires approval or recovery"
           end
-          raise RecoverySupport.error_from_failure(result[:error]) if result[:error]
+          raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
           return result.reject { |key, _| key.to_s.start_with?("_phronomy_") || key == :handoff_request }.merge(agent: active)
         end
       rescue Phronomy::CancellationError => error
@@ -101,7 +102,7 @@ module Phronomy
         operation_error = error
         raise
       ensure
-        @runtime.__release_multi_agent(main_agent) if admitted
+        @admissions.release!(main_agent) if admitted
         Phronomy::Tracing::Automatic.finish(trace_handle, output: result && result[:output], error: operation_error)
       end
 
@@ -117,25 +118,25 @@ module Phronomy
           @persistence.transaction do |tx|
             first = tx.executions.load(execution_id)
             unless first.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-              raise Phronomy::Persistence::ConflictError, "Execution does not belong to this Handoff anchor"
+              raise Phronomy::Storage::ConflictError, "Execution does not belong to this Handoff anchor"
             end
             leaf = first
             leaf_id = first.execution_id
             seen = {}
             while leaf&.status == :handed_off
-              raise Phronomy::Persistence::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
+              raise Phronomy::Storage::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
               seen[leaf_id] = true
               leaf_id = leaf.metadata.fetch("handoff_target_execution_id")
               begin
                 leaf = tx.executions.load(leaf_id)
-              rescue Phronomy::Persistence::NotFoundError
+              rescue Phronomy::Storage::NotFoundError
                 leaf = nil
               end
             end
             next if leaf&.terminal?
             routing = tx.handoff_states.load(main_agent.agent_id)
             unless routing && (leaf ? routing.active_agent_id == leaf.agent_id : routing.pending_target_execution_id == leaf_id)
-              raise Phronomy::Persistence::ConflictError, "Handoff routing no longer owns the requested turn"
+              raise Phronomy::Storage::ConflictError, "Handoff routing no longer owns the requested turn"
             end
             ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf_id]).uniq
             intended = routing.with(phase: leaf ? routing.phase : "stable",
@@ -147,7 +148,7 @@ module Phronomy
           raise error unless intended && confirmed && Array(confirmed.metadata["cancelled_execution_ids"]).include?(leaf_id)
         end
         return @persistence.execution_result(leaf_id) if leaf&.terminal?
-        ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
+        Phronomy::Agent::ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
         {execution_id: leaf_id, cancellation_requested: !leaf&.terminal?}.freeze
       end
 
@@ -163,7 +164,7 @@ module Phronomy
         state = @persistence.handoff_states.load(main_agent.agent_id)
         return state if state
         now = Time.now.utc.iso8601(6)
-        initial = HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
+        initial = Phronomy::Agent::HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
           active_agent_id: main_agent.agent_id, active_handoff_context_ref: nil,
           phase: "stable", pending_source_execution_id: nil, pending_target_execution_id: nil,
           created_at: now, updated_at: now, metadata: {})

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -23,7 +23,7 @@ module Phronomy
           raise Phronomy::EventLoopReentrancyError, "Orchestrator#resume cannot block EventLoop"
         end
         execution = persistence.executions.load(execution_id)
-        raise Phronomy::Persistence::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
+        raise Phronomy::Storage::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
         input = persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
         result = Phronomy::Agent::ExactExecution.start(agent: self, execution_id: execution_id, input: input, config: config).wait_result
         raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
@@ -174,7 +174,7 @@ module Phronomy
           invocation_context: invocation_context, concurrency_limit: max_concurrency) do |child, execution|
           # Preserve a child-specific context as well as this dispatch's controls.
           # Agent admission adds that context's constraints to the supplied token.
-          binding = Phronomy::Execution.__operation_binding(
+          binding = Phronomy::Concurrency::OperationBinding.new(
             invocation_context: execution.invocation_context,
             cancellation_token: child.config[:cancellation_token]
           )

data/lib/phronomy/multi_agent/persistence/codec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Current-format record schemas and conversion for this domain.
+      # @api private
+      module Codec
+        extend Phronomy::Storage::RecordCodec
+
+        module_function
+
+        def encode_team_root(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::TeamRoot.from_h(payload)
+          build_record("phronomy.team_root", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode TeamRoot", error)
+        end
+
+        def decode_team_root(record)
+          payload = current_payload!(record, record_type: "phronomy.team_root",
+            format_version: "0.1", keys: Phronomy::MultiAgent::TeamRoot::ATTRIBUTES, label: "TeamRoot")
+          Phronomy::MultiAgent::TeamRoot.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode TeamRoot", error)
+        end
+
+        def encode_team_execution(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::TeamExecution.from_h(payload)
+          build_record("phronomy.team_execution", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode TeamExecution", error)
+        end
+
+        def decode_team_execution(record)
+          payload = current_payload!(record, record_type: "phronomy.team_execution",
+            format_version: "0.1", keys: Phronomy::MultiAgent::TeamExecution::ATTRIBUTES, label: "TeamExecution")
+          Phronomy::MultiAgent::TeamExecution.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode TeamExecution", error)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/queries.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Read and assemble domain results; the public entry point owns the execution-thread guard.
+      # @api private
+      class Queries
+        def initialize(repositories)
+          @repositories = repositories
+        end
+
+        def team_execution_result(team_execution_id)
+          execution = @repositories.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 && @repositories.contents.fetch_json(execution.result_ref),
+            error: execution.error_ref && @repositories.contents.fetch_json(execution.error_ref)
+          }.then { |value| Phronomy::Values::Immutable.copy(value) }
+        end
+
+        def list_team_executions(team_id, after: nil, limit: 100)
+          @repositories.team_executions.list(team_id, after: after, limit: limit)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/team_execution_repository.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns execution activity, ownership, admission and durable record encoding.
+      # @api private
+      class TeamExecutionRepository
+        def initialize(view) = @view = view
+
+        def create_active(execution)
+          raise Phronomy::Storage::SerializationError, "create_active requires an active TeamExecution" unless execution.active?
+          record = Codec.encode_team_execution(execution)
+          admission do
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).insert(key: execution.team_execution_id.to_s,
+                revision: Integer(execution.execution_revision), attributes: attributes(execution), record: record)
+              decode(entry, execution.team_execution_id, owner: execution.team_id,
+                revision: execution.execution_revision, active: true)
+            end
+          end
+        end
+
+        def load(team_execution_id)
+          value = @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).read(team_execution_id.to_s)
+            entry && decode(entry, team_execution_id)
+          end
+          value || raise(Phronomy::Storage::NotFoundError, "TeamExecution not found: #{team_execution_id}")
+        end
+
+        def save(team_execution_id, expected_revision:, execution:)
+          expected = Integer(expected_revision)
+          revision = Integer(execution.execution_revision)
+          raise Phronomy::Storage::ConflictError, "execution save must advance revision exactly once" unless revision == expected + 1
+          unless execution.team_execution_id.to_s == team_execution_id.to_s
+            raise Phronomy::Storage::SerializationError, "Execution identity mismatch"
+          end
+          record = Codec.encode_team_execution(execution)
+          admission do
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).replace(key: team_execution_id.to_s,
+                expected_revision: expected, next_revision: revision, attributes: attributes(execution),
+                expected_attributes: execution.active? ? {active: true} : {}, record: record)
+              decode(entry, team_execution_id, owner: execution.team_id, revision: revision, active: execution.active?)
+            end
+          end
+        end
+
+        def list_active(team_id)
+          @view.atomic do |bound|
+            bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).scan(index: :owner_active,
+              equals: {owner: team_id.to_s, active: true}).map { |entry| decode(entry, entry.key, owner: team_id, active: true) }.freeze
+          end
+        end
+
+        def list(team_id, after: nil, limit: 100)
+          raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+          @view.atomic do |bound|
+            bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).scan(index: :owner, equals: {owner: team_id.to_s},
+              after: after&.to_s, limit: limit).map { |entry| decode(entry, entry.key, owner: team_id) }.freeze
+          end
+        end
+
+        def delete(team_execution_id)
+          @view.records(Phronomy::TeamStorageSchema::EXECUTIONS).delete(key: team_execution_id.to_s)
+        end
+
+        def delete_for_team(team_id)
+          @view.records(Phronomy::TeamStorageSchema::EXECUTIONS).delete_matching(index: :owner, equals: {owner: team_id.to_s})
+        end
+
+        def assert_idle!(team_id)
+          condition = Phronomy::Storage::Condition::NoRows.new(resource: Phronomy::TeamStorageSchema::EXECUTIONS,
+            index: :owner_active, equals: {owner: team_id.to_s, active: true})
+          @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: Phronomy::TeamStorageSchema::ROOTS, key: team_id.to_s)],
+            conditions: [condition])
+        rescue Phronomy::Storage::ConditionFailedError => error
+          raise unless error.condition.equal?(condition)
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        private
+
+        def attributes(execution) = {owner: execution.team_id.to_s, active: execution.active?}
+
+        def admission
+          yield
+        rescue Phronomy::Storage::UniqueConstraintError => error
+          raise unless error.resource == Phronomy::TeamStorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        def decode(entry, team_execution_id, owner: nil, revision: nil, active: nil)
+          execution = Codec.decode_team_execution(entry.record)
+          valid = entry.key == team_execution_id.to_s && execution.team_execution_id == entry.key &&
+            execution.execution_revision == entry.revision && attributes(execution) == entry.attributes &&
+            (!owner || execution.team_id == owner.to_s) && (!revision || execution.execution_revision == revision) &&
+            (active.nil? || execution.active? == active)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Team Execution identity/metadata"
+          end
+          execution
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/team_repository.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns Team root encoding and validates returned storage metadata.
+      # @api private
+      class TeamRepository
+        def initialize(view) = @view = view
+
+        def create(root)
+          record = Codec.encode_team_root(root)
+          @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).insert(key: root.team_id.to_s,
+              revision: Integer(root.team_revision), attributes: {}, record: record)
+            decode(entry, root.team_id, revision: root.team_revision)
+          end
+        end
+
+        def load(team_id)
+          value = @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).read(team_id.to_s)
+            entry && decode(entry, team_id)
+          end
+          value || raise(Phronomy::Storage::NotFoundError, "Team not found: #{team_id}")
+        end
+
+        def save(team_id, expected_revision:, root:)
+          expected = Integer(expected_revision)
+          revision = Integer(root.team_revision)
+          raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
+          unless root.team_id.to_s == team_id.to_s
+            raise Phronomy::Storage::SerializationError, "Team root identity mismatch"
+          end
+          record = Codec.encode_team_root(root)
+          @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).replace(key: team_id.to_s,
+              expected_revision: expected, next_revision: revision, attributes: {}, record: record)
+            decode(entry, team_id, revision: revision)
+          end
+        end
+
+        def delete(team_id)
+          @view.records(Phronomy::TeamStorageSchema::ROOTS).delete(key: team_id.to_s)
+        end
+
+        private
+
+        def decode(entry, team_id, revision: nil)
+          root = Codec.decode_team_root(entry.record)
+          valid = entry.key == team_id.to_s && root.team_id == entry.key &&
+            root.team_revision == entry.revision && (!revision || revision == entry.revision)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Team identity/revision"
+          end
+          root
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → multi_agent}/shared_state.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
-    # Implements peer coordination through a shared KnowledgeStore.
+  module MultiAgent
+    # Implements peer coordination through an invocation-local KnowledgeStore.
+    # @api public
     class SharedState
       # Semantic revision of the framework-owned SharedState instrumentation
       # applied on top of one specific researcher definition revision.
@@ -13,6 +14,8 @@ module Phronomy
       INSTRUMENTATION_DEFINITION_VERSION = 1
       private_constant :INSTRUMENTATION_DEFINITION_VERSION
 
+      # Findings shared by the sequential members of one invocation.
+      # @api public
       class KnowledgeStore
         def initialize
           @findings = []
@@ -78,8 +81,15 @@ module Phronomy
       # @api public
       def invoke(input, config: {})
         validate_termination!
-
         store = KnowledgeStore.new
+        cycles, terminated_by = coordinate_members(input, store)
+
+        {output: aggregate_findings(store), cycles: cycles, terminated_by: terminated_by}
+      end
+
+      private
+
+      def coordinate_members(input, store)
         max_cycles = self.class._max_cycles
         deadline = self.class._timeout ? Time.now + self.class._timeout : nil
         terminated_by = :max_cycles
@@ -87,15 +97,7 @@ module Phronomy
         cycle_limit = max_cycles || Float::INFINITY
 
         (1..cycle_limit).each do |cycle|
-          self.class._members.each do |member_config|
-            invoke_researcher(
-              member_config[:klass],
-              store,
-              cycle,
-              input,
-              member_config[:instruction]
-            )
-          end
+          invoke_members(input, store, cycle)
           completed_cycles = cycle
 
           if self.class._terminate_when&.call(store)
@@ -109,17 +111,25 @@ module Phronomy
           end
         end
 
-        output = if self.class._aggregator
+        [completed_cycles, terminated_by]
+      end
+
+      def invoke_members(input, store, cycle)
+        self.class._members.each do |member_config|
+          invoke_researcher(
+            member_config[:klass], store, cycle, input, member_config[:instruction]
+          )
+        end
+      end
+
+      def aggregate_findings(store)
+        if self.class._aggregator
           self.class._aggregator.call(store)
         else
           store.read_all
         end
-
-        {output: output, cycles: completed_cycles, terminated_by: terminated_by}
       end
 
-      private
-
       def validate_termination!
         return if self.class._max_cycles || self.class._timeout
 
@@ -148,28 +158,8 @@ module Phronomy
 
       def build_instrumented_researcher(researcher_class, store, cycle)
         agent_key = researcher_class.name&.to_sym || researcher_class.object_id.to_s.to_sym
-
-        read_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name "read_store"
-          description "Read all current findings from the shared knowledge store. " \
-            "Call this to see what other researchers have discovered."
-          execution_mode :cooperative
-
-          define_method(:execute) { store.read_all.to_json }
-        end
-
-        write_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name "write_finding"
-          description "Record a new finding into the shared knowledge store so " \
-            "that other researchers can build on your discovery."
-          execution_mode :cooperative
-          param :content, type: :string, desc: "The finding to record"
-
-          define_method(:execute) do |content:|
-            store.write(agent: agent_key, content: content, cycle: cycle)
-            "Finding recorded."
-          end
-        end
+        read_tool = build_read_tool(store)
+        write_tool = build_write_tool(store, cycle, agent_key)
 
         definitions = researcher_class.tools.to_h do |tool_class|
           [tool_class, researcher_class.tool_aliases[tool_class]]
@@ -197,12 +187,39 @@ module Phronomy
         end
       end
 
+      def build_read_tool(store)
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
+          tool_name "read_store"
+          description "Read all current findings from the shared knowledge store. " \
+            "Call this to see what other researchers have discovered."
+          execution_mode :cooperative
+
+          define_method(:execute) { store.read_all.to_json }
+        end
+      end
+
+      def build_write_tool(store, cycle, agent_key)
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
+          tool_name "write_finding"
+          description "Record a new finding into the shared knowledge store so " \
+            "that other researchers can build on your discovery."
+          execution_mode :cooperative
+          param :content, type: :string, desc: "The finding to record"
+
+          define_method(:execute) do |content:|
+            store.write(agent: agent_key, content: content, cycle: cycle)
+            "Finding recorded."
+          end
+        end
+      end
+
       def instrumented_definition_for(researcher_class)
         parent_def = researcher_class.agent_definition
         parent_id = parent_def.fetch(:id)
         parent_version = parent_def.fetch(:version)
 
         {
+          # Keep the existing semantic ID across the Ruby namespace migration.
           id: "Phronomy::Agent::SharedState::Instrumented/#{parent_id}@#{parent_version}".freeze,
           version: INSTRUMENTATION_DEFINITION_VERSION
         }.freeze

data/lib/phronomy/multi_agent/storage_contract/team_storage_schema.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Domain-owned Team metadata, independent of coordination runtime loading.
+  # @api private
+  module TeamStorageSchema
+    ROOTS = Phronomy::Storage::Resource.new(id: "team.roots", kind: :records,
+      guard: {resource: "team.roots", via: :key})
+    EXECUTIONS = Phronomy::Storage::Resource.new(id: "team.executions", kind: :records,
+      attributes: {owner: :string, active: :boolean}, immutable_attributes: [:owner],
+      indexes: {owner: [:owner], owner_active: [:owner, :active]},
+      unique: [{name: :one_active_owner, fields: [:owner], where: {active: true}}],
+      guard: {resource: ROOTS.id, via: :owner})
+  end
+end