phronomy 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f097c81530a33bd631974866ff26a0d2ec8b4793286c6dfa0bb0facaac4fdd83
-  data.tar.gz: 80b9980737c80446f660d9a058aa1b898bdcdec452e517764261c386c32a1e78
+  metadata.gz: 6ee0a6e2cc02a9014a1f6b4b0587474255697960b0e1589070a7846d038452ad
+  data.tar.gz: eb866c788b4dbaf5c560ec0a6a9fe1ef641d630932c7f4309c5ca0741dce2ad0
 SHA512:
-  metadata.gz: 2cacf04ecea168021b36835f12901723380a7a908d0173f23b564e9bb67d4f85cf46bf958949fd4257043393234ef5acc7e8d9cecdcf68beac61b0c7ce454084
-  data.tar.gz: c7f7b1d9cbcd54d0d0d9bb7583e5587ecadfafa987788f44e8c8abc0f9fa75241092d63a543669b55a6837fc1c2c09c102cf514578b6c266b2c85ff17d2ba2cc
+  metadata.gz: a4970e936adca3d87ee8a8a18469630a563df8fb8a07f06796f4a4bfcae3b1e97b67a51869fdbb68760892201deb12f5f765c082cdfe8559c5f6d0c5ad10dd1a
+  data.tar.gz: 10c461ef9e86a476cc73020dc1167d6b80564f02f47c3da0161a7da8a34953be96efa236ebcfdf938c7b8a5bfeb2ea6ad3fdaca137d6f70cd5238a71bd6cb829

data/README.md

@@ -21,7 +21,7 @@ tracking `main` directly.
 
 - **Agent** — stateful, persistence-backed LLM agent with canonical execution history.
 - **Persistence** — shared atomic scopes with domain-owned Agent/Team stores and Workflow checkpoints.
-- **Workflow** — state-machine-driven application workflow with explicit events and wait states.
+- **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.
@@ -35,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:
@@ -49,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.
 
@@ -91,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::Tool::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
@@ -152,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.

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.

data/docs/architecture/dx05-agent-scope.md

@@ -0,0 +1,119 @@
+# Agent scope and incarnation lifetime (DX05-E core)
+
+An application decides how long it needs an Agent. C04 owns the mechanics for
+acquiring that incarnation and releasing it safely. A scope does not delete saved
+Agents, stop other Agents, close an application-owned Store, or infer whether a
+business operation should be retried.
+
+## Application change
+
+Before, a long-running application could create Agents for each request, but
+the Runtime retained their mutable incarnations until shutdown. `close!` changes
+the durable Agent lifecycle; `purge!` deletes saved state. Neither is a substitute
+for releasing a process-local incarnation.
+
+```ruby
+agent = ReviewAgent.create(persistence: store)
+agent.invoke(text) # the Runtime still owns this incarnation afterwards
+```
+
+After, the application declares the ownership boundary once:
+
+```ruby
+Phronomy::Agent.open_scope do |agents|
+  agent = agents.create(ReviewAgent, persistence: store)
+  agent.invoke_async(text)
+end
+```
+
+`open_scope` waits for a returned TaskResult and returns its resolved value (or
+raises the original exception). A plain block value is returned unchanged.
+It then attempts to unload every Agent it acquired. A Workflow can use
+`agents.create_async` or `agents.load_async` from EventLoop and compose their
+TaskResults. The outer application keeps the scope alive until the Workflow has
+finished. A scope is not serializable Workflow context.
+
+An existing application-owned Agent cannot be adopted by `scope.load`: that
+would give the scope permission to release someone else's object. The attempt
+raises `AgentBusyError`. Repeated load in the same scope returns its live instance,
+after checking class and Store compatibility. A listener cannot be replaced on
+an already live instance. Existing `Agent.load`/`get` lookup semantics remain;
+obtaining a reference does not extend its owning scope's lifetime.
+
+## Release contract
+
+`agent.unload_async` returns `TaskResult<Boolean>` and is EventLoop-safe.
+`agent.unload!(timeout: nil)` waits externally. Both preserve all durable state:
+root and context revisions, journal position, contents, history, metadata and
+lifecycle status. A closed Agent remains closed after reload.
+
+Release requires an exact live owner, no accepted operations or execution
+admission (including approval and recovery waits), and an idle durable execution
+ledger with no retention references. C04 interprets only the presence of opaque
+retention references; their owning domain decides when to remove them.
+
+Concurrent release requests share the pending handle. A successful release
+returns `true`; an already unloaded reference returns `false`. A wait timeout
+does not cancel the release. Store check failure rolls back the reservation and
+preserves the original error. Runtime shutdown closes admission and drains
+already accepted transition completion without creating a replacement Runtime.
+
+New operations cannot enter during release. Old Agent operations fail with
+`AgentUnloadedError` (`code: "agent.unloaded"`, `agent_id`); asynchronous methods
+return failed TaskResults. Immutable snapshots and `agent_id` remain usable.
+A later load creates a new instance and can bind a new listener. The old
+reference cannot mutate or release that new owner. Purged Agents keep their
+existing `AgentPurgedError` semantics.
+
+A concurrent `get` or `load` during release raises `AgentBusyError` immediately;
+it does not wait or create a second owner. Accepted operations make unload fail
+with Busy at its admission gate. In particular, unload inside an Agent terminal
+listener is Busy while that listener is executing. Exit the outer application
+scope after result delivery to release it. Existing immutable local-state reads
+remain available while Runtime shutdown is draining an incomplete transition;
+new execution and mutation admission stays closed.
+
+## Failure and cancellation
+
+Scope tracks materialization receipts before starting work and registers acquired
+Agents before returning them. Closure stops new acquisition and waits for the
+physical completion of accepted materialization, even when its handle was
+cancelled. Indeterminate durable create keeps the C04 recovery reservation and
+logs the Agent ID; it is never silently made creatable again.
+
+Scope does not cancel or wait for unjoined child execution as an implicit
+cleanup policy. An active Agent is retained and cleanup reports `AgentBusyError`.
+If the main operation failed, its same exception is preserved and secondary
+cleanup failures are logged with Agent IDs. Logger failure cannot replace it.
+If the main operation succeeded, failed cleanup raises `Agent::ScopeCleanupError`
+(`code: "agent.scope_cleanup_failed"`). `result` preserves the successful value;
+`failures` is an array of `{agent_id:, error:}` with the original exceptions.
+All acquired Agents are attempted. No automatic retry, purge, or retention
+removal is performed.
+
+## Responsibility and ordering
+
+- C04 owns scope receipts, exact incarnation identity, operation admission,
+  busy/retention rules, invalidation and cleanup errors.
+- C07 supplies the existing transaction boundary. C04's Agent Store supplies
+  `assert_idle!`, `guard_agent!` and retention reads; neither Persistence nor
+  physical Storage gains incarnation release policy.
+- C13 supplies existing TaskResult and physical-completion contracts. It gains
+  no scope membership, Agent busy rules or unload states.
+- Engine supplies existing worker execution, serial EventLoop delivery and
+  shutdown participation. It gains no Agent-specific states.
+- The operation lease and release reservation share the C04 ownership mutex.
+  No Store transaction, Runtime call, application callback or blocking wait runs
+  under that mutex. Accepted runner continuations use C04 internal snapshots;
+  callbacks initiating a new public operation must acquire a new lease.
+- Agent operation completion is distinct from cancelling its public handle.
+  C04 acknowledges release after domain terminal/listener delivery and physical
+  worker completion. A queued or physically running cancelled operation still
+  blocks release.
+
+For notifications, finish child processing, drain notifications, then exit the
+Agent scope. `run_once` retains its existing Store and lifetime behavior; merely
+calling it does not opt into scope cleanup.
+
+This is P5 (core). P6 migrates application examples and performs cross-repository
+acceptance against the published or pinned candidate core.

data/docs/architecture/dx05-workflow-task-state.md

@@ -0,0 +1,134 @@
+# DX05-D: Workflow-owned asynchronous task states
+
+Status: unreleased Beta implementation. Based on DX05-A core `c673c958c`.
+
+## Problem and intended application boundary
+
+A Workflow application describes which operation a stage starts, how its result
+changes business state, and where that state goes next. Repeating callbacks,
+completion events, error envelopes and state-entry identifiers obscures those
+choices. Workflow already owns the live execution and state-entry lifetime, so it
+can own this correlation without knowing how an Agent, Tool or LLM runs.
+
+The business flow is preserved. Failure, cancellation, stale-result and delivery
+semantics become explicit and stronger; this is not a claim that every failure
+path of the previous manual recipe was equivalent.
+
+## Before and after
+
+Previously, each state manually arranged delivery (simplified successful path):
+
+```ruby
+workflow = nil
+workflow = Phronomy::Workflow.define(AnswerState) do
+  initial :asking
+  state :asking
+  entry :asking, ->(state) {
+    id = state.workflow_instance_id
+    agent.invoke_async(state.question).on_complete do |value, error|
+      workflow.signal(workflow_instance_id: id, event: :answer_ready,
+        payload: {value: value, error: error})
+    end
+    state
+  }
+  transition from: :asking, on: :answer_ready, to: :__finish__,
+    action: ->(state, event) {
+      raise event.payload[:error] if event.payload[:error]
+      state.merge(answer: event.payload.fetch(:value).fetch(:output))
+    }
+end
+```
+
+That snippet also needs rejection handling and entry-specific guards for safe
+reentry. The application now writes only the operation and successful update:
+
+```ruby
+workflow = Phronomy::Workflow.define(AnswerState) do
+  initial :asking
+  task_state :asking,
+    start: ->(state) { agent.invoke_async(state.question) },
+    apply: ->(state, result) { state.merge(answer: result.fetch(:output)) }
+  transition from: :asking, to: :__finish__
+end
+```
+
+`start` receives an isolated context snapshot, including current phase and
+Workflow identity. It must return a `Phronomy::TaskResult` promptly. It must not
+perform blocking I/O or wait for another Task. Use `Blocking.call_async` for real
+blocking work. `apply` receives the current context and successful value, runs
+briefly on EventLoop, and returns the same context type or nil. Normal transition
+guards run after `apply`. Nil means no context replacement, not failure.
+
+A task state may have ordinary entry/exit actions and external transitions.
+Leaving it abandons observation of its source. Declaring the same state as both
+`state`/`wait_state` and `task_state` is rejected. Ordinary entry/transition actions
+still cannot return a TaskResult. Business signals keep their existing API.
+
+## Contract ownership
+
+| Owner | Responsibility |
+|---|---|
+| C02 Workflow | Task-state definition; live execution and state-entry reception; once-only consumption; success application, failure/cancellation classification; stale-result and queued-progression rejection; restart policy |
+| C13 Execution | Thread-safe TaskResult notification and cancellation subscription mechanisms |
+| I07 Workflow runtime binding | Connect C02 decisions to the existing FSM, owner EventLoop and owner Runtime timer/shutdown services |
+| Engine | Generic event/session delivery and lifecycle; no task-state or Agent policy is added |
+| C04 Agent and application | Agent execution, business transformation/fallback, child cancellation policy and producer lifetime |
+
+C02 uses its execution-environment port and receives an injected session
+connection. It does not select Runtime or depend on I07. `WorkflowTaskSession`
+in I07 adapts the generic FSMSession. Engine source is unchanged.
+
+A revocable C02 reception is created before `start`. Source callbacks retain only
+that reception. Closing it drops source and registry references. Completion is
+sent to the originating registry under an opaque execution owner token, never
+rerouted by a durable Workflow ID. Receiver-side validation checks the current
+entry and consumes once. Exits, reentry, cancellation and terminal decisions
+revoke it. Queued automatic progression also carries an entry-specific key:
+an external transition between result application and automatic dispatch cannot
+advance a later entry. These private messages are not public business signals.
+
+## Outcomes and lifetime
+
+| Condition | Caller-visible result |
+|---|---|
+| Start throws, source fails, or apply throws | Workflow fails with the same error object |
+| Source status is `cancelled` | Workflow TaskResult is cancelled with the source error |
+| Source status is `failed` with a CancellationError | Remains failed; class alone does not imply cancellation |
+| Explicit parent token cancellation/deadline | Cancel Workflow observation; do not implicitly cancel the source |
+| Old or duplicated source notification | Ignore; no application or retry |
+| Current completion delivery rejects/throws | Fail on the owner; if owner delivery is wholly unavailable, settle observation only and retain admission until shutdown cleanup |
+| Runtime shutdown while waiting | Settle observation and revoke subscriptions; no claim that child work physically stopped |
+| Known durable terminal result | Use existing save/readback classification and release rules |
+| Unknown durable terminal result | Fail the observation while retaining recovery-required ownership |
+
+Cancellation is serialized on the owning EventLoop. Once terminal persistence
+has begun, its existing durable barrier remains authoritative; later cancellation
+does not reverse a committed or uncertain terminal decision. A source passed to
+the state has an independent lifetime. Applications explicitly pass cancellation
+controls to children when desired; they own Agent release and side effects.
+
+This API creates no thread/worker for logical waits. Actual I/O and existing
+tracing or checkpoint work may still use the bounded pool. Expected business
+failures may be transformed into ordinary values through TaskResult composition.
+The API does not infer retry, fallback, durable child execution or delivery ACKs.
+
+## Persistence and restart
+
+Normal completion and ordinary `wait_state` halts use existing Workflow
+checkpoints. Resuming an ordinary wait into a new task state is supported. Pending
+TaskResults, callbacks and entry keys are process-local and are never serialized.
+Restoring a snapshot whose phase is a task state raises
+`Phronomy::WorkflowTaskResumeError` (C02, subclass of `Phronomy::Error`, code
+`workflow.task_resume_unsupported`) before running its start callback. The
+application must reconcile that operation explicitly instead of automatically
+repeating external side effects. F01 durable child execution remains separate.
+
+## Verification
+
+The new task-state regression suite covers immediate and delayed results,
+repeated entry, old success/failure/cancellation, duplicate callbacks, external
+transition races, rejected guards, delivery failure, shutdown, source/parent
+cancellation, owner Runtime selection, retained-reference revocation, strict
+callback result types, normal durable halt/resume, restart rejection and unknown
+durable outcomes. Existing Workflow, TaskResult, API and executable-documentation
+tests remain active. Examples 01/03/04/07/14/20/25/26 use the new API.