phronomy 0.27.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '095ac1376e77f34201dceeafec7dc114340aa2cae7cd8f1bb2bb7c2552e64e87'
-  data.tar.gz: 4d900c3bdc20e3fb0210046daffc4d78d1b990f118281c04037cc45beca2d699
+  metadata.gz: 6ee0a6e2cc02a9014a1f6b4b0587474255697960b0e1589070a7846d038452ad
+  data.tar.gz: eb866c788b4dbaf5c560ec0a6a9fe1ef641d630932c7f4309c5ca0741dce2ad0
 SHA512:
-  metadata.gz: 3108c48424885f72ea256e6c7cd7dfa8a7230647727f288f9fce840ee9309a51b523e64748663a7d1341e88b0c05cfe5432cb91a521039b16f28b0e2c14a4714
-  data.tar.gz: 51795e8c019cb92d8a17eadb864b726f9359ed1c963b06acfb52cb7440b99234755ad2c7e169a5afb8e5958ea45b99635d9035eea4d3c4ceb84ac4d554fdc814
+  metadata.gz: a4970e936adca3d87ee8a8a18469630a563df8fb8a07f06796f4a4bfcae3b1e97b67a51869fdbb68760892201deb12f5f765c082cdfe8559c5f6d0c5ad10dd1a
+  data.tar.gz: 10c461ef9e86a476cc73020dc1167d6b80564f02f47c3da0161a7da8a34953be96efa236ebcfdf938c7b8a5bfeb2ea6ad3fdaca137d6f70cd5238a71bd6cb829

data/.mutant.yml

@@ -9,14 +9,14 @@ matcher:
   subjects:
     - Phronomy::WorkflowContext
     - Phronomy::WorkflowRunner
-    # Phronomy::Tool::Base is a public constant alias to this same Class object.
-    # Use the implementation canonical name returned by Class#name for Mutant.
-    - Phronomy::Agent::Context::Capability::Base
+    - Phronomy::Tool::Base
+    - Phronomy::Tool::Schema
     - Phronomy::LlmContextWindow::TokenBudget
-    - Phronomy::Agent::ContextAssembler
-    - Phronomy::Agent::ContextPolicies::Default
-    - Phronomy::Agent::ContextPolicyInputBuilder
-    - Phronomy::Agent::ContextPlanValidator
-    - Phronomy::Agent::HandoffPolicy
-    - Phronomy::Agent::HandoffProjection
+    - Phronomy::Context::Assembly
+    - Phronomy::Agent::ContextPreparation
+    - Phronomy::Context::DefaultPolicy
+    - Phronomy::Context::ContextPolicyInputBuilder
+    - Phronomy::Context::ContextPlanValidator
+    - Phronomy::MultiAgent::HandoffPolicy
+    - Phronomy::Agent::TransferProjection
     - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -12,6 +12,58 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+### r8 first implementation unit (breaking, unreleased)
+
+- Move Context policy/plan/manifest/budget/prompt operations into `Phronomy::Context`.
+  Agent retains snapshot, journal and lifecycle ownership. Manifest and execution
+  references remain written within the same transaction.
+- Make `Tool::Base` the actual implementation; move common definition and
+  authorization operations into Tool. Remove the old Agent Context namespace.
+- Move chat construction and SDK failure translation into the LLM adapter.
+  Custom synchronous adapters must implement the expanded construction SPI.
+- Unite execution contracts and services in `execution/`; move FSM values and
+  scheduling bindings to Engine, observation to Tracing. Keep result/control
+  rules independent of Engine startup. Update Ruby/RBS analysis and diagrams.
+- Remove empty contract-only subdivisions and old API aliases. This unit does
+  not complete r8 Persistence, parent admission or all domain FSM separation.
+  See [the scope and migration report](docs/architecture/r8-unit1.md).
+
+### Changed
+
+- Add public Beta `Storage::AsyncClient#transaction_async` and route 16 existing
+  durable Agent/Workflow/coordination execution units through its private submit
+  boundary. Preserve transaction/savepoint, result reconciliation and admission
+  policy; do not add cancellation or timeout to existing terminal writes.
+- Move StoredContents into `content_store/backends/` without changing its
+  constant or behavior. Complete P4; see the
+  [Storage client guide](docs/migrations/storage-async-client.md).
+- Preserve transparent text panels and module outlines in generated diagrams.
+  Hide arrows into M33/M41/M44 as a display choice; keep their measured source
+  dependencies, evidence and complete matrix.
+
+- **Beta API receiver migration:** move VectorStore `add_async`, `search_async`,
+  `remove_async`, `clear_async` and Embeddings `embed_async` onto the public
+  feature-specific `AsyncClient` objects. Synchronous backend methods and
+  concrete class names remain unchanged. Remove the inherited async methods
+  and `VectorStore::AsyncBackend`; see the
+  [migration guide](docs/migrations/vector-async-clients.md).
+- Split VectorStore/Embeddings implementations into collapsed `backends/`
+  directories. Synchronous RBS uses structural cancellation; separate client
+  signatures retain TaskResult and the full execution token. Complete P3 and
+  remove the remaining backend-to-Engine edges from the measured graph.
+
+- Separate the synchronous LLMAdapter SPI, RubyLLM implementation and internal
+  AsyncClient. Adapter authors implement only `complete` and `stream`; default
+  configuration, provider behavior, admission/cancellation and Agent event
+  delivery remain unchanged. See
+  [ADR-059](docs/decisions/059-backend-contracts-and-async-clients.md).
+- Separate responsibility groups from the diagram's B1-B6 display layers. Add
+  the source-derived SVG/matrix generator and Architecture CI boundary gate;
+  retain individual module boxes, stable module IDs and the earlier horizontal
+  layer layout with topical columns. Separated Contracts belong in B5 beside
+  the independent Engine group; clients, implementations and pending mixed
+  backends are displayed in B4. Storage/ContentStore migration remains pending.
+
 ---
 
 ## [0.27.0] - 2026-09-24

data/CONTRIBUTING.md

@@ -219,14 +219,14 @@ The authoritative subject list is `.mutant.yml`. It currently includes:
 
 - `Phronomy::WorkflowContext`
 - `Phronomy::WorkflowRunner`
-- `Phronomy::Agent::Context::Capability::Base`
+- `Phronomy::Tool::Base`
 - `Phronomy::LlmContextWindow::TokenBudget`
-- `Phronomy::Agent::ContextAssembler`
-- `Phronomy::Agent::ContextPolicies::Default`
-- `Phronomy::Agent::ContextPolicyInputBuilder`
-- `Phronomy::Agent::ContextPlanValidator`
-- `Phronomy::Agent::HandoffPolicy`
-- `Phronomy::Agent::HandoffProjection`
+- `Phronomy::Agent::ContextPreparation`
+- `Phronomy::Context::DefaultPolicy`
+- `Phronomy::Context::ContextPolicyInputBuilder`
+- `Phronomy::Context::ContextPlanValidator`
+- `Phronomy::MultiAgent::HandoffPolicy`
+- `Phronomy::Agent::TransferProjection`
 - `Phronomy::VectorStore::InMemory`
 
 The nightly mutation matrix mirrors this authoritative list so each subject can
@@ -235,7 +235,7 @@ configuration-consistency guard that fails if the nightly subject set diverges
 from `.mutant.yml`.
 
 The Tool mutation subject intentionally uses
-`Phronomy::Agent::Context::Capability::Base`, which is the implementation
+`Phronomy::Tool::Base`, which is the implementation
 canonical name returned by the single Class object's runtime `Class#name`.
 `Phronomy::Tool::Base` is the public facade constant alias to that same Class
 object; it is not a second Tool base class.

data/README.md

@@ -8,7 +8,11 @@
 
 **Phronomy** is a Ruby AI agent framework for stateful Agents, Workflows, Tools,
 context management, filtering, tracing, and multi-agent coordination. Large Language
-Model (LLM) access is provided through [RubyLLM](https://github.com/crmne/ruby_llm).
+Model (LLM) operations use `Phronomy::LLMAdapter`; the default backend uses
+[RubyLLM](https://github.com/crmne/ruby_llm). Custom backends implement the
+[SDK-independent LLM contract](docs/migrations/r8-unit6.md).
+Tool declarations and argument validation belong to `Phronomy::Tool`, independently
+of the selected LLM backend.
 
 Phronomy is pre-1.0. Pin to a released gem version for production use rather than
 tracking `main` directly.
@@ -16,8 +20,8 @@ tracking `main` directly.
 ## Core concepts
 
 - **Agent** — stateful, persistence-backed LLM agent with canonical execution history.
-- **Persistence** — unified durable backend for Agent state and Workflow `workflow_states`.
-- **Workflow** — state-machine-driven application workflow with explicit events and wait states.
+- **Persistence** — shared atomic scopes with domain-owned Agent/Team stores and Workflow checkpoints.
+- **Workflow** — state-machine-driven application workflow with task states, explicit events and wait states.
 - **Tool / Capability** — callable application capability exposed to an Agent; application-defined Tools subclass `Phronomy::Tool::Base`.
 - **Multi-Agent Handoff** — semantic Source-to-Target responsibility transfer with policy-bounded Context projection and persisted active responsibility and exact Target recovery within one Persistence domain.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
@@ -31,6 +35,19 @@ tracking `main` directly.
 
 See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
 
+The following application APIs are part of unreleased development:
+
+| API | Stability | Contract |
+|---|---|---|
+| `Agent.open_scope`, `Agent::Scope`, `Agent::Base#unload_async / #unload!`, `AgentUnloadedError` and `Agent::ScopeCleanupError` | Beta | Runtime-bound ownership and safe release of idle Agent incarnations without changing saved history or closing the Store; [contract](docs/architecture/dx05-agent-scope.md) |
+| `Workflow::Builder#task_state` and `WorkflowTaskResumeError` | Beta | State-entry-scoped Task completion, live cancellation and explicit restart rejection; [contract](docs/architecture/dx05-workflow-task-state.md) |
+| `Phronomy::Integrations::OrderedEventDelivery` | Beta | Optional ordered delivery with bounded admission and explicit drain lifetime; [usage](docs/ordered-event-delivery.md) |
+| `Phronomy::Error#code` and error constructor `code:` | Beta | Optional reason codes and bounded causes retained in saved failure diagnostics; [meaning and compatibility](docs/architecture/error-api-review.md) |
+| `Phronomy::AgentNotFoundError#agent_id` | Beta | Identifies absence of the requested Agent root; referenced history and Content failures retain their own errors; [migration](docs/architecture/error-api-review.md) |
+| `Phronomy::MultiAgent::TeamNotFoundError` and `TeamBusyError`, with `team_id` | Beta | Team-owned absence and busy errors; child Agent failures retain their Agent classification; [migration](docs/architecture/error-api-review.md) |
+| `Phronomy::Embeddings::AuthenticationError` and `RateLimitError` | Beta | Embeddings-owned transport error subclasses retaining the provider cause; [migration](docs/architecture/error-api-review.md) |
+| `Phronomy::Tracing::Base.trace_with` | Beta | Uses the tracer start/finish SPI, attempts finish once, and preserves a primary application error; [contract](docs/architecture/error-api-review.md) |
+
 ## Installation
 
 Add Phronomy to your Gemfile:
@@ -45,7 +62,10 @@ Then run:
 bundle install
 ```
 
-This refactoring branch requires RubyLLM 2.0.x. See the
+Phronomy 0.28 requires RubyLLM 2.0.x. Faraday 2.1.0 is the tested minimum
+supported version; the `~> 2.1` requirement allows versions from 2.1 up to,
+but excluding, 3.0. CI checks fresh dependency resolution and the exact minimum
+with MCP 1.0.0. See the
 [RubyLLM 2 and token-ownership migration](docs/architecture/rubyllm-2-token-ownership.md)
 for removed input-budget overrides and the in-flight Tool-manifest upgrade boundary.
 
@@ -87,9 +107,7 @@ result = ResearchAgent.new.invoke("What happened in AI research this week?")
 puts result[:output]
 ```
 
-`Phronomy::Tool::Base` is the public authoring name for the existing Tool base
-class. The legacy `Phronomy::Agent::Context::Capability::Base` constant remains
-valid for compatibility.
+`Phronomy::Tool::Base` is the public base class for application-defined Tools.
 
 For non-blocking top-level use, call `invoke_async` and keep the returned
 `Phronomy::TaskResult`. Inside Phronomy lifecycle callbacks, do not block waiting for
@@ -148,6 +166,7 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 ## Documentation
 
 - [Getting started](docs/getting-started.md) — installation, RubyLLM setup, Agent/Workflow basics, persistence, streaming.
+- [Application recipes](docs/application-recipes.md) — complete persistence, streaming, and Workflow examples, including explicit failure handling.
 - [Features and API stability](docs/features.md) — public feature matrix and stability labels.
 - [Architecture](docs/architecture.md) — canonical current explanatory architecture entry and authority navigation.
 - [Runtime and concurrency](docs/runtime-and-concurrency.md) — EventLoop, FSMSession, TaskResult, OffloadPool, cancellation, observability.
@@ -155,6 +174,8 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 - [MCP client](docs/mcp-client.md) — Model Context Protocol (MCP) integration and supported schema subset.
 - [Migration from 0.15-era APIs](docs/migrations/0.15.md).
 - [0.16 cleanup migration](docs/migrations/0.16.md).
+- [r8 persistence boundary migration](docs/architecture/r8-unit3.md) — domain stores, shared scopes, and removed facade APIs.
+- [Persistence failure contract migration](docs/migrations/persistence-failure-contracts.md) — domain rescue clauses and unchanged raw backend errors.
 - [0.19 unified Persistence migration](docs/migrations/0.19.md).
 - [0.22 semantic Multi-Agent Handoff migration](docs/migrations/0.22.md).
 - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.

data/benchmark/bench_agent_invoke.rb

@@ -19,49 +19,21 @@ require_relative "../lib/phronomy"
 # Shared stubs
 # ---------------------------------------------------------------------------
 
-module BenchAgentMessage
-  def self.assistant(content = "done")
-    RubyLLM::Message.new(
-      role: :assistant, content: content,
-      tokens: RubyLLM::Tokens.new(input: 5, output: 5, cache_read: 0, cache_write: 0)
-    )
-  end
-end
-
-# A minimal stub Chat that returns a pre-built response immediately.
-class BenchStubChat
-  attr_reader :messages
-
+# A stub backend that preserves the adapter's validation/cancellation template.
+class BenchStubLLMAdapter < Phronomy::LLMAdapter::Base
   def initialize(response)
     @response = response
-    @messages = []
-  end
-
-  def with_instructions(_, **_options) = self
-  def with_tools(*) = self
-  def with_temperature(_) = self
-  def with_cache_instructions(_) = self
-  def with_output_schema(_) = self
-  def last_message = @response
-
-  def after_message(&block)
-    @after_message = block
-    self
   end
 
-  def ask(_)
-    complete
-  end
+  protected
 
-  def complete
-    @messages << @response
-    @after_message&.call(@response)
+  def perform_complete(request, cancellation_token:)
     @response
   end
 end
 
 # A stub tool that does nothing but conforms to the Tool::Base interface.
-class BenchNullTool < Phronomy::Agent::Context::Capability::Base
+class BenchNullTool < Phronomy::Tool::Base
   description "No-op benchmark tool"
   param :x, type: :string, desc: "input"
 
@@ -74,38 +46,41 @@ end
 # Agent classes
 # ---------------------------------------------------------------------------
 
-BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
+BENCH_RESP = Phronomy::LLMAdapter::Response.new(
+  content: "benchmark complete",
+  usage: Phronomy::LLMAdapter::TokenUsage.new(input: 5, output: 5, cached: 0, cache_creation: 0)
+)
 
 bench_minimal_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-minimal", version: 1
   model "stub-model"
-
-  define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-tool", version: 1
   model "stub-model"
   tools(BenchNullTool => nil)
-
-  define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 AGENT_INVOKE_ITERATIONS = 200
-BENCH_AGENTS_MINIMAL = Array.new(AGENT_INVOKE_ITERATIONS) { bench_minimal_class.new }.freeze
-BENCH_AGENTS_TOOLS = Array.new(AGENT_INVOKE_ITERATIONS) { bench_tool_class.new }.freeze
-
-puts "=== bench_agent_invoke ==="
-Benchmark.bm(50) do |x|
-  x.report("Agent#invoke — fresh, no tools, #{AGENT_INVOKE_ITERATIONS} iters") do
-    BENCH_AGENTS_MINIMAL.each do |agent|
-      agent.invoke("ping")
+
+Phronomy.with_configuration do |config|
+  config.llm_adapter = BenchStubLLMAdapter.new(BENCH_RESP)
+  bench_agents_minimal = Array.new(AGENT_INVOKE_ITERATIONS) { bench_minimal_class.new }.freeze
+  bench_agents_tools = Array.new(AGENT_INVOKE_ITERATIONS) { bench_tool_class.new }.freeze
+
+  puts "=== bench_agent_invoke ==="
+  Benchmark.bm(50) do |x|
+    x.report("Agent#invoke — fresh, no tools, #{AGENT_INVOKE_ITERATIONS} iters") do
+      bench_agents_minimal.each do |agent|
+        agent.invoke("ping")
+      end
     end
-  end
 
-  x.report("Agent#invoke — fresh, tool-aware, #{AGENT_INVOKE_ITERATIONS} iters") do
-    BENCH_AGENTS_TOOLS.each do |agent|
-      agent.invoke("ping")
+    x.report("Agent#invoke — fresh, tool-aware, #{AGENT_INVOKE_ITERATIONS} iters") do
+      bench_agents_tools.each do |agent|
+        agent.invoke("ping")
+      end
     end
   end
 end

data/benchmark/bench_context_assembler.rb

@@ -14,7 +14,7 @@ module BenchContextAssembler
   module_function
 
   def provenance
-    Phronomy::Agent::ContextPolicyInput::Provenance.new(origin: :journal)
+    Phronomy::Context::ContextPolicyInput::Provenance.new(origin: :journal)
   end
 
   def policy_input(item_count)
@@ -22,13 +22,13 @@ module BenchContextAssembler
     conversation = []
     item_count.times do |index|
       if (index % 10).zero?
-        knowledge << Phronomy::Agent::ContextPolicyInput::KnowledgeItem.new(
+        knowledge << Phronomy::Context::ContextPolicyInput::KnowledgeItem.new(
           id: "knowledge-#{index}", kind: :knowledge, role: :user,
           content: "knowledge #{index}", content_format: :text,
           estimated_tokens: 8, required: false, provenance: provenance, metadata: {}
         )
       else
-        conversation << [Phronomy::Agent::ContextPolicyInput::ConversationItem.new(
+        conversation << [Phronomy::Context::ContextPolicyInput::ConversationItem.new(
           id: "message-#{index}", kind: :external_message, role: :user,
           content: "message #{index}", content_format: :text,
           sequence: index, estimated_tokens: 8, required: false,
@@ -38,7 +38,7 @@ module BenchContextAssembler
       end
     end
 
-    Phronomy::Agent::ContextPolicyInput.new(
+    Phronomy::Context::ContextPolicyInput.new(
       agent_id: "bench-agent", execution_id: "bench-execution",
       call_sequence: 2, call_mode: :complete,
       instruction: [], knowledge: knowledge, tools: [], conversation: conversation,
@@ -50,7 +50,7 @@ module BenchContextAssembler
   end
 
   def assembler_fixture
-    persistence = Phronomy::Persistence.in_memory
+    persistence = Phronomy::PersistenceComposition.in_memory.agent
     agent_class = Class.new(Phronomy::Agent::Base) do
       agent_definition id: "bench-manifest-context-assembler", version: 1
       # Resolve capabilities from RubyLLM's bundled registry; no provider call.
@@ -86,9 +86,10 @@ module BenchContextAssembler
     )
 
     [
-      Phronomy::Agent::ContextAssembler.new(agent: agent, persistence: persistence),
+      Phronomy::Agent::ContextPreparation.new(agent: agent, persistence: persistence),
       root,
-      execution
+      execution,
+      persistence
     ]
   end
 end
@@ -97,7 +98,7 @@ puts "Typed Context Policy benchmark"
 puts "Ruby #{RUBY_VERSION} on #{RUBY_PLATFORM}"
 puts "=" * 72
 
-policy = Phronomy::Agent::ContextPolicies::Default.instance
+policy = Phronomy::Context::DefaultPolicy.instance
 policy_inputs = [10, 100, 1_000].to_h do |count|
   [count, BenchContextAssembler.policy_input(count)]
 end
@@ -110,15 +111,17 @@ Benchmark.bm(46) do |x|
     end
   end
 
-  assembler, root, execution = BenchContextAssembler.assembler_fixture
-  x.report("ContextAssembler prepare/finalize x500") do
+  assembler, root, execution, persistence = BenchContextAssembler.assembler_fixture
+  x.report("Context prepare/store x500") do
     500.times do
       prepared = assembler.prepare_initial(
         input: "benchmark input",
         agent_root: root,
         execution: execution
       )
-      assembler.finalize(prepared)
+      persistence.transaction do |tx|
+        Phronomy::Context::Assembly.new.store(prepared, contents: tx.contents)
+      end
     end
   end
 end

data/benchmark/bench_regression.rb

@@ -69,7 +69,7 @@ end
 # ---------------------------------------------------------------------------
 # Target 3: Tool::Base#params_schema generation (10 params)
 # ---------------------------------------------------------------------------
-tool_class = Class.new(Phronomy::Agent::Context::Capability::Base) do
+tool_class = Class.new(Phronomy::Tool::Base) do
   description "Test tool with 10 params"
   param :p1, type: :string, desc: "param 1"
   param :p2, type: :string, desc: "param 2"

data/benchmark/bench_tool_schema.rb

@@ -7,7 +7,7 @@
 require "benchmark"
 require_relative "../lib/phronomy"
 
-class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
+class BenchTool10Params < Phronomy::Tool::Base
   description "A tool with 10 parameters for benchmarking purposes"
   param :param1, type: :string, desc: "First parameter"
   param :param2, type: :integer, desc: "Second parameter"

data/docs/application-recipes.md

@@ -0,0 +1,229 @@
+# Application recipes
+
+Start with [Getting started](getting-started.md). Every `ruby runnable` block
+below is a complete example after `require "phronomy"` and provider configuration.
+CI substitutes only the LLM adapter; Agent, Tool and Workflow operations are real.
+
+## Choose the completion channel
+
+| Need | Public API | Caller responsibility |
+|---|---|---|
+| One final answer | `agent.invoke(input)` | Call from an external thread |
+| Nonblocking final answer | `agent.invoke_async(input)` | Observe the returned TaskResult |
+| Intermediate events | Construction-time `on_event:` | Keep the callback short |
+| Streamed tokens | `stream` / `stream_async` with a listener | Move network delivery out of the callback |
+| Durable approval | `approve_async` with the request IDs | Apply the application's authorization decision |
+| State-owned asynchronous result | `task_state(name, start:, apply:)` | Framework correlates completion to state entry |
+| Live Workflow notification | `workflow.signal(...)` | Check admission; correlate the waiting operation |
+
+`TaskResult#wait_result` waits at an external application boundary. Completion
+callbacks and Agent listeners must not block EventLoop. A wait timeout does not
+cancel the underlying operation. The caller owns cancellation and cleanup.
+
+## Create, load and get
+
+```ruby runnable
+class ConversationAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-conversation", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+
+store = Phronomy::PersistenceComposition.in_memory.agent
+agent = ConversationAgent.create(agent_id: "recipe-session", persistence: store)
+puts agent.invoke("Hello").fetch(:output)
+
+# A live lookup is not a database read. Loading a live identity returns its owner.
+raise "Unexpected owner" unless ConversationAgent.get("recipe-session").equal?(agent)
+raise "Unexpected load" unless ConversationAgent.load("recipe-session", persistence: store).equal?(agent)
+
+def load_existing_agent(agent_class:, agent_id:, persistence:)
+  agent_class.load(agent_id, persistence: persistence)
+rescue Phronomy::AgentNotFoundError => error
+  raise unless error.agent_id == agent_id.to_s
+  nil
+end
+
+missing = load_existing_agent(
+  agent_class: ConversationAgent, agent_id: "missing-session", persistence: store
+)
+raise "Expected a missing Agent" unless missing.nil?
+```
+
+This application treats only absence as `nil`. Storage unavailability, state
+conflicts and recovery requirements remain errors. `create` is not upsert; do
+not catch every persistence failure and create a replacement conversation.
+The in-memory store is for this example; a durable backend must outlive Runtime
+to support process restart. See [persistence failures](migrations/persistence-failure-contracts.md).
+
+## Streaming and final results
+
+```ruby runnable
+class StreamingAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-streaming", version: 1
+  model "gpt-4o-mini"
+  instructions "Explain briefly."
+end
+
+events = Queue.new
+agent = StreamingAgent.new(on_event: ->(event) {
+  events << event if event.type == :token
+})
+
+task = agent.stream_async("Explain asynchronous results")
+result = task.wait_result
+puts result.fetch(:output)
+puts "Received #{events.size} token events"
+```
+
+The unbounded Queue is an in-process teaching example. A Web application needs
+bounded admission and ordered delivery outside the listener, such as Example 18.
+Register the listener at `new`/`create`/first `load`; per-invocation listener
+arguments or blocks are rejected. Do not replace a listener by loading an
+already-live Agent. See [approval](getting-started.md#human-in-the-loop-approval)
+for the separate durable approval identifiers and application decision.
+
+## Workflow task states
+
+When a Workflow owns the start of an operation, use `task_state` to keep the
+application focused on its operation, result fields and routing decisions.
+The example below returns the original error to its caller if either invocation
+fails; it does not silently retry or convert a failed invocation into an answer.
+
+```ruby runnable
+class TwoAnswersState
+  include Phronomy::WorkflowContext
+  field :question, type: :replace
+  field :answers, type: :replace, default: -> { [] }
+end
+class TwoAnswersAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-two-answers", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+agent = TwoAnswersAgent.new
+workflow = Phronomy::Workflow.define(TwoAnswersState) do
+  initial :asking
+  task_state :asking,
+    start: ->(state) { agent.invoke_async(state.question) },
+    apply: ->(state, result) { state.merge(answers: state.answers + [result.fetch(:output)]) }
+  state :decide
+  transition from: :asking, to: :decide
+  transition from: :decide, to: :__finish__, guard: ->(state) { state.answers.length >= 2 }
+  transition from: :decide, to: :asking
+end
+puts workflow.invoke({question: "Explain completion handles"}).answers
+```
+
+Expected business failures can be converted into application values before
+returning the source Task, for example using `TaskResult.all_settled` and `map`.
+Phronomy does not select a fallback or retry policy. See the
+[full contract](architecture/dx05-workflow-task-state.md).
+
+## Workflow completion and failures
+
+The following **legacy low-level signal recipe** is retained for existing users
+and its compatibility tests. New state-owned asynchronous operations should use
+`task_state` above. The restrictions below apply to this manual recipe, not to
+the new task-state API.
+
+This recipe targets **one live waiting stage**. Do not restart, reenter or replace
+that stage while a result is pending. A logical `workflow_instance_id` alone does
+not identify a particular execution or waiting operation. For those wider cases,
+application operation IDs and receiver-side guards are necessary.
+
+```ruby runnable
+def request_answer(agent:, workflow:, workflow_instance_id:, question:,
+  on_delivery_error:)
+  task = agent.invoke_async(question).map do |result|
+    {answer: result.fetch(:output)}
+  end
+
+  task.on_complete do |payload, operation_error|
+    delivery_error = nil
+    begin
+      accepted = workflow.signal(
+        workflow_instance_id: workflow_instance_id,
+        event: :answer_ready,
+        payload: operation_error ? {error: operation_error} : payload
+      )
+      unless accepted
+        delivery_error = Phronomy::Error.new("Workflow did not accept answer_ready")
+      end
+    rescue => error
+      delivery_error = error
+    end
+    on_delivery_error.call(delivery_error) if delivery_error
+  end
+
+  nil
+end
+
+class AnswerAgent < Phronomy::Agent::Base
+  agent_definition id: "recipe-answer", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+
+class AnswerState
+  include Phronomy::WorkflowContext
+  field :question, type: :replace
+  field :answer, type: :replace
+  field :error_message, type: :replace
+end
+
+agent = AnswerAgent.new
+delivery_errors = Queue.new
+workflow = nil
+workflow = Phronomy::Workflow.define(AnswerState) do
+  initial :asking
+  state :asking
+  state :done
+  entry :asking, ->(state) {
+    request_answer(
+      agent: agent, workflow: workflow,
+      workflow_instance_id: state.workflow_instance_id, question: state.question,
+      on_delivery_error: ->(error) { delivery_errors << error }
+    )
+    state
+  }
+  transition from: :asking, on: :answer_ready, to: :done,
+    action: ->(state, event) {
+      error = event.payload[:error]
+      error ? state.merge(error_message: error.message) : state.merge(answer: event.payload.fetch(:answer))
+    }
+  transition from: :done, to: :__finish__
+end
+
+final = workflow.invoke(
+  {question: "What is a completion handle?"},
+  config: {workflow_instance_id: "recipe-answer"}
+)
+puts final.error_message || final.answer
+raise delivery_errors.pop unless delivery_errors.empty?
+```
+
+The receiver handles both answer and error; changing only the sender would be
+incomplete. Store a serializable diagnostic, not the exception object, in the
+Workflow context. Result mapping failures (such as a missing `:output`) also
+become operation failures. Synchronous submission errors still propagate to
+the caller of `request_answer`.
+
+`signal == true` means admission, not transition completion or durable success.
+`false` and signal exceptions reach `on_delivery_error` once without automatic
+retry. This callback must be short and nonblocking. Its own exceptions follow
+TaskResult's existing callback logging policy; they do not change the settled
+operation result. Logging depends on the configured logger.
+
+Delivery rejection does not itself settle a waiting Workflow. The application
+must observe its diagnostic channel and decide whether to cancel or recover.
+The synchronous invocation above illustrates successful delivery. Production
+callers needing a wait limit should use `invoke_async` and manage both the
+Workflow TaskResult and the diagnostic channel at their external boundary.
+
+No generic Workflow forwarding helper is required by these recipes. A helper
+must first establish how an old result is prevented from reaching a new waiting
+stage; internal execution generations or automatic recovery are not implied.
+
+For an application-local extraction with the same limited lifetime, see the
+[bounded completion recipe](workflow-completion.md). It is not a new library API.