phronomy 0.27.0 → 0.29.0

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

@@ -3,7 +3,7 @@
 require "securerandom"
 
 RSpec.shared_examples "an Execution repository" do
-  let(:execution_repository) { persistence.executions }
+  let(:execution_repository) { stores.agent.executions }
   let(:execution_agent_root) do
     Phronomy::Agent::AgentRoot.create(
       agent_id: "execution-agent-#{SecureRandom.uuid}",
@@ -27,7 +27,7 @@ RSpec.shared_examples "an Execution repository" do
   end
 
   before do
-    persistence.agents.create(execution_agent_root)
+    stores.agent.agents.create(execution_agent_root)
   end
 
   it "creates and loads an active execution" do
@@ -40,7 +40,7 @@ RSpec.shared_examples "an Execution repository" do
   it "raises NotFoundError for a missing execution" do
     expect do
       execution_repository.load("missing-#{SecureRandom.uuid}")
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 
   it "rejects a duplicate execution_id" do
@@ -49,7 +49,7 @@ RSpec.shared_examples "an Execution repository" do
 
     expect do
       execution_repository.create_active(execution)
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "admits at most one active or suspended execution for one Agent" do
@@ -68,7 +68,7 @@ RSpec.shared_examples "an Execution repository" do
       agent_definition_id: "contract-agent",
       agent_definition_version: 1
     )
-    persistence.agents.create(other_root)
+    stores.agent.agents.create(other_root)
 
     expect do
       execution_repository.create_active(build_contract_execution(execution_agent_root))
@@ -107,7 +107,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: updated
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects an execution identity mismatch" do
@@ -118,7 +118,7 @@ RSpec.shared_examples "an Execution repository" do
       agent_definition_id: "contract-agent",
       agent_definition_version: 1
     )
-    persistence.agents.create(other_root)
+    stores.agent.agents.create(other_root)
     other = build_contract_execution(other_root).with(
       execution_revision: 1,
       status: :active,
@@ -131,7 +131,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: other
       )
-    end.to raise_error(Phronomy::Storage::SerializationError)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 
   it "requires execution revision to advance exactly once" do
@@ -149,7 +149,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: skipped
       )
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "lists active executions for one Agent" do
@@ -179,7 +179,7 @@ RSpec.shared_examples "an Execution repository" do
 
     expect do
       execution_repository.load(execution.execution_id)
-    end.to raise_error(Phronomy::Storage::NotFoundError)
+    end.to raise_error(Phronomy::Persistence::NotFoundError)
   end
 
   it "deletes all executions for one Agent without deleting other Agents' executions" do
@@ -188,7 +188,7 @@ RSpec.shared_examples "an Execution repository" do
       agent_definition_id: "contract-agent",
       agent_definition_version: 1
     )
-    persistence.agents.create(other_root)
+    stores.agent.agents.create(other_root)
     own = build_contract_execution(execution_agent_root)
     other = build_contract_execution(other_root)
     execution_repository.create_active(own)

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

@@ -19,7 +19,7 @@ RSpec.shared_context "coordination repository values" do
   end
   let(:coordination_handoff) do
     now = Time.now.utc.iso8601(6)
-    Phronomy::Agent::HandoffState.new(main_agent_id: SecureRandom.uuid, handoff_revision: 1,
+    Phronomy::MultiAgent::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: {})
@@ -30,27 +30,27 @@ 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
+    expect(stores.multi_agent.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)
+    stores.multi_agent.handoff_states.save(value.main_agent_id, expected_revision: nil, state: value)
+    loaded = stores.multi_agent.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)
+    stores.multi_agent.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::Storage::ConflictError)
-    expect(persistence.handoff_states.load(value.main_agent_id).handoff_revision).to eq(2)
+      stores.multi_agent.handoff_states.save(value.main_agent_id, expected_revision: 1, state: updated)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
+    expect(stores.multi_agent.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::Storage::SerializationError)
+      stores.multi_agent.handoff_states.save("other", expected_revision: nil, state: coordination_handoff)
+    end.to raise_error(Phronomy::Persistence::SerializationError)
   end
 end
 
@@ -58,53 +58,53 @@ 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::Storage::ConflictError)
+    stores.multi_agent.teams.create(coordination_team)
+    expect(stores.multi_agent.teams.load(coordination_team.team_id).to_h).to eq(coordination_team.to_h)
+    expect { stores.multi_agent.teams.create(coordination_team) }.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rejects a stale Team revision" do
-    persistence.teams.create(coordination_team)
+    stores.multi_agent.teams.create(coordination_team)
     updated = coordination_team.with(lifecycle_status: "active")
-    persistence.teams.save(coordination_team.team_id, expected_revision: 0, root: updated)
+    stores.multi_agent.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::Storage::ConflictError)
+      stores.multi_agent.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::Storage::NotFoundError)
+    expect { stores.multi_agent.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) }
+  before { stores.multi_agent.teams.create(coordination_team) }
 
   it "atomically admits at most one active run per Team" do
-    persistence.team_executions.create_active(coordination_run)
+    stores.multi_agent.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])
+    expect { stores.multi_agent.team_executions.create_active(other) }.to raise_error(Phronomy::MultiAgent::TeamBusyError)
+    expect(stores.multi_agent.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)
+    stores.multi_agent.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)
+    stores.multi_agent.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)
+    stores.multi_agent.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(stores.multi_agent.team_executions.list(coordination_team.team_id, limit: 1).map(&:team_execution_id)).to eq(ids.first(1))
+    expect(stores.multi_agent.team_executions.list(coordination_team.team_id, after: ids.first).map(&:team_execution_id)).to eq(ids.last(1))
+    expect(stores.multi_agent.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::Storage::ConflictError)
+      stores.multi_agent.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,
+      stores.multi_agent.team_executions.save(completed.team_execution_id, expected_revision: 1,
         execution: completed.with(status: "active", phase: "coordinator"))
-    end.to raise_error(Phronomy::Storage::ConflictError)
+    end.to raise_error(Phronomy::Persistence::ConflictError)
   end
 
   it "rolls the new three repositories back with the existing transaction domain" do
@@ -112,26 +112,32 @@ RSpec.shared_examples "a Team execution repository" do
     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"
+      stores.coordinator.atomic do |scope|
+        stores.multi_agent.participate(scope) do |team|
+          stores.agent.participate(scope) do |agent|
+            scope.participate(persistence: stores.coordinator, adapter: Phronomy::Workflow::Persistence::StateRepository) do |workflow|
+              team.team_executions.create_active(coordination_run)
+              team.teams.save(coordination_team.team_id, expected_revision: 0, root: coordination_team.with(lifecycle_status: "active"))
+              team.handoff_states.save(handoff.main_agent_id, expected_revision: nil, state: handoff)
+              content_ref = agent.contents.put_text("coordination-rollback-#{SecureRandom.uuid}")
+              root = Phronomy::Agent::AgentRoot.create(agent_id: root_id, agent_definition_id: "rollback", agent_definition_version: 1)
+              agent.agents.create(root)
+              agent.journals.append(root_id, expected_position: 0, records: [])
+              record = Phronomy::Agent::JournalRecord.new(agent_id: root_id, kind: :input_received, channel: :external)
+              agent.executions.create_active(Phronomy::Agent::AgentExecution.start(agent_root: root, input_record: record))
+              workflow.save(root_id, expected_revision: nil, snapshot: {fields: {value: "committed"}, phase: "pause"})
+              raise "rollback all eight"
+            end
+          end
+        end
       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::Storage::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)
+    expect(stores.multi_agent.teams.load(coordination_team.team_id).team_revision).to eq(0)
+    expect(stores.multi_agent.handoff_states.load(handoff.main_agent_id)).to be_nil
+    expect(stores.multi_agent.team_executions.list(coordination_team.team_id)).to be_empty
+    expect { stores.agent.agents.load(root_id) }.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect(stores.agent.executions.list(root_id)).to be_empty
+    expect(stores.workflow.load(root_id)).to be_nil
+    expect(stores.agent.contents.exist?(content_ref)).to be(false)
   end
 end

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

@@ -4,7 +4,7 @@ require "securerandom"
 
 # This same opaque-record suite runs against InMemory, SQLite and PostgreSQL.
 RSpec.shared_examples "neutral storage primitives" do
-  let(:raw_backend) { persistence.backend }
+  let(:raw_backend) { stores.coordinator.backend }
   let(:raw_view) { raw_backend.view }
   let(:raw_schema) { Phronomy::Agent::Persistence::StorageSchema }
   let(:raw_record) { Phronomy::Storage::DurableRecord.new(record_type: "unrelated.envelope", format_version: "0.1", payload: {"status" => "ignored"}) }

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

@@ -9,7 +9,7 @@ RSpec.shared_examples "storage transaction boundaries" do
         view.is_a?(Phronomy::Storage::View) ? Phronomy::ContentStore::StoredContents.new(view) : view.contents
       end
 
-      let(:transaction_service) { (entry_point == :backend) ? persistence.backend : persistence }
+      let(:transaction_service) { (entry_point == :backend) ? stores.coordinator.backend : stores.agent }
 
       it "rolls back a failed inner scope and re-raises the same error before the outer scope continues" do
         outer_id = inner_id = later_id = nil
@@ -19,39 +19,40 @@ RSpec.shared_examples "storage transaction boundaries" do
         result = transaction_service.transaction do |outer|
           outer_id = transaction_contents(outer).put_text("outer-#{workflow_id}")
           expect do
-            transaction_service.transaction do |inner|
+            transaction_service.transaction do |inner, scope|
               inner_id = transaction_contents(inner).put_text("inner-#{workflow_id}")
               if entry_point == :backend
-                inner.records(Phronomy::WorkflowStorageSchema::STATES).insert(key: workflow_id,
+                inner.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).insert(key: workflow_id,
                   revision: 1, attributes: {}, record: Phronomy::Storage::DurableRecord.new(
                     record_type: "opaque.transaction", format_version: "0.1", payload: {"value" => "inner"}
                   ))
               else
-                inner.workflow_states.save(workflow_id,
-                  expected_revision: nil, snapshot: {fields: {value: "inner"}, phase: "pause"})
+                scope.participate(persistence: stores.coordinator, adapter: Phronomy::Workflow::Persistence::StateRepository) do |workflow|
+                  workflow.save(workflow_id, expected_revision: nil, snapshot: {fields: {value: "inner"}, phase: "pause"})
+                end
               end
               raise failure
             end
           end.to raise_error { |error| expect(error).to equal(failure) }
           expect(transaction_contents(outer).exist?(outer_id)).to be(true)
           expect(transaction_contents(outer).exist?(inner_id)).to be(false)
-          expect(persistence.backend.view.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_id)).to be_nil
+          expect(stores.coordinator.backend.view.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).read(workflow_id)).to be_nil
           later_id = transaction_contents(outer).put_text("later-#{workflow_id}")
           :outer_result
         end
 
         expect(result).to eq(:outer_result)
-        expect(persistence.contents.exist?(outer_id)).to be(true)
-        expect(persistence.contents.exist?(later_id)).to be(true)
-        expect(persistence.contents.exist?(inner_id)).to be(false)
-        expect(persistence.backend.view.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_id)).to be_nil
+        expect(stores.agent.contents.exist?(outer_id)).to be(true)
+        expect(stores.agent.contents.exist?(later_id)).to be(true)
+        expect(stores.agent.contents.exist?(inner_id)).to be(false)
+        expect(stores.coordinator.backend.view.records(Phronomy::Workflow::Persistence::StorageSchema::STATES).read(workflow_id)).to be_nil
       end
 
       it "commits both scopes on normal completion and returns their block values" do
         outer_id = inner_id = nil
         result = transaction_service.transaction do |outer|
           outer_id = transaction_contents(outer).put_text("outer-#{SecureRandom.uuid}")
-          inner_result = transaction_service.transaction do |inner|
+          inner_result = transaction_service.transaction do |inner, scope|
             inner_id = transaction_contents(inner).put_text("inner-#{SecureRandom.uuid}")
             :inner_result
           end
@@ -59,8 +60,8 @@ RSpec.shared_examples "storage transaction boundaries" do
           :outer_result
         end
         expect(result).to eq(:outer_result)
-        expect(persistence.contents.exist?(outer_id)).to be(true)
-        expect(persistence.contents.exist?(inner_id)).to be(true)
+        expect(stores.agent.contents.exist?(outer_id)).to be(true)
+        expect(stores.agent.contents.exist?(inner_id)).to be(true)
       end
 
       it "rolls back successful inner writes when the outer scope fails" do
@@ -68,7 +69,7 @@ RSpec.shared_examples "storage transaction boundaries" do
         expect do
           transaction_service.transaction do |outer|
             outer_id = transaction_contents(outer).put_text("outer-#{SecureRandom.uuid}")
-            result = transaction_service.transaction do |inner|
+            result = transaction_service.transaction do |inner, scope|
               inner_id = transaction_contents(inner).put_text("inner-#{SecureRandom.uuid}")
               :inner_result
             end
@@ -77,8 +78,8 @@ RSpec.shared_examples "storage transaction boundaries" do
             raise "outer failure"
           end
         end.to raise_error("outer failure")
-        expect(persistence.contents.exist?(outer_id)).to be(false)
-        expect(persistence.contents.exist?(inner_id)).to be(false)
+        expect(stores.agent.contents.exist?(outer_id)).to be(false)
+        expect(stores.agent.contents.exist?(inner_id)).to be(false)
       end
 
       it "rolls back both scopes when an inner error escapes the outer scope" do
@@ -86,20 +87,20 @@ RSpec.shared_examples "storage transaction boundaries" do
         expect do
           transaction_service.transaction do |outer|
             outer_id = transaction_contents(outer).put_text("outer-#{SecureRandom.uuid}")
-            transaction_service.transaction do |inner|
+            transaction_service.transaction do |inner, scope|
               inner_id = transaction_contents(inner).put_text("inner-#{SecureRandom.uuid}")
               raise "uncaught inner failure"
             end
           end
         end.to raise_error("uncaught inner failure")
-        expect(persistence.contents.exist?(outer_id)).to be(false)
-        expect(persistence.contents.exist?(inner_id)).to be(false)
+        expect(stores.agent.contents.exist?(outer_id)).to be(false)
+        expect(stores.agent.contents.exist?(inner_id)).to be(false)
       end
     end
   end
 
   it "validates every stream entry before writing any part of a batch" do
-    backend = persistence.backend
+    backend = stores.coordinator.backend
     schema = Phronomy::Agent::Persistence::StorageSchema
     owner_id = "batch-#{SecureRandom.uuid}"
     record = Phronomy::Storage::DurableRecord.new(record_type: "opaque.transaction", format_version: "0.1", payload: {})
@@ -107,14 +108,14 @@ RSpec.shared_examples "storage transaction boundaries" do
     valid = Phronomy::Storage::Entry::Append.new(id: "first", record: record)
     content_id = nil
     backend.transaction do |view|
-      content_id = persistence.contents.put_text("retained-#{owner_id}")
+      content_id = stores.agent.contents.put_text("retained-#{owner_id}")
       stream = view.streams(schema::JOURNAL)
       expect { stream.append(stream: owner_id, expected_head: 0, entries: [valid, Object.new]) }
         .to raise_error(Phronomy::Storage::SerializationError)
       expect(stream.head(stream: owner_id)).to eq(0)
       expect(stream.read(stream: owner_id)).to be_empty
     end
-    expect(persistence.contents.exist?(content_id)).to be(true)
+    expect(stores.agent.contents.exist?(content_id)).to be(true)
     entries = backend.view.streams(schema::JOURNAL).append(stream: owner_id, expected_head: 0,
       entries: [valid, Phronomy::Storage::Entry::Append.new(id: "second", record: record)])
     expect(entries.map(&:position)).to eq([1, 2])

data/lib/phronomy/tool/authorization.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Common authorization framework. Requests implement the Tool request protocol;
+    # callers attach their own immutable identity context, never a live owner.
+    module Authorization
+      VALID_DECISIONS = %i[allow require_approval reject].freeze
+      Decision = Data.define(:decision, :facts, :reason)
+
+      def self.call(request:, arguments:, context:, facts: nil, requirement: false, policy: nil)
+        value = facts&.call(arguments, context)
+        unless value.nil? || value.is_a?(Hash)
+          raise Phronomy::ConfigurationError, "approval_facts must return a Hash or nil (got #{value.class})"
+        end
+        value = snapshot(value || {})
+        request = request.with(facts: value)
+        required = requirement.respond_to?(:call) ? requirement.call(request) : requirement
+        default = case required
+        when true then :require_approval
+        when false, nil then :allow
+        else
+          raise Phronomy::ConfigurationError,
+            "requires_approval callable must return true or false (got #{required.inspect})"
+        end
+        request = request.with(default_decision: default)
+        decision = policy ? policy.call(request) : default
+        decision = decision.to_sym if decision.respond_to?(:to_sym)
+        unless VALID_DECISIONS.include?(decision)
+          raise Phronomy::ConfigurationError,
+            "tool_approval_policy must return :allow, :require_approval, or :reject (got #{decision.inspect})"
+        end
+        reason = if decision == :require_approval
+          (request.origin == :mcp) ? "MCP Tool execution requires approval" : "Tool execution requires approval"
+        end
+        Decision.new(decision: decision, facts: value, reason: reason)
+      end
+
+      def self.snapshot(value)
+        if phronomy_managed_live_domain_object?(value)
+          raise Phronomy::ConfigurationError,
+            "authorization worker snapshot cannot contain Phronomy-managed live " \
+            "domain object #{value.class}"
+        end
+
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, item), result|
+            result[snapshot(key)] = snapshot(item)
+          end.freeze
+        when Array
+          value.map { |item| snapshot(item) }.freeze
+        when String
+          value.dup.freeze
+        else
+          # Application-defined opaque objects are permitted by ACS-11 and remain
+          # Application-owned. A stricter general value-type protocol is deferred.
+          value
+        end
+      end
+
+      def self.phronomy_managed_live_domain_object?(value)
+        value.is_a?(Phronomy::Concurrency::WorkerInputRestricted)
+      end
+      private_class_method :phronomy_managed_live_domain_object?
+
+      def self.behavior(value, name)
+        return value if value.nil? || value == true || value == false
+        if phronomy_managed_live_domain_object?(value)
+          raise Phronomy::ConfigurationError,
+            "#{name} must not be a Phronomy-managed live domain object (got #{value.class})"
+        end
+        value
+      end
+    end
+  end
+end