phronomy 0.26.0 → 0.28.0

data/docs/decisions/README.md

@@ -62,7 +62,7 @@ resolved explicitly.
 | [`011-delegate-transport-policy-to-adapters`](011-delegate-transport-policy-to-adapters.md) | Accepted | Yes | Legacy duplicate numeric prefix; use the full canonical key. |
 | [`012-canonical-execution-log-and-context-policy`](012-canonical-execution-log-and-context-policy.md) | Accepted | Yes | Current Journal / Manifest / Context authority. |
 | [`013-journal-backed-knowledge-as-context-candidates`](013-journal-backed-knowledge-as-context-candidates.md) | Accepted | Yes | Current persistent Knowledge authority. |
-| [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md) | Accepted | Yes | Durable-backend and live-owner/no-reload intent remains current; live Agent execution mutation is refined by ADR-024, same-process Agent identity/admission ownership by ADR-025, and same-process Workflow admission/terminal-barrier ordering by ADR-026. Workflow identity terminology is superseded by ADR-020, generic `InvocationContext` / Agent correlation semantics by ADR-021, and concrete FSMSession/Agent-Tool routing identity by ADR-023. |
+| [`014-unified-persistence-durable-state`](014-unified-persistence-durable-state.md) | Accepted | Yes | Durable-backend and live-owner/no-reload intent remains current; [032-storage-backend-composition](032-storage-backend-composition.md) refines storage contract ownership and replaces the backend inheritance SPI; live Agent execution mutation is refined by ADR-024, same-process Agent identity/admission ownership by ADR-025, and same-process Workflow admission/terminal-barrier ordering by ADR-026. Workflow identity terminology is superseded by ADR-020, generic `InvocationContext` / Agent correlation semantics by ADR-021, and concrete FSMSession/Agent-Tool routing identity by ADR-023. |
 | [`015-tool-public-facade-and-rbs-boundary`](015-tool-public-facade-and-rbs-boundary.md) | Accepted | Yes | Current Tool façade / extension-SPI / RBS boundary. |
 | [`016-semantic-multi-agent-handoff`](016-semantic-multi-agent-handoff.md) | Superseded | No | Superseded by [ADR-030](030-agent-handoff-domain-and-durable-responsibility.md), including Agent-domain ownership and exact Target recovery. |
 | [`017-design-authority-and-adr-governance`](017-design-authority-and-adr-governance.md) | Accepted | Yes | Repository-wide architecture authority and ADR governance. |
@@ -72,14 +72,52 @@ resolved explicitly.
 | [`021-generic-agent-invocation-identity-removal`](021-generic-agent-invocation-identity-removal.md) | Accepted | Yes | Removes generic Agent/InvocationContext identity and canonical Journal `correlation_id`; CG-02 is closed, with targeted legacy durable-key read compatibility and no eager rewrite. |
 | [`022-agent-execution-parent-identity-and-runtime-routing-boundary`](022-agent-execution-parent-identity-and-runtime-routing-boundary.md) | Accepted | Yes | Canonicalizes Agent-owned Tool/approval logical parent as `execution_id`; CG-03a is reconciled, ADR-023 supplies incarnation routing, and ADR-024 supplies EventLoop result/live-state authority. |
 | [`023-fsm-session-incarnation-identity-and-routing`](023-fsm-session-incarnation-identity-and-routing.md) | Accepted | Yes | FSMSession-owned incarnation identity, session-local Agent/Tool/Multi-Agent routing, and stale-target drop remain current. Its transitional Workflow identity-reservation/admission bridge is superseded by ADR-026; Agent result authority is completed by ADR-024. |
-| [`024-event-loop-single-writer-agent-runtime`](024-event-loop-single-writer-agent-runtime.md) | Accepted | Yes | EventLoop is the single writer of Phronomy-managed live Agent execution state; removes Activation/ActivationRegistry and defines operation-specific Offload result application with current FSM + semantic-ID authority. |
-| [`025-process-local-agent-ownership-and-runtime-admission`](025-process-local-agent-ownership-and-runtime-admission.md) | Accepted | Yes | One mutable live Agent owner per `agent_id` per Runtime; EventLoop is the primary same-process top-level admission authority while Persistence admission remains durable defense. |
-| [`026-workflow-runtime-admission-and-durable-terminal-barrier`](026-workflow-runtime-admission-and-durable-terminal-barrier.md) | Accepted | Yes | EventLoop-owned opaque Workflow admission owner, admission-before-hydration ordering, and FSMSession-integrated durable terminal save barrier with fail-closed uncertain outcomes. |
+| [`024-event-loop-single-writer-agent-runtime`](024-event-loop-single-writer-agent-runtime.md) | Amended | Yes | EventLoop is the single writer of Phronomy-managed live Agent execution state; removes Activation/ActivationRegistry and defines operation-specific Offload result application with current FSM + semantic-ID authority.  Implementation ownership/delivery amended by [042-feature-owned-execution-state](042-feature-owned-execution-state.md). |
+| [`025-process-local-agent-ownership-and-runtime-admission`](025-process-local-agent-ownership-and-runtime-admission.md) | Amended | Yes | One mutable live Agent owner per `agent_id` per Runtime; EventLoop is the primary same-process top-level admission authority while Persistence admission remains durable defense. ADR-041 moves registry implementation to Agent while retaining Runtime-scoped lifetime.  Implementation ownership/delivery amended by [042-feature-owned-execution-state](042-feature-owned-execution-state.md). |
+| [`026-workflow-runtime-admission-and-durable-terminal-barrier`](026-workflow-runtime-admission-and-durable-terminal-barrier.md) | Amended | Yes | EventLoop-owned opaque Workflow admission owner, admission-before-hydration ordering, and FSMSession-integrated durable terminal save barrier with fail-closed uncertain outcomes.  Implementation ownership/delivery amended by [042-feature-owned-execution-state](042-feature-owned-execution-state.md). |
 | [`027-llm-adapter-provider-boundary`](027-llm-adapter-provider-boundary.md) | Accepted | Yes | Phronomy-owned Provider-call extension boundary; RubyLLM is the default adapter/integration while current input materialization remains RubyLLM-specific. |
 | [`028-preparing-recovery-replay-contract`](028-preparing-recovery-replay-contract.md) | Accepted | Yes | Adds replay-safe same-`execution_id` recovery for durably admitted Agent `:preparing` executions when replayability is durably established; unsupported Runtime-only dependencies fail closed. |
 | [`029-semantic-completion-and-application-effect-boundary`](029-semantic-completion-and-application-effect-boundary.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
-| [`030-agent-handoff-domain-and-durable-responsibility`](030-agent-handoff-domain-and-durable-responsibility.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
-| [`031-durable-multi-agent-coordination`](031-durable-multi-agent-coordination.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. |
+| [`030-agent-handoff-domain-and-durable-responsibility`](030-agent-handoff-domain-and-durable-responsibility.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. Runner ownership amended by [034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md); other V2 semantics remain. |
+| [`031-durable-multi-agent-coordination`](031-durable-multi-agent-coordination.md) | Accepted | Yes | V2 revision 2; framework semantic coordination and Application effect boundary. Runner ownership amended by [034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md); other V2 semantics remain. |
+| [`032-storage-backend-composition`](032-storage-backend-composition.md) | Accepted | Yes | Separates raw Storage contracts/backends from domain Persistence by composition; replaces the Persistence subclass SPI and its facade-building helper. ADR-014 single transaction domain and ownership guarantees remain; [033-domain-persistence-ownership](033-domain-persistence-ownership.md) refines codec/repository ownership. |
+| [`033-domain-persistence-ownership`](033-domain-persistence-ownership.md) | Amended | Yes | Domain-owned codecs, repositories, and result queries over the unchanged Storage SPI; explicit composition preserves one transaction domain. Error boundary refined by [043-storage-execution-constraint-notifications](043-storage-execution-constraint-notifications.md). |
+| [`034-handoff-runner-coordination-ownership`](034-handoff-runner-coordination-ownership.md) | Accepted | Yes | H1 moves the public HandoffRunner to MultiAgent; Agent execution, Handoff records, and Runtime shutdown semantics are preserved. Further Handoff separation is deferred. |
+| [`035-tool-executor-capability-ownership`](035-tool-executor-capability-ownership.md) | Accepted | Yes | T1 places the private default Tool executor beside Capability Base; public Tool identity, execution modes, Runtime injection, and Agent authorization/result ownership are preserved. |
+| [`036-context-contract-ownership`](036-context-contract-ownership.md) | Accepted | Yes | C1 groups Context Policy/hook contracts, values, Manifest representation, and Plan validation in a collapsed directory; public Agent constants, extension protocols, and stored formats are preserved. |
+| [`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) | 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. |
+| [`043-storage-execution-constraint-notifications`](043-storage-execution-constraint-notifications.md) | Accepted | Yes | Raw backends report Storage-owned active-execution conflicts; feature repositories preserve public busy errors within the same transaction. Beta raw error SPI migration. |
+| [`044-agent-default-and-one-shot-composition`](044-agent-default-and-one-shot-composition.md) | Accepted | Yes | Agent consumes an owner-defined fresh-Persistence factory; application composition selects the default and owns the unchanged one-shot API. |
+| [`045-worker-input-restriction-ownership`](045-worker-input-restriction-ownership.md) | Accepted | Yes | Each restricted type declares an execution-boundary marker; authorization input validation preserves the existing rejection and opaque application-value contracts without enumerating feature types. |
+| [`046-agent-responsibility-layout-and-shared-records`](046-agent-responsibility-layout-and-shared-records.md) | Amended | Yes | Agent responsibility directories preserve constants; shared record encoding, saved context reads and live restoration have separate owners. Continuation control refined by [047-recovered-execution-continuation-contract](047-recovered-execution-continuation-contract.md); deferred SharedState ownership resolved by [053-shared-state-coordination-ownership](053-shared-state-coordination-ownership.md). |
+| [`047-recovered-execution-continuation-contract`](047-recovered-execution-continuation-contract.md) | Accepted | Yes | Recovery hands semantic commands to the execution owner; EventLoop identity/revision checks and shared session registration replace private control calls. |
+| [`048-dispatch-preparation-worker-ownership`](048-dispatch-preparation-worker-ownership.md) | Accepted | Yes | Dispatch worker owns prerequisite persistence and readback; the execution owner retains EventLoop validation, apply and dispatch. Operation-specific boundaries and purpose-level method bodies are preserved. |
+| [`049-initial-preparation-worker-ownership`](049-initial-preparation-worker-ownership.md) | Accepted | Yes | Initial preparation and preparing recovery share a persistence worker; admission outcomes, commit certainty and EventLoop ownership stay distinct. Pure failure classification is shared without sharing transaction control. |
+| [`050-approval-resume-snapshot-and-commit-ownership`](050-approval-resume-snapshot-and-commit-ownership.md) | Accepted | Yes | Validated approval commands own immutable recovery snapshots. A worker commits decision, Execution and Root; the execution owner retains admission, live state and session resumption. |
+| [`051-execution-outcome-worker-ownership`](051-execution-outcome-worker-ownership.md) | Accepted | Yes | Ordinary and Handoff outcome workers own atomic persistence and operation-specific readback; EventLoop retains result authority and delivery. |
+| [`052-tool-invocation-restoration-ownership`](052-tool-invocation-restoration-ownership.md) | Accepted | Yes | ToolInvocation owns saved state application; Recovery retains snapshot decoding and identity matching. Existing restoration and replay rules are preserved. |
+| [`053-shared-state-coordination-ownership`](053-shared-state-coordination-ownership.md) | Accepted | Yes | Moves Experimental SharedState and its invocation-local store to MultiAgent without an old-name alias; preserves coordination behavior and generated definition identity. Resolves the deferred SharedState ownership in ADR-046. |
+| [`054-workflow-terminal-save-single-owner`](054-workflow-terminal-save-single-owner.md) | Accepted | Yes | Consolidates the active F1-aware terminal save in WorkflowRunner and removes its private prepend override. Amends ADR-038 loading; preserves the durable barrier and leaves FSMSession policy ownership as separate work. |
+| [`055-terminal-observer-failure-settlement`](055-terminal-observer-failure-settlement.md) | Accepted | Yes | Keeps the error path open until terminal stable notification returns. Observer failure settles the caller and releases admission without retrying or undoing an already confirmed save. Clarifies ADR-026; W2b ownership extraction remains separate. |
+| [`056-workflow-terminal-policy-ownership`](056-workflow-terminal-policy-ownership.md) | Accepted | Yes | Workflow owns persistence-result interpretation through a private policy; Engine retains generic session gating and complete/fail/retire actions. Preserves ADR-026/055 ordering and uncertainty without a public plugin API. |
+| [`057-storage-transaction-boundaries`](057-storage-transaction-boundaries.md) | Accepted | Yes | Enforces active-owner exclusion on InMemory updates, validates SQL Journal batches before writes and defines explicit nested savepoints with propagated failures. Preserves the existing SPI and record formats; the neutral SPI remains separate work. |
+
+| [`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`
 
@@ -174,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/design/durable-semantic-coordination/IMPLEMENTATION_DESIGN_V2.md

@@ -1,5 +1,11 @@
 # Phronomy Durable Semantic Coordination — Implementation Design V2
 
+> Runner namespace update (2026-09-18): this document preserves the V2
+> implementation/migration record. The current Runner is
+> `Phronomy::MultiAgent::HandoffRunner` under
+> [ADR-034](../../decisions/034-handoff-runner-coordination-ownership.md).
+> Handoff and HandoffPolicy remain in Agent at this stage.
+
 ## 0. Status and authority
 
 **Accepted implementation design — V2 revision 2 (2026-09-06).**

data/docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md

@@ -1,5 +1,11 @@
 # Durable Semantic Coordination V2 revision 2 — Implementation report
 
+> Runner namespace update (2026-09-18): this document preserves the V2
+> implementation/migration record. The current Runner is
+> `Phronomy::MultiAgent::HandoffRunner` under
+> [ADR-034](../../decisions/034-handoff-runner-coordination-ownership.md).
+> Handoff and HandoffPolicy remain in Agent at this stage.
+
 作成日: 2026-09-07。設計承認日: 2026-09-06。
 対象baseline: `5472116cd99a63ec27875024c955ea82be612d6b`。
 承認済みADR-029/030/031とRC-01〜05に対する新規実装です。

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/features.md

@@ -20,7 +20,7 @@ for production deployments.
 | **Workflow** — Stateful, branching workflows with `wait_state` and explicit events | Stable |
 | **Agent** — Stateful ReAct-style agents with stable `agent_id`, one mutable live owner per Runtime, persistence-backed execution state, canonical history, and conversation context | Stable |
 | **Tool authoring façade** — `Phronomy::Tool::Base` is the public authoring name for the existing Capability base class; the legacy namespace remains compatible | Beta |
-| **Unified Persistence** — One durable backend abstraction for Agent state and Workflow `workflow_states`; live Agent/Workflow state remains owned by Runtime/session authority between durable commits; custom backends implement the documented Backend SPI and repository/transaction semantics | Beta |
+| **Unified Persistence** — One transaction domain for Agent, Team, and Workflow state; a domain-facing `Persistence` composes a record-oriented `Storage::Backend`; live Agent/Workflow state remains owned by Runtime/session authority between durable commits; custom backends implement the documented Backend SPI, including Storage-owned active-execution constraint notifications translated by domain repositories, and repository/transaction semantics | Beta |
 | **LLMAdapter SPI** — `Phronomy::LLMAdapter::Base#complete` / `#stream` define the Beta call-adapter extension boundary; Phronomy owns async/offload wrapping | Beta |
 | **Before-Large-Language-Model (LLM) Input Hook** — Three-tier per-call LLM input customization via `before_llm_input` and `LLMInputPatch` | Stable |
 | **Context Management** — Journal + Context Policy + per-LLM-call Manifest with token-budget-aware selection and protocol-safe Tool Call / Tool message dependencies | Stable |
@@ -46,12 +46,17 @@ 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 |
 | **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 |
@@ -79,14 +84,20 @@ rather than implicitly inheriting the parent revision. The Stable
 
 ## Agent and workflow patterns
 
+Agent Tool batches use a single ordinary RubyLLM chat path. Agent owns Tool
+authorization, dispatch and the barrier before the next Provider request;
+concurrency remains governed by Tool execution modes and Runtime capacity.
+The obsolete `parallel_tool_execution` configuration accessor has been removed.
+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 Agent Handoff** — `Agent::Handoff` and `Agent::HandoffRunner` persist responsibility, immutable Context and exact Target reservation in one Persistence domain; current graph wiring is required for continuation | 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 |
-| **SharedState** — Peer-agent shared-state coordination | Experimental |
+| **`Phronomy::MultiAgent::SharedState`** — Sequential peer-agent coordination through an invocation-local findings store; see the [namespace migration](migrations/shared-state-multi-agent.md) | Experimental |
 | **Human-in-the-loop approval** — durable suspension publishes `:approval_required` through the Agent listener; `approve` / `approve_async` resumes the same logical `execution_id` with a fresh FSMSession incarnation | Beta |
 | **`tool_approval_policy`** — Application-defined allow/approve/reject policy using a value-only `ApprovalEvaluationRequest` without live Agent/Tool references | Beta |
 

data/docs/getting-started.md

@@ -50,7 +50,7 @@ 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
+exact alias of the existing `Phronomy::Tool::Base`, so
 existing Tool definitions using the longer namespace remain compatible.
 
 ```ruby
@@ -85,7 +85,7 @@ application does not need to pass the previous `messages` array back into every
 invocation.
 
 ```ruby
-persistence = Phronomy::Persistence::InMemory.new
+persistence = Phronomy::PersistenceComposition.agent
 
 agent = ResearchAgent.create(
   agent_id: "research-session-42",
@@ -115,7 +115,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
-`Persistence::NotFoundError`.
+`Storage::NotFoundError`.
 
 Use `get` when only a process-local lookup is wanted:
 
@@ -131,7 +131,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 `Persistence::ConflictError` rather than
+external durable write is surfaced as `Storage::ConflictError` rather than
 silently merged into the live instance.
 
 The active transcript and Knowledge views can be advanced independently without
@@ -250,7 +250,7 @@ end
 write_draft  = ->(state) { state.merge(draft: "Draft content") }
 review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
 
-persistence = Phronomy::Persistence::InMemory.new
+persistence = Phronomy::PersistenceComposition.in_memory.workflow
 
 workflow = Phronomy::Workflow.define(
   ReviewContext,
@@ -274,7 +274,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,12 +286,15 @@ 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.

data/docs/migrations/0.15.md

@@ -16,6 +16,11 @@ follow the current contracts documented in
 | `InvocationContext#provider_limits` | Configure the provider client directly |
 | `stream_queue_max_size` | No replacement; the shared EventLoop queue is unbounded by design. Monitor `Metrics.snapshot[:event_loop_queue_depth]` instead |
 
+The historical `parallel_tool_execution` switch mentioned above was subsequently
+removed by the architecture refactor. Current code should follow the
+[Chat migration guide](parallel-tool-chat-removal.md); it is not an on/off
+control for Agent Tool concurrency.
+
 ## Timeout ownership
 
 Phronomy owns logical lifecycle deadlines and cooperative cancellation. Provider,

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,13 @@
 # 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
+> [ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).
+> Handoff and HandoffPolicy remain in Agent at this stage.
+
 This Beta clean break applies to baseline `5472116cd99a63ec27875024c955ea82be612d6b`.
 
 | Previous surface | Current surface |

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

@@ -0,0 +1,37 @@
+# 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.
+
+| Previous API | API on this refactoring branch |
+|---|---|
+| `Phronomy::Agent::HandoffRunner` | `Phronomy::MultiAgent::HandoffRunner` |
+| `Phronomy::Agent::Handoff` | Unchanged |
+| `Phronomy::Agent::HandoffPolicy` | Unchanged |
+
+The previous Runner name is removed without an alias. Update direct `require`
+paths from `phronomy/agent/handoff_runner` to `phronomy/multi_agent/handoff_runner`
+if used; ordinary `require "phronomy"` continues to use Zeitwerk.
+
+Runner initialization still accepts `main_agent:` and `handoffs:`. Its `invoke`,
+`cancel` and `result` methods, `main_agent`/`handoffs` readers and `MAX_HANDOFFS`
+constant retain their behavior. Existing Handoff edges and Policy objects remain
+in the Agent namespace during this first step.
+
+Update the core and examples together. When using examples from the corresponding
+refactoring branch, set `PHRONOMY_PATH` to the matching local core checkout before
+resolving bundles or running verification. The examples API preflight rejects an
+older core and checks exact removed constants without mistaking
+`MultiAgent::HandoffRunner` for `MultiAgent::Handoff`.
+
+No persisted-record migration or SQL schema change is required. Existing
+HandoffState, Context and execution records are read using the same format,
+identity and revision rules. Recovery still requires compatible current Agent
+definitions and Handoff graph wiring; changing the Runner namespace does not
+relax that requirement.
+
+The ownership rationale and remaining work are recorded in
+[ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).

data/docs/migrations/neutral-storage-spi.md

@@ -0,0 +1,43 @@
+# Migrating to neutral Storage SPI 2 (Refactor 35)
+
+Apply matching core and examples changes together. Existing SQL databases need
+no schema or payload migration. Applications continue using Persistence domain
+repositories. Direct Backend implementations and callers must migrate.
+
+| Previous extension point | SPI 2 |
+|---|---|
+| Eight repository keywords to Backend | `resources: [Resource, ...]` |
+| `backend.agents`, `backend.executions`, etc. | `backend.view.records(resource)`; domain names stay on Persistence |
+| Journal raw repository | `view.streams(resource)` with `Entry::Append` inputs |
+| Raw ContentStore repository | `view.blobs(resource)`; `ContentStore::StoredContents` owns digest behavior |
+| `Storage::Repositories` transaction view | `Storage::View` bound to a transaction scope |
+| `assert_agent_watermark!` on raw Backend | Agent-owned Watermark composes GuardRef, RevisionIs and StreamHeadIs |
+| ActiveExecutionConflictError | UniqueConstraintError with exact resource/constraint; NoRows condition for idle |
+| Three domain-named raw capabilities | spi_version 2 and six neutral capabilities |
+
+A driver implements the protected physical operations used by Records, Streams,
+Blobs and guards, plus `storage_transaction`. Reuse the common scope lifecycle;
+do not override `transaction` with a view that bypasses it. Return independent
+Entry values and never decode domain payload to reconstruct index metadata.
+A non-subclass backend must provide the same public protocol and semantics.
+The SQL reference driver receives immutable physical mappings independently of
+resource declarations; no resource-ID case switch selects domain SQL behavior.
+
+Repository wrappers obtained inside a transaction expire with that transaction.
+Do not retain them in application objects. Cache root repositories/handles when
+needed: they route to the current transaction on the same thread. Recover from
+an operation failure only outside an explicit inner savepoint. Catching a failure
+inside its failed scope prevents further work and commit. Complete transaction
+blocks normally; return/break/throw raises TransactionError after rollback.
+
+Initial Workflow/Handoff saves still use expected_revision nil and return the
+existing domain result. Storage Records itself requires explicit insert versus
+replace. Missing required parent records now consistently raise NotFoundError;
+this closes prior InMemory/SQLite/PG differences for orphan raw writes. Nonempty
+keys and text attributes must be valid UTF-8 without NUL. Nullable unique keys
+are distinct. Domain Journal limit zero remains an empty result.
+
+Run the shipped domain and neutral conformance suites, the dedicated SPI 2/RBS
+checks and each physical driver's concurrency/failure tests. For PostgreSQL run
+the real server gate with the matching candidate core, then verify fresh-pool
+reload. Existing S2a CI is historical evidence, not validation of this SPI.

data/docs/migrations/parallel-tool-chat-removal.md

@@ -0,0 +1,49 @@
+# Removal of the internal parallel Chat path
+
+This change belongs to the incremental architecture refactor following 0.26.0.
+It does not publish a new gem version.
+
+## Application changes
+
+Remove assignments to `Phronomy.configuration.parallel_tool_execution`, including
+assignments inside `Phronomy.configure`. Both the reader and writer are removed;
+there is no compatibility accessor or replacement switch. The former setting
+selected a Chat subclass but did not gate concurrency in the Agent-owned Tool
+execution path. A previous value of `false` did not guarantee serial execution.
+
+`Phronomy::MultiAgent::ParallelToolChat` and its file are removed. Do not require
+the old file or instantiate that private class. No `Agent::ParallelToolChat`
+replacement or alias is introduced. Applications that need Agent-owned Tool
+approval, cancellation and execution tracking should enter through the Agent
+invoke/stream APIs. Direct RubyLLM chat use is outside that Agent lifecycle.
+
+## Retained behavior
+
+Both complete and streaming calls use ordinary `RubyLLM::Chat`. Before the first
+Tool body runs, the existing RubyLLM callback lets Agent capture every Tool call
+in the complete assistant message. Agent manages Tool authorization, approval,
+dispatch, cancellation and result collection under ADR-010 and ADR-024.
+
+On success, every result is associated with its original call ID and recorded
+in request order. All results are included in the next Provider request, after
+the batch completes. Runtime capacity and each Tool's execution mode still
+determine how work can overlap. This change does not introduce a serial Tool
+mode or a partial-result Provider continuation.
+
+The old direct-Chat fallback and its RubyLLM-specific callback/Halt behavior are
+removed with the private class. They are not a second supported Agent execution
+API. Agent-level event callbacks keep their existing contract.
+
+## Existing stored records
+
+New standard model-config records omit `parallel_tool_execution`. Existing
+ContentStore records and manifest hashes are not rewritten. An existing record
+may still contain that field; materialization preserves its bytes and Agent's
+Chat builder ignores it, just as it ignores other unused model-config fields.
+There is no manifest version change or compatibility branch that reinstates the
+removed Chat class.
+
+The regression suite checks materialization and Chat construction for stored
+records containing both historical boolean values. Existing recovery tests
+continue to cover the supported recovery contracts; this change does not add
+execution-resumption or external-effect guarantees.

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.

data/docs/migrations/r8-unit11.md

@@ -0,0 +1,33 @@
+# Migrating to r8 unit 11
+
+Apply after core eaff581cb8806c707d47649bb561b70690fa9e57 (unit 10).
+This package changes core only. The unit 6 examples at
+ed455c52018338f7c5a4c2948ae0d7db131aa090 require no source changes.
+
+No application API changes or database migrations are required. Continue to
+load the library with require "phronomy" and use the existing context_policy
+DSL for explicit policies. The boot composition installs DefaultPolicy through
+that same DSL. Reading an unconfigured internal Base now fails explicitly
+instead of selecting a concrete Policy inside Agent.
+
+| Private implementation use | Replacement |
+| --- | --- |
+| Agent::Base concrete Policy fallback | runtime_composition/agent_defaults.rb installs the default |
+| InvocationActions constructs LLMAdapter::AsyncClient | Its captured environment.build_llm_client(adapter: ...) |
+| Agent LLM submission resolves the current global Runtime | EngineEnvironment binds the client to its retained Runtime |
+| AsyncClient constructor | Optional submitter: using existing _ExecutionSubmitter; existing arguments still work |
+
+Internal custom ExecutionEnvironment implementations must supply the new client
+capability. It is not a supported application extension API. Clients created
+without an injected submitter preserve their default Runtime behavior; explicit
+pool arguments preserve precedence. Changing the global default Runtime does
+not migrate an existing Agent's resources. Follow the existing stop/drain and
+recreate procedure when replacing running processes.
+
+The ZIP contains complete changed files, strict-base application and expected-tree
+verification, a review patch, test evidence and recovery instructions. Run
+--check, --apply and --verify in a new worktree, then --verify after commit.
+
+For examples verification, unset BUNDLE_GEMFILE before entering the examples
+checkout and set PHRONOMY_PATH to this core. Inspect and restore only generated
+lockfile/vendor changes; no examples commit is needed.