phronomy 0.25.0 → 0.27.0

data/lib/phronomy.rb

@@ -2,12 +2,13 @@
 
 require "zeitwerk"
 require "ruby_llm"
-require_relative "phronomy/ruby_llm_patches"
+require_relative "phronomy/version"
 
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("rag" => "RAG")
 loader.inflector.inflect("fsm_session" => "FSMSession")
+loader.inflector.inflect("fsm_protocol" => "FSMProtocol")
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 loader.inflector.inflect("llm_operation_result" => "LLMOperationResult")
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
@@ -18,104 +19,61 @@ loader.inflector.inflect("llm_input_manifest" => "LLMInputManifest")
 loader.inflector.inflect("llm_input_build_context" => "LLMInputBuildContext")
 loader.inflector.inflect("llm_input_patch" => "LLMInputPatch")
 loader.inflector.inflect("before_llm_input" => "BeforeLLMInput")
-loader.collapse("#{__dir__}/phronomy/engine")
-# Loaded via require_relative before loader.setup; ignore to avoid Zeitwerk constant-name mismatch.
-loader.ignore("#{__dir__}/phronomy/ruby_llm_patches.rb")
-# Persistence backend conformance tests are explicit test support. Keep them out
-# of production eager-load so ordinary `require "phronomy"` never requires RSpec.
+# These responsibility directories do not add a public Ruby namespace.
+%w[common configuration engine generation llm_contract recovery].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/#{directory}")
+end
+# Agent responsibility directories retain the existing Agent constant names.
+%w[
+  context_contract lifecycle execution tool_execution context_assembly
+  journal handoff recovery
+].each do |directory|
+  loader.collapse("#{__dir__}/phronomy/agent/#{directory}")
+end
+
+# A nested root is independent of its enclosing Ruby namespace. Keep existing
+# Phronomy::Workflow, Phronomy::WorkflowContext, and other canonical constants
+# beside the feature they belong to, without aliases or a new partial-load API.
+%w[
+  agent/api
+  agent/lifecycle_contract
+  filter/contract
+  output_parser/contract
+  persistence/api
+  tool/contract
+  workflow/execution
+  workflow/storage_contract
+  multi_agent/storage_contract
+].each do |directory|
+  loader.push_dir("#{__dir__}/phronomy/#{directory}", namespace: Phronomy)
+end
+
+# These files wire composition, reopen namespaces, or patch a dependency.
+loader.ignore(
+  "#{__dir__}/phronomy/configuration/global_configuration.rb",
+  "#{__dir__}/phronomy/agent/composition",
+  "#{__dir__}/phronomy/runtime_composition/agent_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/configuration_defaults.rb",
+  "#{__dir__}/phronomy/runtime_composition/global_runtime.rb"
+)
+# Persistence conformance support must never make production loading require RSpec.
 loader.ignore(
   "#{__dir__}/phronomy/testing/persistence_contract.rb",
   "#{__dir__}/phronomy/testing/persistence_contract"
 )
 loader.setup
 
-require_relative "phronomy/version"
-require_relative "phronomy/token_usage"
-
-module Phronomy
-  class Error < StandardError; end
-  class ParseError < Error; end
-  class RecursionLimitError < Error; end
-  class ToolError < Error; end
-  class TimeoutError < Error; end
-  class ConfigurationError < Error; end
-  class HandoffError < Error; end
-
-  class TransportError < Error; end
-  class RateLimitError < TransportError; end
-  class AuthenticationError < TransportError; end
-  class ContextLengthError < Error; end
-  class CancellationError < Error; end
-
-  # Raised when a synchronous API would block the EventLoop control thread.
-  class EventLoopReentrancyError < Error; end
-
-  # Backward-compatible error class name for callers that still rescue the old
-  # scheduler-oriented exception. New code should use EventLoopReentrancyError.
-  class SchedulerReentrancyError < EventLoopReentrancyError; end
+require_relative "phronomy/runtime_composition/configuration_defaults"
+require_relative "phronomy/llm_contract/token_usage"
+require_relative "phronomy/configuration/global_configuration"
+require_relative "phronomy/runtime_composition/global_runtime"
 
-  class RuntimeShutdownError < Error; end
-  class RuntimeShutdownReentrancyError < RuntimeShutdownError; end
-
-  class LowConfidenceError < Error
-    attr_reader :result
-
-    def initialize(result)
-      @result = result
-      super("Answer confidence #{result.confidence} is below the required threshold")
-    end
-  end
-
-  class FilterBlockError < Error
-    attr_reader :filter
-
-    def initialize(message, filter: nil)
-      super(message)
-      @filter = filter
-    end
-  end
-
-  class PoolShutdownError < Error; end
-  class BackpressureError < Error; end
-
-  class WorkflowContextOwnershipError < Error; end
-
-  class << self
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    def configure
-      yield configuration
-    end
-
-    def reset_configuration!
-      @configuration = Configuration.new
-    end
-
-    def with_configuration
-      original = @configuration&.dup
-      yield configuration
-    ensure
-      @configuration = original
-    end
-
-    def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
-      previous_grace = @configuration&.event_loop_stop_grace_seconds
-      result = Runtime.reset_default!(timeout: timeout)
-
-      new_configuration = Configuration.new
-      if previous_grace
-        new_configuration.event_loop_stop_grace_seconds = previous_grace
-      end
-      @configuration = new_configuration
-      result
-    end
-  end
-end
+# Explicitly install the Agent namespace extensions even if its factory
+# contract was loaded first. Composition owns both concrete binding and the
+# run_once method definition; neither is required from Agent execution files.
+require_relative "phronomy/agent/api/agent"
+require_relative "phronomy/runtime_composition/agent_defaults"
+require_relative "phronomy/agent/composition/run_once"
 
-# Shared Recovery primitives and Workflow Persistence F1 reconciliation.
-# Entity-specific Agent Recovery is loaded from lib/phronomy/agent.rb when the
-# Agent namespace is materialized.
-require_relative "phronomy/recovery"
-require_relative "phronomy/workflow_recovery"
+# Load the common recovery vocabulary during ordinary application loading.
+require_relative "phronomy/recovery/recovery"

data/scripts/api_snapshot.rb

@@ -36,7 +36,7 @@ PUBLIC_API_ENTRIES = [
   # Beta
   Phronomy::Agent::Handoff,
   Phronomy::Agent::HandoffPolicy,
-  Phronomy::Agent::HandoffRunner,
+  Phronomy::MultiAgent::HandoffRunner,
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Filter::Base,
@@ -70,7 +70,9 @@ def snapshot_entry(klass)
       "public_instance_methods" => own_methods
     }
   else
-    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS).sort
+    internal_context_methods = (klass == Phronomy::InvocationContext) ?
+      %i[__bind_execution __execution_scope] : []
+    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS - internal_context_methods).sort
     class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
     {
       "name" => klass.name,

data/scripts/storage_spi_snapshot.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/phronomy"
+
+# Explicit SPI 2 scope, independent of the Stable/Beta product API snapshot.
+# Private dispatch and domain composition helpers are deliberately excluded.
+surfaces = {
+  Phronomy::Persistence => Phronomy::Persistence.public_instance_methods(false).sort,
+  Phronomy::Storage::Backend => %i[initialize capabilities transaction resources view],
+  Phronomy::Storage::Backends::InMemory => %i[initialize capabilities],
+  Phronomy::Storage::View => %i[records streams blobs check!],
+  Phronomy::Storage::Resource => %i[initialize id kind attributes immutable_attributes indexes unique guard validate_attributes index_values],
+  Phronomy::Storage::Records => %i[resource insert read fetch replace delete scan delete_matching],
+  Phronomy::Storage::Streams => %i[resource append read head delete],
+  Phronomy::Storage::Blobs => %i[resource put_if_absent fetch exist?],
+  Phronomy::Storage::GuardRef => %i[initialize resource key],
+  Phronomy::Storage::Condition::RevisionIs => %i[initialize resource key expected],
+  Phronomy::Storage::Condition::StreamHeadIs => %i[initialize resource stream expected],
+  Phronomy::Storage::Condition::NoRows => %i[initialize resource index equals],
+  Phronomy::Storage::Entry::Record => %i[initialize key revision attributes record],
+  Phronomy::Storage::Entry::Stream => %i[initialize position id record],
+  Phronomy::Storage::Entry::Append => %i[initialize id record],
+  Phronomy::Storage::Entry::Blob => %i[initialize key bytes attributes],
+  Phronomy::Storage::UniqueConstraintError => %i[initialize resource constraint],
+  Phronomy::Storage::ConditionFailedError => %i[initialize condition]
+}
+snapshot = {spi_version: 2, capabilities: Phronomy::Storage::Backend::REQUIRED_CAPABILITIES,
+            surfaces: surfaces.to_h { |type, names| [type.name, names.sort.to_h { |name| [name, type.instance_method(name).parameters] }] }}
+json = JSON.pretty_generate(snapshot) + "\n"
+if ARGV.include?("--write")
+  File.write(File.expand_path("../spec/fixtures/storage_spi_v2_snapshot.json", __dir__), json)
+else
+  puts json
+end

data/sig/phronomy/agent.rbs

@@ -190,7 +190,6 @@ module Phronomy
       def self.max_iterations: (?Integer value) -> Integer
       def self.cache_instructions: (?bool enabled) -> bool?
       def self.max_output_tokens: (?Integer value) -> Integer?
-      def self.context_window: (?Integer value) -> Integer?
       def self.context_policy: () -> ContextPolicy
                              | (ContextPolicy policy) -> ContextPolicy
       def self.agent_definition: () -> Hash[Symbol, untyped]
@@ -213,18 +212,18 @@ module Phronomy
       # Public operation methods no longer accept per-invocation event listeners
       # or event-listener blocks.
       def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
-      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[Hash[Symbol, untyped]]
+      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[Hash[Symbol, untyped]]
       def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
-      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[Hash[Symbol, untyped]]
+      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[Hash[Symbol, untyped]]
 
       def approve: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> untyped
-      def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> Task[untyped]
+      def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> TaskResult[untyped]
 
       # Resolves a factual Recovery ambiguity. result: is meaningful for
       # :succeeded; error: is required for :failed; neither is used by
       # :not_performed.
       def resolve: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> untyped
-      def resolve_async: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> Task[untyped]
+      def resolve_async: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> TaskResult[untyped]
 
       def transcript: () -> Array[untyped]
       def add_knowledge: (untyped content, ?metadata: Hash[untyped, untyped]) -> self

data/sig/phronomy/execution_receiver.rbs

@@ -0,0 +1,34 @@
+module Phronomy
+  # Internal Engine contract (ADR-042); not an application extension SPI.
+  class ExecutionReceiver
+    def self.for: (EventLoop event_loop) -> instance
+    def self.existing_for: (Runtime runtime) -> instance?
+    def initialize: (event_loop: EventLoop) -> void
+    def __bound_to?: (EventLoop event_loop) -> bool
+    def idle?: () -> bool
+    def deliver: (untyped message) -> untyped
+    def shutdown: (error: Exception?) -> untyped
+    def session_retired: (String fsm_session_id, reason: Symbol) -> untyped
+
+    private
+
+    def synchronize: [V] () { () -> V } -> V
+    def admit: [V] () { () -> V } -> V
+    def post_message: (untyped message, ?admission: bool, ?completion: TaskResult[untyped]?) -> bool
+    def assert_event_loop_thread!: () -> void
+  end
+
+  class EventLoop
+    def __execution_receiver: (key: untyped) -> ExecutionReceiver?
+    def __register_execution_receiver: (key: untyped, receiver: ExecutionReceiver) -> ExecutionReceiver
+    def __synchronize_execution_state: [V] () { () -> V } -> V
+    def __admit_execution: [V] (ExecutionReceiver receiver) { () -> V } -> V
+    def __post_execution: (ExecutionReceiver receiver, untyped message, ?admission: bool, ?completion: TaskResult[untyped]?) -> bool
+    def __route_execution_event: (ExecutionReceiver receiver) { () -> untyped } -> bool
+    def __receiver_cleanup_complete?: () -> bool
+  end
+
+  class Runtime
+    def __event_loop_if_initialized: () -> EventLoop?
+  end
+end

data/sig/phronomy/extensions.rbs

@@ -28,16 +28,16 @@ module Phronomy
       def clear: () -> untyped
       def size: () -> Integer
 
-      def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
-      def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[Array[Hash[Symbol, untyped]]]
-      def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
-      def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+      def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
+      def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[Array[Hash[Symbol, untyped]]]
+      def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
+      def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
     end
 
     module Embeddings
       class Base
         def embed: (String text, ?Concurrency::CancellationToken? cancellation_token) -> Array[Float]
-        def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> Task[Array[Float]]
+        def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> TaskResult[Array[Float]]
       end
     end
   end

data/sig/phronomy/handoff.rbs

@@ -25,14 +25,16 @@ module Phronomy
       def selectable_categories: () -> Array[Symbol]
       def to_h: () -> Hash[String, Hash[String, String]]
     end
+  end
 
+  module MultiAgent
     class HandoffRunner
       MAX_HANDOFFS: Integer
 
       attr_reader main_agent: ::Phronomy::Agent::Base
-      attr_reader handoffs: Array[Handoff]
+      attr_reader handoffs: Array[::Phronomy::Agent::Handoff]
 
-      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[Handoff]) -> void
+      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[::Phronomy::Agent::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]

data/sig/phronomy/multi_agent.rbs

@@ -1,13 +1,29 @@
 module Phronomy
   module MultiAgent
+    class SharedState
+      class KnowledgeStore
+        def self.new: () -> instance
+        def read_all: () -> Array[Hash[Symbol, untyped]]
+        def write: (agent: untyped, content: untyped, cycle: untyped) -> nil
+        def size: () -> Integer
+      end
+
+      def self.new: () -> instance
+      def self.member: (singleton(::Phronomy::Agent::Base) klass, ?instruction: untyped) -> Array[Hash[Symbol, untyped]]
+      def self.coordination: (?untyped text) -> untyped
+      def self.max_cycles: (?untyped value) -> Integer?
+      def self.timeout: (?untyped value) -> Float?
+      def self.terminate_when: () ?{ (KnowledgeStore) -> untyped } -> untyped
+      def self.aggregate: () ?{ (KnowledgeStore) -> untyped } -> untyped
+      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    end
+
     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]
+      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::TaskResult[untyped]
     end
 
     class TeamCoordinator

data/sig/phronomy/persistence.rbs

@@ -1,10 +1,4 @@
 module Phronomy
-  interface _ContentRepository
-    def put: (String bytes, canonicalization_version: untyped) -> String
-    def fetch: (String content_id) -> String
-    def exist?: (String content_id) -> bool
-  end
-
   # Runtime/domain-facing repository interfaces.
   interface _AgentRepository
     def create: (untyped root) -> untyped
@@ -40,37 +34,6 @@ module Phronomy
   # Backend-side record repository interfaces. DurableRecord is the opaque data
   # carrier. Identity/revision/index metadata is passed separately so backends do
   # not need to interpret DurableRecord#payload.
-  interface _BackendAgentRecordRepository
-    def create: (agent_id: String, agent_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
-    def load: (String agent_id) -> Persistence::DurableRecord
-    def save: (String agent_id, expected_revision: Integer, next_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
-    def delete: (String agent_id) -> untyped
-  end
-
-  interface _BackendJournalRecordRepository
-    def append: (String agent_id, expected_position: Integer, records: Array[Persistence::DurableRecord], record_ids: Array[String]) -> Array[Persistence::DurableRecord]
-    def read: (String agent_id, ?after: Integer?, ?limit: Integer?) -> Array[Persistence::DurableRecord]
-    def head: (String agent_id) -> Integer
-    def delete: (String agent_id) -> untyped
-  end
-
-  interface _BackendExecutionRecordRepository
-    def create_active: (execution_id: String, agent_id: String, execution_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
-    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
-  end
-
-  interface _BackendWorkflowStateRecordRepository
-    def load: (String workflow_instance_id) -> Persistence::DurableRecord?
-    def save: (String workflow_instance_id, expected_revision: Integer?, next_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
-    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
@@ -95,34 +58,6 @@ module Phronomy
     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
-
   interface _PersistenceTransactionView
     def contents: () -> _ContentRepository
     def agents: () -> _AgentRepository
@@ -136,36 +71,16 @@ module Phronomy
   end
 
   class Persistence
-    class ConflictError < Phronomy::Error
-    end
-    class NotFoundError < Phronomy::Error
-    end
-    class UnsupportedBackendError < Phronomy::Error
-    end
-    class SerializationError < Phronomy::Error
-    end
-
-    class DurableRecord
-      FORMAT_VERSION_PATTERN: Regexp
-      attr_reader record_type: String
-      attr_reader format_version: String
-      attr_reader payload: Hash[String, untyped]
-      def initialize: (record_type: String, format_version: String, payload: Hash[String, untyped]) -> void
-      def copy: () -> DurableRecord
-    end
-
     module Migration
       module InitialFormatMigration
-        def self.agent_root: (Hash[untyped, untyped] hash) -> DurableRecord
-        def self.agent_execution: (Hash[untyped, untyped] hash) -> DurableRecord
-        def self.journal_record: (Hash[untyped, untyped] hash) -> DurableRecord
-        def self.workflow_state: (workflow_instance_id: String, revision: Integer, snapshot: Hash[untyped, untyped]) -> DurableRecord
+        def self.agent_root: (Hash[untyped, untyped] hash) -> Storage::DurableRecord
+        def self.agent_execution: (Hash[untyped, untyped] hash) -> Storage::DurableRecord
+        def self.journal_record: (Hash[untyped, untyped] hash) -> Storage::DurableRecord
+        def self.workflow_state: (workflow_instance_id: String, revision: Integer, snapshot: Hash[untyped, untyped]) -> Storage::DurableRecord
         def self.llm_input_manifest: (Hash[untyped, untyped] hash) -> Hash[String, untyped]
       end
     end
 
-    REQUIRED_CAPABILITIES: Hash[Symbol, bool]
-
     attr_reader contents: _ContentRepository
     attr_reader agents: _AgentRepository
     attr_reader journals: _JournalRepository
@@ -180,10 +95,11 @@ module Phronomy
     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
+    attr_reader backend: _StorageBackend
+    def initialize: (backend: _StorageBackend) -> void
+    def self.in_memory: () -> Persistence
     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, 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

data/sig/phronomy/runtime.rbs

@@ -1,17 +1,44 @@
 module Phronomy
-  class Task[A]
-    def self.completed: [V] (V value, ?name: String?) -> Task[V]
-                      | (?name: String?) -> Task[nil]
-    def self.failed: (Exception error, ?name: String?) -> Task[untyped]
+  class TaskResult[A]
+    class Outcome[V]
+      attr_reader index: Integer
+      attr_reader status: (:completed | :failed | :cancelled | :unfinished)
+      attr_reader value: V?
+      attr_reader error: Exception?
+    end
+
+    def self.completed: [V] (V value, ?name: String?) -> TaskResult[V]
+                      | (?name: String?) -> TaskResult[nil]
+    def self.failed: (Exception error, ?name: String?) -> TaskResult[untyped]
+    def self.all_settled: [V] (Array[TaskResult[V]] results) -> TaskResult[Array[Outcome[V]]]
     attr_reader name: String?
-    attr_reader parent: Task[untyped]?
+    attr_reader parent: TaskResult[untyped]?
 
     def status: () -> (:pending | :completed | :failed | :cancelled)
     def done?: () -> bool
     def alive?: () -> bool
     def wait_result: (?timeout: Numeric?) -> A
     def on_complete: () { (A?, Exception?) -> void } -> self
-    def map: [B] () { (A) -> B } -> Task[B]
+    def map: [B] () { (A) -> B } -> TaskResult[B]
+    def flat_map: [B] () { (A) -> TaskResult[B] } -> TaskResult[B]
+  end
+
+  class Execution
+    attr_reader invocation_context: InvocationContext
+
+    def self.run_async: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> TaskResult[Array[TaskResult::Outcome[V]]]
+    def self.run: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> Array[TaskResult::Outcome[V]]
+    def observe: [V] (TaskResult[V] source_result) -> TaskResult[V]
+  end
+
+  class ExecutionTimeoutError < TimeoutError
+    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
+  end
+
+  class ExecutionCancellationError < CancellationError
+    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
   end
 
   module Concurrency
@@ -44,6 +71,6 @@ end
 
 module Phronomy
   module Blocking
-    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?) { () -> V } -> Task[V]
+    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { () -> V } -> TaskResult[V]
   end
 end