phronomy 0.27.0 → 0.29.0

data/docs/decisions/065-vector-and-embeddings-common-operations.md

@@ -0,0 +1,38 @@
+# ADR-065: Vector and Embeddings common operations
+
+Status: accepted for the authorized r8 unit 5 implementation. Actual-service
+verification is reported separately from the design decision.
+
+This amends ADR-059's vector/embedding extension and namespace provisions.
+Its synchronous backend boundary, separate AsyncClients and no production worker
+Threads rule remain in force. It implements C10/C11 and DP09/DP10 from the agreed
+contract foundation target.
+
+VectorStore::Base and Embeddings::Base own the public operation templates,
+validation and cancellation checkpoint. Concrete backends override protected
+perform_* hooks, retaining algorithms, database/SDK adaptation and physical state.
+VectorStore does not require an embedding provider, and Embeddings does not depend
+on VectorStore. Documents groups the existing Loader/Splitter helpers without
+creating another domain Contract.
+
+Placement is decided by domain meaning and observable rules, not shared use.
+Generic reusable code does not become a Contract merely because multiple callers
+need it. Database response parsing and SDK/serialization adaptation remain
+implementation responsibilities even when several backends perform similar work.
+
+Malformed public inputs fail before backend I/O. Malformed backend results fail
+explicitly. Provider exceptions are adapted at the provider boundary, never by
+rescuing arbitrary application failures in the common framework. No generic retry,
+commit reconciliation or stronger concurrency guarantee is added.
+
+Backends must reject malformed external data before converting it to the public
+result. Redis RESP2 fields/counts/distances and Pgvector rows/JSON are decoded
+inside their own backends, with `VectorStore::InvalidResultError` as the public
+failure for invalid data. Legitimate absent metadata and Redis's documented
+expired-document response are distinguished from corruption. The common Base
+then validates the domain result; it contains no external-protocol decoder.
+
+Old namespaces and public-template overrides are intentionally replaced without
+compatibility aliases. Runtime API, RBS, contract tests, examples and migration
+guidance move together. See [unit 5](../architecture/r8-unit5.md) and
+[migration](../migrations/r8-unit5.md).

data/docs/decisions/066-llm-and-tool-operation-contracts.md

@@ -0,0 +1,20 @@
+# ADR-066: LLM and Tool operation contracts
+
+Status: Accepted for the r8 unit 6 candidate; application verification is separate.
+
+C09 owns model-turn values, operation invariants, usage and failures. C06 owns Tool
+requests, schemas, validation, authorization and execution rules. Shared usage is
+not a placement criterion. SDK wire parsing/rendering and callback interception
+remain in the RubyLLM backend. Agent owns context, approval, durable execution and
+recovery; AsyncClient submits the complete backend operation to Execution.
+
+Tool::Base becomes independent of RubyLLM::Tool. The schema used for advertisement
+is also the validation source for both declaration paths. C09 depends only on C06
+value/schema semantics, never executable Tool instances. Protected hooks allow a
+minimal independent backend; public complete/stream enforce the common contract.
+No forwarding namespace or legacy SDK-shaped adapter SPI is retained.
+
+Consequences and compatibility are recorded in
+[unit 6 architecture](../architecture/r8-unit6.md) and
+[unit 6 migration](../migrations/r8-unit6.md). Existing pending execution schema
+comparisons remain strict; deployment must account for changed Tool definitions.

data/docs/decisions/067-agent-progress-and-engine-connection.md

@@ -0,0 +1,29 @@
+# ADR-067: Agent progress owns policy; composition supplies its execution connection
+
+Status: accepted for r8 unit 7 candidate. Supersedes the construction ownership
+portion of the Agent transition design; durable guarantees are unchanged.
+
+## Decision
+
+Keep progress rules, entry operations, admission, approval and recovery decisions
+inside Agent. Introduce the private ExecutionEnvironment connection and an Engine
+implementation. Bind a live Agent to the environment of its ownership registry.
+Move concrete session/phase-machine construction to agent/runtime_binding.
+Keep state_machines out of InvocationTransitions. Extract the serial receiver
+lifecycle framework to Execution with an Engine-owned channel implementation.
+
+## Why
+
+The old session builder mixed domain operations with concrete FSM construction.
+Repeated Runtime.instance lookups made execution connection selection implicit.
+Moving all code into a binding would relocate the same semantic mixture.
+A contract owns executable rules, not just signatures or forwarding methods.
+
+## Consequences
+
+The application invoke/stream/approval/recovery API is unchanged. Internal
+AgentInvocationSessionBuilder is removed with no alias. Private receiver
+constructors now accept a channel. Internal embedders must adopt the composition
+port and respect serial mutation, bounded submission, shutdown and session
+incarnation rules. Tool child and other domain FSM decomposition remain separate
+work. See ../architecture/r8-unit7.md for scope and verification.

data/docs/decisions/068-agent-tool-child-progress-and-tool-operation.md

@@ -0,0 +1,36 @@
+# ADR-068: Agent owns Tool child progress; Tool owns its operation protocol
+
+Status: accepted for the r8 unit 8 candidate. Extends
+[067-agent-progress-and-engine-connection](067-agent-progress-and-engine-connection.md)
+to Tool children and refines the operation boundary in
+[066-llm-and-tool-operation-contracts](066-llm-and-tool-operation-contracts.md).
+
+## Decision
+
+Keep Tool child transitions, approval waiting, dispatch eligibility, outcome
+application and parent notification in C04. Use one ordered transition definition
+for both concrete FSM construction and source admission. Move FSMSession and
+state_machines construction into Agent runtime_binding. Pass the original Agent
+execution environment explicitly to child authorization and execution.
+
+C06 owns standard/custom Tool operation dispatch, execution-mode validity,
+completion protocol and result adaptation. It accepts the C13 submitter protocol
+for standard offloaded work. Agent uses the public operation rather than
+inspecting the implementation owner and calling the private default executor.
+Custom Tool#call_async overrides keep their public signature and own mechanism.
+
+## Reason
+
+The previous builder mixed Agent rules with concrete connections and duplicated
+transition definitions. Agent also selected Tool implementation paths in both
+invocation and result binding. Moving whole classes to an adapter or assigning
+all Tool-related progress to C06 would preserve or misplace those responsibilities.
+
+## Consequences
+
+The boundary now supports independent Agent policy tests and Engine adaptation
+tests. No concrete Runtime or Agent type enters C06. Existing durable identity,
+approval/recovery, causal revision and physical-quiescence guarantees remain.
+No new exactly-once or in-flight version compatibility is claimed. See
+[the unit 8 scope](../architecture/r8-unit8.md) and
+[migration instructions](../migrations/r8-unit8.md).

data/docs/decisions/README.md

@@ -88,7 +88,7 @@ resolved explicitly.
 | [`037-common-definition-ownership`](037-common-definition-ownership.md) | Amended | Yes | Defines the common responsibility group and initially extracts the shared base exception; [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md) extends the extraction scope while preserving ownership rules and exception contracts. |
 | [`038-responsibility-based-source-layout`](038-responsibility-based-source-layout.md) | Amended | Yes | Reserves the direct root for version/namespace loading, groups common definitions and feature implementation/contracts, and preserves canonical constants and lifecycle loading through explicit Zeitwerk roots. ADR-039 separates cross-owner Runtime lifecycle coordination. |
 | [`039-runtime-configuration-lifecycle-ownership`](039-runtime-configuration-lifecycle-ownership.md) | Amended | Yes | Separates application Runtime reset and configuration replacement into runtime_composition; configuration access and Engine mechanics retain their own ownership and existing API behavior. ADR-040 separates concrete-default selection without changing Runtime reset. |
-| [`040-configuration-default-composition`](040-configuration-default-composition.md) | Accepted | Yes | Settings consume internal fresh-instance factories; runtime_composition selects and binds the concrete adapter/tracer defaults. Preserves Configuration.new and the adapter SPI. |
+| [`040-configuration-default-composition`](040-configuration-default-composition.md) | Amended | Yes | Settings consume internal fresh-instance factories; runtime_composition selects and binds the concrete adapter/tracer defaults. Preserves Configuration.new and the adapter SPI. |
 | [`041-feature-owned-identity-registries`](041-feature-owned-identity-registries.md) | Accepted | Yes | Agent and MultiAgent own identity registries; Runtime retains them through generic lookup, drain/wait, and optional finalization. Preserves product APIs and single-owner lifetime; Execution state is separately assigned by ADR-042. |
 
 | [`042-feature-owned-execution-state`](042-feature-owned-execution-state.md) | Accepted | Yes | Agent/Workflow own execution state; Engine retains generic receiver delivery, synchronization and shutdown boundaries. Single-writer and durable barriers remain. |
@@ -110,6 +110,15 @@ resolved explicitly.
 
 | [`058-neutral-storage-primitives`](058-neutral-storage-primitives.md) | Accepted | Yes | Neutral Records/Streams/Blobs SPI 2 and scoped transaction lifecycle; amends 032, 033, 043 and 057. |
 
+| [`059-backend-contracts-and-async-clients`](059-backend-contracts-and-async-clients.md) | Accepted | Yes | P1/P2 separates synchronous LLM contracts, implementations and internal clients; independent responsibility groups replace numbered layers. VectorStore/Storage migration remains pending. |
+| [`060-runtime-settings-and-application-configuration`](060-runtime-settings-and-application-configuration.md) | Accepted | Yes | Separates neutral Engine settings from typed application Configuration; preserves public settings/lifecycle semantics and requires the complete Ruby + RBS boundary gate without exceptions. |
+
+| [`061-persistence-failure-contracts`](061-persistence-failure-contracts.md) | Accepted | Yes | Independent domain failure contracts and explicit raw Storage translation; public rescue-clause migration, preserved transaction/admission/uncertainty semantics. |
+| [`062-content-store-service`](062-content-store-service.md) | Accepted | Yes | Content management over neutral Storage; removes the unnecessary backend subdivision and preserves content/Persistence behavior. |
+
+| [`063-execution-contracts-and-services`](063-execution-contracts-and-services.md) | Accepted | Yes | Shared execution contracts and result/call services separated from Engine internals; preserves public APIs and fixes filtered physical completion. |
+| [`068-agent-tool-child-progress-and-tool-operation`](068-agent-tool-child-progress-and-tool-operation.md) | Accepted | Yes | C04 Tool child progress and original environment; C06 operation dispatch/result adaptation; child FSM in runtime_binding. |
+
 ## Legacy duplicate `011`
 
 The repository intentionally preserves both legacy files:
@@ -203,3 +212,11 @@ Current explanatory architecture starts at
 segregated under `docs/archive/design/` and are non-normative. Explanatory
 architecture documents describe the reconciled current system but do not
 supersede ADRs merely by being newer.
+
+- [`064-agent-execution-and-multi-agent-responsibility`](064-agent-execution-and-multi-agent-responsibility.md)
+
+- [`065-vector-and-embeddings-common-operations`](065-vector-and-embeddings-common-operations.md) — accepted for r8 unit 5; amends the vector/embedding SPI and namespace provisions of ADR-059.
+
+- [`066-llm-and-tool-operation-contracts`](066-llm-and-tool-operation-contracts.md)
+
+- [`067-agent-progress-and-engine-connection`](067-agent-progress-and-engine-connection.md) — Agent progress rules and Engine connection ownership.

data/docs/execution-boundaries-preview.md

@@ -0,0 +1,45 @@
+# Execution boundary candidate (unapplied)
+
+Base: main 653e255a34fe4062d4beca47530e084fdd3a6ba9.
+This is an unpublished prototype for source-derived architecture review.
+
+TaskResult, Outcome, result composition, physical completion and ScopeState
+belong to Execution Results. They depend on Contracts and Common, without
+acquiring Runtime or calling Execution Services. Engine and Services share
+these neutral results. OffloadPool uses an injected timer protocol; its wait
+guard uses WaitPolicy. Services owns operation binding, timer subscriptions,
+worker submission and invocation-control adaptation.
+
+Workflow::Completion owns the public DSL finish value `:__finish__`.
+WorkflowPhaseMachineBuilder, beside WorkflowRunner, translates it to the FSM
+terminal state. FSMSession retains terminal detection and persistence gating.
+TerminalDecision is an execution contract, independent of Workflow and FSM
+state vocabulary.
+
+## Intentional compatibility changes
+
+* InvocationContext#effective_timeout_token and #effective_cancellation_token
+  are removed. Although annotated private, both occurred in the Stable API
+  snapshot. This candidate updates those two entries explicitly. Applications
+  pass cancellation_token/deadline into InvocationContext; the invoking
+  service applies them. Code needing a standalone token constructs
+  Concurrency::CancellationToken directly.
+* Deadline#attach_to is removed. Deadline is a time value, not a timer owner.
+  Internal Workflow control adaptation moves to InvocationControls.
+* Unused private CancellationScope is removed. Private
+  Workflow::PhaseMachineBuilder becomes WorkflowPhaseMachineBuilder in the
+  Runner source directory. FSMProtocol::TerminalDecision becomes
+  Phronomy::TerminalDecision. Direct requires of moved internal files change.
+* An already expired Workflow deadline now cancels immediately. An explicitly
+  supplied token still takes precedence over that deadline, as before.
+
+TaskResult/map/flat_map/all_settled and AsyncClient public operations remain.
+WorkerSubmission preserves injected-pool ownership, original result identity,
+operation-time Runtime resolution and synchronous admission errors. Blocking
+continues converting admission errors to failed results. MCP keeps its named
+cleanup pool. Engine connections remain with registries/coordinators/runners.
+
+RBS declares scope, timer, receiver and terminal-policy protocols in sig/.
+Validation checks signature consistency, not whole-program type correctness.
+The static diagram includes Ruby and RBS evidence; injected implementations
+and callback behavior also require runtime tests.

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,7 @@ 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 |
 
 Agent definition lineage is separate from Agent instance identity. A named
 concrete Agent may declare `agent_definition version: N`; when `id:` is omitted,
@@ -46,18 +47,25 @@ rather than implicitly inheriting the parent revision. The Stable
 |---|---|
 | **Knowledge** — Journal-backed persistent Agent context registered with `knowledge:` / `add_knowledge`, selected per LLM call by Context Policy | Beta |
 | **`VectorStore#size`** — Document count for InMemory, RedisSearch, and Pgvector backends | Beta |
-| **VectorStore async convenience** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `TaskResult`; native async override is not part of the current Backend SPI | Beta |
-| **Embedding async convenience** — `embed_async` offloads synchronous `embed` through Phronomy and returns `TaskResult` | Beta |
+| **Storage::AsyncClient** — `transaction_async` runs a raw backend transaction on one worker and returns TaskResult; [usage and lifetime rules](migrations/storage-async-client.md) | Beta |
+| **VectorStore::AsyncClient** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `TaskResult`; native async override is not part of the current Backend SPI | Beta |
+| **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
+[move those calls to explicit clients](migrations/vector-async-clients.md).
+Backend authors continue to implement the synchronous SPI only.
+
 ## Execution and reliability
 
 | Feature | Stability |
 |---|---|
 | **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 |
@@ -87,8 +95,8 @@ 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 |
-| **Durable Handoff** — `Agent::Handoff` and `MultiAgent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | 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 |
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — LLM coordinator with stateful worker Agents | Beta |

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::Agent::Context::Capability::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"
@@ -85,7 +88,7 @@ application does not need to pass the previous `messages` array back into every
 invocation.
 
 ```ruby
-persistence = Phronomy::Persistence.in_memory
+persistence = Phronomy::PersistenceComposition.agent
 
 agent = ResearchAgent.create(
   agent_id: "research-session-42",
@@ -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
@@ -250,7 +257,7 @@ end
 write_draft  = ->(state) { state.merge(draft: "Draft content") }
 review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
 
-persistence = Phronomy::Persistence.in_memory
+persistence = Phronomy::PersistenceComposition.in_memory.workflow
 
 workflow = Phronomy::Workflow.define(
   ReviewContext,
@@ -274,7 +281,7 @@ final = workflow.send_event(state: state, event: :approve)
 puts final.approved
 ```
 
-`Persistence#workflow_states` is the durable Workflow repository. `workflow_instance_id`
+The injected Workflow checkpoint repository supplies `load`, `save`, and `delete`. `workflow_instance_id`
 identifies the durable Workflow state and remains stable across resume. Each
 concrete Runtime execution receives a separate internal `fsm_session_id`; the
 application-level `session_id` remains ordinary caller/tracing metadata. Phronomy
@@ -286,28 +293,29 @@ A global Persistence backend can be configured when Agents and Workflows should
 share one durable backend:
 
 ```ruby
+stores = Phronomy::PersistenceComposition.in_memory
 Phronomy.configure do |config|
-  config.persistence = persistence
+  config.agent_store = stores.agent
+  config.multi_agent_store = stores.multi_agent
+  config.workflow_store = stores.workflow
 end
 ```
 
-Agent `new`/`create` and Workflow definitions use the global backend when they do
+Agent `new`/`create`, Team construction, and Workflow definitions use their configured store when they do
 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
@@ -317,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
 
@@ -432,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/0.22.md

@@ -178,8 +178,8 @@ and no ordinary Handoff Tool result is generated.
 
 ACS-04 replaces the intermediate Context selection composition API with the
 final four-category Context Policy SPI. Application-defined policies receive an
-immutable `Phronomy::Agent::ContextPolicyInput` and return an immutable
-`Phronomy::Agent::ContextPlan`, each organized as `instruction`, `knowledge`,
+immutable `Phronomy::Context::ContextPolicyInput` and return an immutable
+`Phronomy::Context::ContextPlan`, each organized as `instruction`, `knowledge`,
 `tools`, and grouped `conversation`.
 
 Agent classes bind one Application-constructed Policy instance:

data/docs/migrations/durable-semantic-coordination-v2.md

@@ -1,5 +1,7 @@
 # Durable semantic coordination V2 migration
 
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
 > Runner namespace update (2026-09-18): this document preserves the V2
 > implementation/migration record. The current Runner is
 > `Phronomy::MultiAgent::HandoffRunner` under

data/docs/migrations/handoff-runner-multi-agent.md

@@ -1,5 +1,7 @@
 # HandoffRunner moves to MultiAgent
 
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
 This change applies to H1 on `refactor/architecture` after core commit
 `fe2ad7cea6945a240858b18645dc4ae285e8ce64`. The released 0.26.0 gem does not
 yet provide this new Runner name.

data/docs/migrations/persistence-failure-contracts.md

@@ -0,0 +1,67 @@
+# Migrate the domain Persistence failure contract
+
+This change intentionally changes the exception classes exposed by domain
+Persistence operations. Apply it together with application rescue-clause updates;
+there is no compatibility alias. Public method arguments, return values and
+backend SPI 2 do not change.
+
+## Application and domain repository callers
+
+For calls through `Persistence`, its eight repositories, Agent, Team and Workflow,
+use the upper contract:
+
+| Previous category | New category |
+|---|---|
+| `Phronomy::Storage::ConflictError` | `Phronomy::Persistence::ConflictError` |
+| `Phronomy::Storage::NotFoundError` | `Phronomy::Persistence::NotFoundError` |
+| `Phronomy::Storage::SerializationError` | `Phronomy::Persistence::SerializationError` |
+| `Phronomy::Storage::UnsupportedBackendError` | `Phronomy::Persistence::UnsupportedBackendError` |
+
+For example:
+
+```ruby
+begin
+  root = persistence.agents.load(agent_id)
+rescue Phronomy::Persistence::NotFoundError => error
+  # Handle the missing domain object here.
+  logger.info(error.message)
+end
+```
+
+`Persistence::StateConflictError < Persistence::ConflictError` identifies state,
+ownership or revision contradictions raised by upper domain operations. Catch
+ConflictError when the application handles both state and backend conflicts.
+This subtype is not an instruction to retry: retain operation-specific retry and
+recovery policies. Repository CAS/precondition rejections expose ConflictError.
+
+Translated backend failures retain their original message/backtrace and expose
+the original exception through `error.cause`. Backend constraint/resource details
+remain there. `AgentBusyError` keeps its existing meaning and original cause;
+only the owning active constraint/condition qualifies for that mapping.
+
+## Backend implementations and raw callers
+
+Do **not** globally replace Storage exception names in driver implementations or
+raw `Storage::Backend`/View/Records/Streams/Blobs callers. Those interfaces still
+raise Storage errors. The raw `persistence.backend` accessor exposes that same
+backend. Direct `ContentStore::StoredContents` use also retains its raw failure
+surface; `persistence.contents` applies the upper translation boundary.
+
+Core domain repository conformance examples now expect Persistence errors. Raw
+Storage conformance examples continue to expect Storage errors. Tests which
+inject failures at the physical backend should still inject Storage exceptions;
+tests mocking an already translated repository should inject Persistence errors.
+
+## Commit uncertainty and saved data
+
+Only the four listed categories are translated. Unknown driver/transport errors,
+including IOError, and Storage::TransactionError pass through as the same object.
+ContentStore::IntegrityError and existing domain errors also retain identity.
+Do not classify every Persistence::Error as a known rollback, and do not add a
+retry for a lost commit acknowledgement. Existing admission, transaction scope,
+rollback, nested savepoint and recovery rules continue to apply.
+
+No database migration is required. Saved records and content bytes use the same
+formats. Error class names in newly saved diagnostic payloads can use the new
+Persistence names. Old saved class strings remain diagnostic data; they are not
+resolved as live exception constants or rewritten.

data/docs/migrations/r8-unit10.md

@@ -0,0 +1,36 @@
+# Migrating to r8 unit 10
+
+Apply after core d961fc742f6c4ea4d06dc89f20eedfeb49d04099 (unit 9).
+This package changes core only. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+Public TeamCoordinator and HandoffRunner arguments and results are unchanged.
+No database migration or application Registry registration is needed.
+The existing registries remain MultiAgent-owned and preserve their rules.
+
+| Internal use | Replacement |
+| --- | --- |
+| AdmissionRegistry.for(runtime) | The owning MultiAgent ExecutionEnvironment.admissions |
+| TeamOwnershipRegistry.for(runtime) | The owning environment.ownership |
+| TeamOwnershipRegistry.existing_for(runtime) | The selected environment.existing_ownership for lookup only |
+| Team/Handoff Runtime.instance checks | The captured environment.current? |
+| Team cancellation Execution.submit(runtime: ...) | The captured environment.submit(...) |
+| Team persistence factory in runtime_composition/agent_defaults.rb | runtime_composition/multi_agent_defaults.rb |
+
+Registry construction remains side-effect free. Tests of domain rules can use
+Registry.new; tests of Runtime registration use MultiAgent::EngineEnvironment.
+Removed private class methods have no aliases. Internal callers are updated
+together. New connection classes are private APIs; public RBS signatures stay
+unchanged. Ordinary require "phronomy" installs defaults lazily, without creating
+global configuration, stores or a Runtime during loading.
+
+The ZIP includes complete changed files, a strict-base applier, expected-tree
+verification, a review patch, test evidence and rollback instructions. Run
+--check, --apply and --verify in a new worktree, then --verify again after commit.
+Use the existing stop/drain procedure when replacing running processes. This
+change does not add in-flight cross-version compatibility or rollback of
+external effects.
+
+For examples verification, unset BUNDLE_GEMFILE before entering the examples
+checkout and set PHRONOMY_PATH to the candidate core. Inspect and restore only
+verification-generated lockfile/vendor changes; no examples commit is needed.