phronomy 0.28.0 → 0.30.0

data/docs/architecture/transport-error-boundaries.md

@@ -0,0 +1,103 @@
+# RubyLLM transport error boundaries
+
+## Purpose and ownership
+
+Applications need to handle a failed provider communication through Phronomy's
+public API without knowing the HTTP client hidden behind the selected backend.
+LLM generation and embedding are separate contracts, so each retains its own
+existing `TransportError`. The concrete RubyLLM backends translate identifiable
+communication failures; Agent, Generation and Execution propagate that result.
+
+This change adds no public class, parameter, failure code, cross-contract edge,
+shared error translator or retry mechanism. Faraday references remain in the two
+concrete backends. The public RBS shape is unchanged.
+
+## Mapping and exclusions
+
+| Failure at the RubyLLM boundary | LLM complete/stream | Embeddings |
+| --- | --- | --- |
+| `Faraday::TimeoutError` | `LLMAdapter::TransportError` | `Embeddings::TransportError` |
+| `Faraday::ConnectionFailed` | `LLMAdapter::TransportError` | `Embeddings::TransportError` |
+| Existing RubyLLM errors | Existing authentication/rate-limit/context/transport classifications | Existing authentication/rate-limit/transport classifications |
+| Application streaming callback, including either Faraday class above | Original exception identity | Not applicable |
+| Cancellation, execution deadline, arbitrary I/O, programming failure or unrecognized Faraday error | Original exception identity | Original exception identity |
+
+The top-level mapped exception preserves the original message and its SDK/HTTP
+exception as `cause`. That exception's network cause is retained, for example:
+`LLMAdapter::TransportError -> Faraday::TimeoutError -> Net::ReadTimeout`.
+No classification is inferred from an exception's message or nested cause.
+The explicitly selected LM Studio backend additionally decodes the HTTP response
+body at the SDK boundary using a narrow provider-response mapping; see
+[LM Studio output failures](lm-studio-output-failures.md). This is not a generic
+exception-message or cause-chain heuristic, and the default RubyLLM mapping below
+is unchanged.
+Generic `Faraday::Error`, `Faraday::SSLError`, raw `IOError` and system errors are
+not added to this mapping. Future additions require evidence and an explicit
+category decision rather than a blanket rescue.
+
+The LLM backend's callback identity check runs before provider classification.
+An application callback throwing `Faraday::TimeoutError` therefore remains the
+same object. A provider timeout after a delivered chunk is a transport failure;
+the already delivered chunk is not withdrawn, replayed or turned into success.
+
+## Application code before and after
+
+Before, handling a provider timeout required knowledge of the backend's client:
+
+```ruby
+begin
+  response = adapter.complete(request)
+rescue Phronomy::LLMAdapter::TransportError,
+       Faraday::TimeoutError, Faraday::ConnectionFailed => error
+  warn "Provider communication failed: #{error.message}"
+end
+```
+
+After, the same communication categories are handled through the public owner:
+
+```ruby
+begin
+  response = adapter.complete(request)
+rescue Phronomy::LLMAdapter::TransportError => error
+  warn "Provider communication failed: #{error.message}"
+end
+```
+
+Embeddings applications use `Phronomy::Embeddings::TransportError` in the same
+way. Applications may inspect `cause` for diagnostics, but ordinary transport
+handling does not need a Faraday dependency. Existing specialized errors remain
+available for applications that distinguish authentication or rate limiting.
+
+## Retry, interruption and lifetime
+
+The accepted [transport-policy ADR](../decisions/011-delegate-transport-policy-to-adapters.md)
+continues to apply. RubyLLM owns its configured HTTP retries. Phronomy translates
+the failure reaching its boundary and does not replay the LLM operation, Agent
+invocation or Tool work. A transport classification does not assert that no
+output or external effect occurred, and does not authorize a retry.
+
+An execution deadline and an HTTP timeout remain different failures. This change
+does not force worker threads to stop, alter cancellation, or make an active
+Agent safe to unload. Once an ordinary provider failure has settled and its
+physical work has finished, the existing lifetime APIs can release its owners.
+
+The old Faraday 2.1.0 / faraday-net_http 2.1.0 streaming path lost HTTP status and
+caused RubyLLM to retry a schema/Tool rejection as a synthetic ServerError.
+The supported floors are now Faraday 2.14.4 / faraday-net_http 3.4.4. Real HTTP
+tests verify the original status and request count with SDK retries enabled.
+The obsolete ServerError-to-schema-rejection fallback is removed: an actual 500
+remains a server failure even when its text resembles a known 400 rejection.
+Configured SDK retries for 429/500 remain intact; no global retry switch or
+SDK monkey patch is introduced.
+
+## Verification
+
+Unit contracts cover both mapped types across complete, stream and embed,
+identity exclusions, same-class callback failures and failure after partial
+output. Loopback HTTP tests exercise the real RubyLLM/Faraday stack for timeout,
+connection loss, partial streaming with SDK retries enabled, callback identity,
+and GeneratorVerifier propagation/release. The minimum HTTP CI job runs these
+contracts too. Test-only shortened timeouts do not change production settings.
+
+These tests do not certify live model answer quality, schema/Tool combination
+support, or the root cause of the earlier unreproduced LM Studio wait.

data/docs/architecture/trust-acceptance-followup.md

@@ -0,0 +1,87 @@
+# Trust pipeline acceptance follow-up
+
+## Purpose and responsibility
+
+Communication integrity, schema validity and business truth are different
+promises. Successful HTTP and valid JSON cannot establish faithful extraction.
+
+| Concern | Owner | Change |
+| --- | --- | --- |
+| HTTP status and configured retries | HTTP stack / concrete RubyLLM backend | Require a verified stack that preserves streaming status |
+| Schema-valid terminal values | Agent, using OutputParser | Existing guarantee retained |
+| Evaluation criteria and result meaning | GeneratorVerifier | Existing protocol retained |
+| Exact invoice extraction | Application / acceptance oracle | Reject incorrect values explicitly |
+| Approval decision and Tool effects | Application decision, Agent execution, Generation routing | Observe notification, decision, effects and release |
+| Unexplained wait | Diagnostic runner plus server logs | Record payload, settings, attempts and periodic thread stacks |
+
+Contract owners, their dependencies, Engine and Execution are unchanged.
+No SDK monkey patch, extra retry loop, output repair or schema downgrade is added.
+
+## HTTP dependency correction
+
+Faraday 2.1.0 with faraday-net_http 2.1.0 did not pass the response environment to
+streaming callbacks. RubyLLM 2.0.0 could interpret a JSON 400 as a synthetic 500.
+401 and 429 could also lose their identity. The ServerError fallback additionally
+misclassified an actual 500 whose text matched the known schema rejection.
+
+Supported floors are now Faraday 2.14.4 and faraday-net_http 3.4.4, the pair
+already verified on the normal path. Both are explicit in the gemspec: raising
+Faraday alone does not exclude older Net::HTTP adapters. CI pins and checks both,
+with the existing minimum RubyLLM, MCP and JSON versions. These are verified
+support floors, not claims about the earliest upstream fix. Custom Faraday
+adapters need their own streaming/status compatibility assessment.
+
+The obsolete ServerError fallback is removed. Only a real BadRequestError with
+the known body becomes StructuredOutputUnsupportedError. Actual 500 responses
+retain the SDK server-error cause. Configured SDK retries for 429/500 remain;
+a 400 rejection is one HTTP attempt even with three retries configured.
+Partial-stream replay and callback identity regressions remain in place.
+
+Before and after, application handling uses the same public API:
+
+```ruby
+rescue Phronomy::LLMAdapter::StructuredOutputUnsupportedError => error
+  warn error.cause.class
+```
+
+Before, the old stack could issue four requests and expose a synthetic ServerError
+for HTTP 400. After, the cause is BadRequestError and that rejection is not
+retried as a transient server failure.
+
+## Content fidelity and acceptance
+
+The invoice demo keeps its general string/number schema and asks the model to
+preserve identifier characters. After Agent release, an independent oracle checks
+the fixed fixture. Incorrect values exit 1; they are never replaced or retried.
+This is fixture acceptance, not a general invoice validator or Agent responsibility.
+
+Before, INV-2026-01 could print and exit successfully for source INV-2026-001.
+After, it is a fidelity failure, while schema validation remains correctly
+successful. One correct response does not establish general model accuracy.
+
+The examples runner checks invoice, accepted, iteration_limit and approval
+yes/no/cancel independently. Approval requires a notification and the expected
+Tool effects. A schema/Tool rejection is blocked, not successful approval.
+Yes checks approval and valid completion; accepted is a separate test because
+Tool approval does not guarantee that evaluation criteria will be satisfied.
+
+## Wait diagnosis and limits
+
+The opt-in runner observes the pinned SDK without replacing the provider or
+changing timeout/retry settings. It records UTC times, request payloads/hashes,
+settings, physical HTTP attempts, results, exception causes, releases and periodic
+Ruby thread stacks. Observer failures invalidate the report and do not replace
+the application exception. Signals wrapped by cleanup errors remain interrupted.
+
+Observation uses diagnostic-only SDK method bindings and must be reviewed when
+the SDK changes. Reports contain prompts/responses. Sampling and file writes add
+overhead; this runner is not a performance benchmark.
+
+Historical LM Studio logs cannot be reconstructed. Match the saved review payload
+and UTC times with server logs; use future wait stacks to identify pending
+HTTP/SDK/framework operations before assigning a cause. A later fast response
+does not resolve the earlier wait.
+
+Controlled HTTP fixtures prove framework and observation behavior, not live
+model accuracy or server support for schema plus Tools. Live acceptance still
+requires a suitable model/server environment and recorded server version.

data/docs/failure-reason-codes.md

@@ -0,0 +1,45 @@
+# Failure reason codes
+
+`Phronomy::Error` and its subclasses accept an optional `code:` String and expose
+it through `error.code`. Unspecified codes are nil. Supplied strings are copied
+and frozen. Existing message, class, cause and backtrace behavior is retained.
+No change is made to StandardError or third-party exceptions.
+
+This is an additive public-contract extension. `class` and `message` remain in
+saved failure diagnostics. When a Phronomy exception has a code, its diagnostic
+also contains `"code"`. The same generic field is retained through Agent failure
+persistence, Team results, and terminal resume/reboot. A code is not an execution
+status and is not a retry permission.
+
+| Code | Owner and meaning |
+|---|---|
+| `team.enqueue_after_finalize` | MultiAgent: a new enqueue was conclusively rejected after finalization, following the existing readback checks |
+
+The operation wrapper remains catchable as ConfigurationError. A Team's aggregate
+failure remains a Phronomy::Error and now carries the stored code. An operation
+that already succeeded with the same identity still replays its original result.
+Unknown persistence outcomes and readback failures remain recovery requirements;
+an inner code is not blindly copied onto that outer uncertainty.
+
+The application may choose to retry only a durably failed planning attempt:
+
+```ruby
+outcome && outcome[:status] == "failed" &&
+  outcome.dig(:error, "code") == "team.enqueue_after_finalize"
+```
+
+Example 21 retains its four-section/content-length validator and existing retry
+limit. That application policy is not part of the reason code contract.
+
+## Compatibility
+
+No SQL columns or record-format versions change. Error diagnostics are content
+JSON; the existing content codec carries the optional field without interpreting
+it. Old diagnostics without codes remain readable. Unknown string codes are
+preserved, and no code is inferred from a message.
+
+A v0.28.0 reader can inspect the extra JSON field through stored result data.
+Its reconstructed exceptions do not expose the new code, and paths that rebuild
+a failure from class/message can lose it. Mixed-version writes and code-based
+exception handling on an old reader are therefore unsupported. Upgrade consumers
+before relying on codes; there is no automatic historical backfill.

data/docs/features.md

@@ -30,6 +30,14 @@ for production deployments.
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Tracing** — Pluggable logical-operation span observability with bounded automatic coverage | Stable |
 | **Error Taxonomy** — Provider errors translated to Phronomy transport/authentication/rate-limit/context errors | Beta |
+| **Optional failure reason codes** — `Phronomy::Error#code` and `code:` retain domain-supplied reasons in saved Agent/Team diagnostics; [meaning and compatibility](failure-reason-codes.md) | Beta |
+
+The RubyLLM backends also translate identified Faraday timeout and connection
+failures to the owning `LLMAdapter::TransportError` or
+`Embeddings::TransportError`, retaining the original cause chain. A stream may
+have delivered partial output before failure; this classification does not imply
+that retry is safe. Callback failures and execution cancellation/deadlines keep
+their identity. See [transport error boundaries](architecture/transport-error-boundaries.md).
 
 Agent definition lineage is separate from Agent instance identity. A named
 concrete Agent may declare `agent_definition version: N`; when `id:` is omitted,
@@ -51,6 +59,7 @@ rather than implicitly inheriting the parent revision. The Stable
 | **VectorStore::Embeddings::AsyncClient** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
 | **Model Context Protocol (MCP) Tool** — `Phronomy::Tools::Mcp` integration through the official `mcp` gem | Beta |
 | **Agent Tool** — `Phronomy::Tools::Agent.from_agent` exposes a child Agent as a Tool without occupying a worker while waiting | Beta |
+| **Ordered event delivery** — Explicitly require `Phronomy::Integrations::OrderedEventDelivery` for bounded ordered delivery outside lifecycle callbacks; [lifetime and failure rules](ordered-event-delivery.md) | Beta |
 | **Vector Search Tool** — `Phronomy::Tools::VectorSearch` wraps VectorStore and Embeddings adapters | Beta |
 
 Applications previously calling async methods on backend objects must
@@ -63,6 +72,7 @@ Backend authors continue to implement the synchronous SPI only.
 |---|---|
 | **EventLoop** — Runtime-owned event-driven execution core shared by Agent, ToolInvocation, Workflow, and MultiAgent sessions; single writer for Phronomy-managed live Agent execution state | Beta |
 | **Agent execution result authority** — Session-local routing plus current FSM state and purpose-specific semantic IDs (`llm_call_id`, `tool_invocation_id`) reject stale async results | Beta |
+| **Agent scope and unload** — `Agent.open_scope` owns newly acquired Agents; `unload_async` / `unload!` release idle incarnations without changing saved state, with typed invalidation and cleanup failures; [contract](architecture/dx05-agent-scope.md) | Beta |
 | **Agent live ownership/admission** — Runtime owns one mutable live Agent per `agent_id`; EventLoop rejects competing same-Agent top-level executions while suspension retains the logical execution slot; Persistence admission remains durable defense | Beta |
 | **Workflow durable admission** — Same-process admission is keyed by durable `workflow_instance_id` from pre-hydration admission through the durable terminal/halted save barrier; admission-owner representation is Runtime-internal | Beta |
 | **`invoke` / `invoke_async`** — Blocking and non-blocking Agent/Workflow entry points | Stable |
@@ -92,9 +102,9 @@ See the [migration guide](migrations/parallel-tool-chat-removal.md).
 
 | Feature | Stability |
 |---|---|
-| **Workflow asynchronous pattern** — Start async work, return immediately, and continue through `Workflow#signal` | Beta |
+| **Workflow asynchronous pattern** — `task_state` starts a `TaskResult`, applies its successful value once to the current state entry, and then evaluates ordinary transitions; `Workflow#signal` remains the application event API | Beta |
 | **Durable Handoff** — `MultiAgent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | Beta |
-| **GeneratorVerifier** — Generator-Verifier loop with injectable prompts/parsers | Beta |
+| **GeneratorVerifier** — Generator-Verifier loop with application prompts, Agent-validated output schemas and explicit output failures | Beta |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |
 | **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
@@ -190,3 +200,5 @@ claim. See [the migration](migrations/durable-semantic-coordination-v2.md).
 turn read-only, including a current absent-but-reserved Target, without graph or
 Agent hydration. Purging an idle main Agent removes its Handoff anchor; pending
 coordination rejects purge rather than discarding its reservation.
+
+Structured output and symmetric lifetime details: [contract and migration](architecture/structured-output-and-scope.md).

data/docs/getting-started.md

@@ -4,6 +4,11 @@ This guide contains the setup and introductory examples that were previously
 embedded in the repository README. The README remains the project entry point;
 this document carries the longer operational examples.
 
+Blocks marked `ruby runnable` are complete after `require "phronomy"` and provider
+configuration. Other blocks are setup or partial examples that reuse definitions
+from the surrounding section. See [application recipes](application-recipes.md)
+for independent examples and explicit failure handling.
+
 ## Install
 
 Add Phronomy to your Gemfile:
@@ -49,11 +54,9 @@ Install only the backend gems required by your application:
 
 ## Define a Tool and Agent
 
-Use `Phronomy::Tool::Base` as the application-facing authoring API. It is an
-exact alias of the existing `Phronomy::Tool::Base`, so
-existing Tool definitions using the longer namespace remain compatible.
+Use `Phronomy::Tool::Base` as the application-facing authoring API.
 
-```ruby
+```ruby runnable
 class WebSearch < Phronomy::Tool::Base
   description "Search the web"
   param :query, type: :string, desc: "Search query"
@@ -115,7 +118,7 @@ A Runtime has at most one mutable live Agent object for an `agent_id`. If the
 Agent is already live, repeated `load` returns that exact Ruby object and does
 not reload Persistence. If it is not live, `load` hydrates the durable Agent
 once. Loading an ID that does not exist durably raises
-`Storage::NotFoundError`.
+`Phronomy::Persistence::NotFoundError`.
 
 Use `get` when only a process-local lookup is wanted:
 
@@ -131,7 +134,7 @@ While the Agent is live, it owns its current AgentRoot/Journal view and
 Runtime/EventLoop owns process-local identity/admission/execution authority.
 Phronomy persists snapshots at defined durability boundaries but does not reload
 mutable Agent/Execution/Journal state before every LLM or Tool step. A conflicting
-external durable write is surfaced as `Storage::ConflictError` rather than
+external durable write is surfaced as `Phronomy::Persistence::StateConflictError` rather than
 silently merged into the live instance.
 
 The active transcript and Knowledge views can be advanced independently without
@@ -165,7 +168,7 @@ the listener when the Agent is materialized, not on each invocation:
 
 ```ruby
 agent = ResearchAgent.load(
-  "research-session-42",
+  "another-session-not-live-in-this-runtime",
   persistence: persistence,
   on_event: ->(event) {
     puts event.payload[:output] if event.type == :done
@@ -175,6 +178,10 @@ agent = ResearchAgent.load(
 task = agent.invoke_async("Hello")
 ```
 
+This load assumes that the other Agent exists in Persistence but has not been
+materialized in this Runtime. To listen to `research-session-42`, register its
+listener in the original `create` call.
+
 `new`, `create`, and `load` also accept an equivalent listener block.
 Supplying both `on_event:` and a construction block is an error. If `load`
 resolves an already-live same-process Agent, supplying any new listener/block
@@ -299,18 +306,16 @@ not inject an explicit `persistence:`. Workflow durability is fixed at the
 application/Workflow-definition boundary; there is no per-invocation backend
 switch.
 
-Workflow entry and transition actions are synchronous Run-to-Completion
-callbacks. If a Workflow needs an Agent or another asynchronous lifecycle, start
-it asynchronously, return the Workflow context immediately, and deliver its
-completion later with `Workflow#signal`.
+Use `task_state` when a state starts an asynchronous operation and needs its
+terminal result before proceeding. `start` returns the TaskResult immediately;
+`apply` updates the current Workflow context on EventLoop. Guards run after
+successful application. Ordinary entry and transition actions remain synchronous.
 
-```ruby
+```ruby runnable
 class AnswerContext
   include Phronomy::WorkflowContext
-
   field :question, type: :replace, default: ""
-  field :answer,   type: :replace, default: nil
-  # workflow_instance_id is framework-owned metadata; do not declare it as a field.
+  field :answer, type: :replace, default: nil
 end
 
 class ResearchAgent < Phronomy::Agent::Base
@@ -320,40 +325,35 @@ class ResearchAgent < Phronomy::Agent::Base
 end
 
 my_agent = ResearchAgent.new
-workflow = nil
-
 workflow = Phronomy::Workflow.define(AnswerContext) do
   initial :asking
-  state :asking
-  state :done
-
-  entry :asking, ->(ctx) {
-    workflow_instance_id = ctx.workflow_instance_id
+  task_state :asking,
+    start: ->(state) { my_agent.invoke_async(state.question) },
+    apply: ->(state, result) { state.merge(answer: result.fetch(:output)) }
+  transition from: :asking, to: :__finish__
+end
 
-    my_agent.invoke_async(ctx.question) do |event|
-      next unless event.type == :done
+answer = workflow.invoke(
+  {question: "What is an asynchronous completion handle?"},
+  config: {workflow_instance_id: "answer-example"}
+)
+puts answer.answer
+```
 
-      workflow.signal(
-        workflow_instance_id: workflow_instance_id,
-        event: :answer_ready,
-        payload: {answer: event.payload[:output]}
-      )
-    end
+Phronomy correlates completion to this execution and state entry, ignores stale
+results after exit or reentry, and propagates start/source/apply failures to the
+caller. A cancelled source cancels the Workflow observation; a failed source
+retains its failure classification. External business events still use
+`Workflow#signal` or `send_event`.
 
-    ctx
-  }
-
-  transition(
-    from: :asking,
-    on: :answer_ready,
-    to: :done,
-    action: ->(ctx, event) { ctx.merge(answer: event.payload[:answer]) }
-  )
-end
-```
+`task_state` is a live wait, while `wait_state` halts the current execution segment.
+Pending Tasks are not persisted: attempting to restore a task-state snapshot
+raises `WorkflowTaskResumeError`. Normal wait-state halt/resume remains supported.
+Parent cancellation stops application of the result; cancelling the child itself
+requires explicit controls passed by the application. See the
+[task-state contract](architecture/dx05-workflow-task-state.md) for these boundaries.
 
-Returning a `Phronomy::TaskResult` from a Workflow entry/transition action is not an
-implicit await mechanism and is rejected.
+Returning a TaskResult from an ordinary entry/transition action remains an error.
 
 ## Agent as Tool
 
@@ -435,6 +435,7 @@ contracts.
 ## Next steps
 
 - [Features and API stability](features.md)
+- [Application recipes](application-recipes.md)
 - [Runtime and concurrency](runtime-and-concurrency.md)
 - [Architecture decisions](decisions/)
 - [Migration guides](migrations/)

data/docs/migrations/r8-unit15.md

@@ -1,5 +1,8 @@
 # r8 unit15 migration
 
+> Historical contract: parser injection/fallback is superseded by
+> [structured output and scope](../architecture/structured-output-and-scope.md).
+
 ## Application impact
 
 No public API, data migration or configuration changes are required.

data/docs/ordered-event-delivery.md

@@ -0,0 +1,54 @@
+# Ordered event delivery
+
+Load the application integration explicitly:
+
+```ruby
+require "phronomy"
+require "phronomy/integrations/ordered_event_delivery"
+
+Phronomy::Integrations::OrderedEventDelivery.open(
+  capacity: 256, batch_size: 32, flush_timeout: 30,
+  deliver: ->(payload) { send_to_application_transport(payload) }
+) do |delivery|
+  agent = MyAgent.new(on_event: ->(event) {
+    payload = application_payload(event)
+    delivery.publish(payload) if payload
+  })
+  agent.stream("Hello")
+end
+```
+
+The block runs on the external caller, and its result is returned after drain.
+`open` rejects EventLoop callers before executing their block. Publication only
+snapshots and queues plain data; it does not wait for capacity or send network
+traffic. The existing Blocking API supplies a worker only while draining. The
+integration creates no scheduler and never shuts down the shared Runtime/pool.
+
+The app owns authentication, destination, authorization, Rails executor wrapping,
+event-to-payload conversion, and any token coalescing. `prepare_batch:` optionally
+receives an immutable Array of snapshots on the drain worker and returns an Array
+of payloads to send in order. Its default is no transformation. Example 18 passes
+its own TokenEventBatch, preserving adjacent-token coalescing with equal metadata.
+
+Capacity limits the waiting queue, excluding an already extracted batch. Multiple
+publishers are ordered by queue admission, not by thread start time. Hashes,
+Arrays, Strings and scalar plain values are copied into immutable snapshots;
+cycles, non-finite numbers and arbitrary objects fail publication.
+
+On overflow/invalid publication, acceptance closes and the failure remains visible
+to final drain even if an Agent listener merely logs its exception. Previously
+accepted work drains if transport is healthy. A failed batch conversion, delivery
+or worker admission also closes acceptance; remaining work may not be delivered.
+There is no silent drop-as-success, automatic retry or durable delivery guarantee.
+
+`close_and_wait` can be called by multiple external threads. It waits for physical
+drain completion, not just TaskResult settlement. A timeout ends only the wait;
+a network operation can still complete afterwards. Configure transport timeouts
+in the transport itself. Network failure does not prove that nothing was sent.
+
+If application execution fails, its original exception, message and backtrace
+remain primary after cleanup. A simultaneous delivery failure is reported through
+the configured Phronomy logger. Without a logger there is no durable diagnostic
+guarantee; logger failure falls back to stderr without replacing the primary error.
+If only delivery fails, that failure is raised. The small final-answer-only Job
+needs no queue and is unchanged.

data/docs/workflow-completion.md

@@ -0,0 +1,92 @@
+# A bounded Workflow completion recipe
+
+This is a **legacy manual-signal recipe**, retained for compatibility and its
+bounded-lifetime tests. New code should use
+[`task_state`](architecture/dx05-workflow-task-state.md), which owns completion
+correlation and failure propagation for operations started by a Workflow state.
+The helper below is application code and is not a Phronomy integration API.
+Its limitations do not describe the new task-state API.
+
+Use the application-local function below only for **one live waiting stage, with
+no restart, reentry or replacement while its operation is pending**. It separates
+result mapping (application logic) from the repetitive notification plumbing.
+For repeated/resumed stages, the app must put an operation ID in every success
+AND error payload and check it with a receiver-side transition `guard:` before
+applying the payload. Signal admission alone is not that check. The example
+below intentionally does not claim that wider guarantee.
+
+```ruby runnable
+def forward_completion(task, workflow:, workflow_instance_id:, event:, on_delivery_error:)
+  task.on_complete do |payload, operation_error|
+    delivery_error = nil
+    begin
+      accepted = workflow.signal(
+        workflow_instance_id: workflow_instance_id, event: event,
+        payload: operation_error ? {error: operation_error} : payload
+      )
+      delivery_error = Phronomy::Error.new("Workflow did not accept #{event}") unless accepted
+    rescue => error
+      delivery_error = error
+    end
+    on_delivery_error.call(delivery_error) if delivery_error
+  end
+  nil
+end
+
+class RecipeAnswerAgent < Phronomy::Agent::Base
+  agent_definition id: "bounded-completion-recipe", version: 1
+  model "gpt-4o-mini"
+  instructions "Answer briefly."
+end
+class CompletionState
+  include Phronomy::WorkflowContext
+  field :question, type: :replace
+  field :answer, type: :replace
+  field :error_message, type: :replace
+end
+
+agent = RecipeAnswerAgent.new
+errors = Queue.new
+workflow = nil
+workflow = Phronomy::Workflow.define(CompletionState) do
+  initial :asking
+  state :asking
+  state :done
+  entry :asking, ->(state) {
+    task = agent.invoke_async(state.question).map { |result| {answer: result.fetch(:output)} }
+    forward_completion(task, workflow: workflow,
+      workflow_instance_id: state.workflow_instance_id, event: :answer_ready,
+      on_delivery_error: ->(error) { 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: "Explain completion handles"},
+  config: {workflow_instance_id: "bounded-recipe"})
+puts final.error_message || final.answer
+raise errors.pop unless errors.empty?
+```
+
+`forward_completion` returns nil after registering one callback. Already-completed
+results are notified immediately. Two registrations are two subscriptions; the
+application avoids duplicates. No task state is changed, no retry is attempted,
+and no callback waits for execution, storage or network delivery.
+
+Operation failures and cancellation notify the Workflow with `{error: error}`.
+A false signal result and a raised signal exception each notify the required
+`on_delivery_error` callback once. A failure of that callback follows TaskResult's
+existing logger policy; it is not retried and does not rewrite the task result.
+The application observes delivery errors and chooses cancellation/recovery.
+
+Signal acceptance does not guarantee transition completion or a durable save.
+Incomplete tasks retain their subscriptions until settlement under the existing
+TaskResult lifecycle. The caller still owns operation cancellation and lifetime;
+this recipe installs no Runtime shutdown hook or global subscription registry.
+
+See [the full application recipe](application-recipes.md#workflow-completion-and-failures)
+for the same failure behavior without extracting this application-local function.

data/gemfiles/http_minimum.gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+eval_gemfile "mcp_1_0.gemfile"
+gem "faraday", "= 2.14.4"
+gem "faraday-net_http", "= 3.4.4"
+gem "webmock", require: false
+
+# Strict JSON decoding and schema transport use these verified minimum versions.
+gem "json", "= 2.21.2"
+gem "ruby_llm", "= 2.0.0"

data/lib/phronomy/agent/admission.rb

@@ -47,7 +47,7 @@ module Phronomy
               "reservation" => correlation, "current_input_ref" => input_ref,
               "durable_context_ref" => context_ref,
               "execution_extension" => @config[:phronomy_execution_participant]&.binding&.to_h
-            }.merge(@preparation_metadata).compact)
+            }.merge(@preparation_metadata).merge(@config[:phronomy_output_contract]&.metadata(records.contents) || {}).compact)
           input_record = JournalRecord.from_h(input_record.to_h.merge("execution_id" => execution_id))
           execution = execution.with(execution_revision: 0, working_records: [input_record])
           records.executions.create_active(execution)

data/lib/phronomy/agent/agent_not_found_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../persistence/errors"
+
+module Phronomy
+  # Only the requested Agent root is absent, not one of its referenced records.
+  # @api public
+  class AgentNotFoundError < Phronomy::Persistence::NotFoundError
+    attr_reader :agent_id
+
+    def initialize(agent_id:)
+      @agent_id = agent_id.to_s.dup.freeze
+      super("Agent not found: #{@agent_id}", code: "agent.not_found")
+    end
+  end
+end

data/lib/phronomy/agent/agent_unloaded_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # An old Agent reference cannot act on a later incarnation of the same ID.
+  # @api public
+  class AgentUnloadedError < Phronomy::Error
+    attr_reader :agent_id
+
+    def initialize(agent_id:)
+      @agent_id = agent_id.to_s.dup.freeze
+      super("Agent #{@agent_id.inspect} has been unloaded", code: "agent.unloaded")
+    end
+  end
+end