phronomy 0.25.0 → 0.27.0

data/docs/decisions/058-neutral-storage-primitives.md

@@ -0,0 +1,78 @@
+# ADR-058: Neutral Storage primitives and scoped transactions
+
+## Status
+
+Accepted. Applied and verified in Refactor 35 (Storage S2b/S2c), core
+`ebd99623f94c8b2db2d74355bfa39f01550778a0` and examples
+`68a0bbd0e354b9e00bbfed728ad2b769b389ed8a`.
+
+## Context
+
+S1 inventoried 37 raw methods across eight required domain slots. Moving their
+classes did not remove Agent watermark or active-owner policy from shared
+storage. S2a fixed concrete transaction and update differences first. S2b now
+changes the extension contract while preserving domain APIs and durable data.
+
+## Decision
+
+1. Replace the eight-slot Backend/Repositories SPI with declared Resources and
+   Records, Streams, Blobs accessed through View. Storage has no domain codecs,
+   active-execution interpretation, content digest or Agent watermark method.
+2. Keep schemas, encoding, initial revisions, active-state interpretation and
+   metadata validation in their features. Composition gathers declarations and
+   builds domain wrappers. Team/Workflow schema loader roots do not load runtime.
+3. Use named equality indexes, conditional unique constraints, immutable metadata,
+   revision CAS, stream head CAS and a closed guarded-condition set. Parent guards
+   precede child locks. Required parent absence is uniformly NotFoundError.
+4. Keep one transaction domain, scoped views, same-connection savepoints and root
+   handle routing. Reject expired/cross-thread views and failed physical scopes.
+   Reject non-local block exits with TransactionError and rollback. A successful
+   optional read returning nil is not a failed physical operation.
+5. Report neutral UniqueConstraintError(resource ID, constraint name) and
+   ConditionFailedError(condition). Only owning domain repositories map exact
+   active constraints to AgentBusyError. Remove the old domain-named error alias.
+6. Share neutral SQL operations in examples/shared/storage, with explicit dialect
+   differences and separate domain/table composition. Keep all existing tables,
+   indexes, envelope formats, payloads, IDs and content bytes. Nullable unique-key
+   fields are distinct, matching SQL default uniqueness semantics.
+
+## Supersession scope
+
+This amends ADR-032's raw eight-slot contract, ADR-033's remaining fixed raw
+boundary, ADR-043's domain-named raw exception and ADR-057's old-SPI-only limit.
+Their domain ownership, composition, savepoint and uncertainty decisions remain.
+No historical artifact is silently reinterpreted as a current SPI specification.
+
+## Public contract and migration
+
+Persistence's constructor, in_memory, eight accessors, result queries and public
+capabilities remain. Backend SPI 2 is intentionally breaking; legacy duck-typed
+backends fail capability validation. There is no compatibility facade or alias.
+See the [contract](../persistence-backends.md), [migration guide](../migrations/neutral-storage-spi.md),
+RBS and explicit SPI 2 snapshot. Ordinary product API snapshots remain separate.
+
+## Validation and remaining gates
+
+Shared conformance tests cover opaque data, CAS, named constraints, parents,
+Unicode cursor ordering, streams, binary blobs, all-resource rollback, nested
+savepoints, view lifetime, thread confinement and non-local exits. Domain tests
+retain F0/F1/F4 behavior and X0 limitations. SQLite old/new/old round-trip checks
+cover all eight resources and unchanged schema. The applied SPI 2 pair passed
+[PostgreSQL 17.11 CI](https://github.com/Raizo-TCS/phronomy-examples/actions/runs/35827495677)
+on Ruby 3.2/3.3/3.4, with 119 examples per version and fresh-pool reload. Both
+checkout SHAs were verified. Earlier SPI CI was not used as substitute evidence.
+No stronger commit certainty, distributed Workflow admission or external-effect
+retry is introduced.
+
+## S3 internal responsibility clarification
+
+Refactor 36 keeps all public SPI 2 signatures and Resource identity rules.
+Resource normalizes a schema object or resource ID before GuardRef/Condition
+construction; the cooperation method is `@api private`, not a new backend
+extension point. Generic Validation handles scalar validation and copying and
+must not depend on Resource. View still enforces catalog membership and exact
+schema identity. This removes the internal Resource/Validation cycle without
+changing a public name, transaction, stored record or physical backend.
+
+See the [closure review](../architecture/refactoring-closure.md) for retained
+placements and the separate distribution application gate.

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,43 @@ 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) | 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. |
+| [`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. |
 
 ## Legacy duplicate `011`
 

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/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,8 +46,8 @@ 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 `Task`; native async override is not part of the current Backend SPI | Beta |
-| **Embedding async convenience** — `embed_async` offloads synchronous `embed` through Phronomy and returns `Task` | 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 |
 | **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 |
@@ -64,10 +64,12 @@ rather than implicitly inheriting the parent revision. The Stable
 | **Agent async events** — one Runtime-only `on_event` listener is bound at Agent `new` / `create` / `load`; invoke/stream operations publish through that listener and streaming additionally emits `:token` | Beta |
 | **`stream` / `stream_async`** — Event callbacks execute on EventLoop and must return quickly | Beta |
 | **`stream_callback_error_policy`** — Terminal event callback error policy (`:report` / `:fail_task`) | Beta |
-| **Task completion contract** — `Task` is the common caller-facing completion handle for EventLoop/FSMSession lifecycles and OffloadPool work | Beta |
-| **`Task#map`** — Application-level Task result transformation and error propagation | Stable |
-| **Settled Task factories** — Public `Task.completed` / `Task.failed` represent already available application results without starting execution | Beta |
-| **Blocking.call_async** — Public non-waiting admission of synchronous application work to the existing OffloadPool, returning a Task | Beta |
+| **TaskResult completion contract** — `TaskResult` is the common caller-facing completion handle for EventLoop/FSMSession lifecycles and OffloadPool work | Beta |
+| **`TaskResult#map`** — Application-level TaskResult result transformation and error propagation | Stable |
+| **`TaskResult#flat_map` / `.all_settled`** — Asynchronous chaining and input-order observation of terminal results | Beta |
+| **`Execution.run_async` / `.run`** — Common runtime fan-out/fan-in with whole-execution controls and immutable outcome snapshots | Beta |
+| **Settled TaskResult factories** — Public `TaskResult.completed` / `TaskResult.failed` represent already available application results without starting execution | Beta |
+| **Blocking.call_async** — Public non-waiting admission of synchronous application work to the existing OffloadPool, returning a TaskResult | Beta |
 | **CancellationToken** — Cooperative cancellation with explicit `cancel!`, lazy monotonic deadlines, and callback registration | Experimental |
 | **Tool `execution_mode`** — `:cooperative` for short EventLoop-safe work; `:offloaded` for synchronous work that must stay off EventLoop | Experimental |
 | **OffloadPool sizing** — `offload_pool_size` / `offload_queue_size`; named pools available for application-owned isolation | Beta |
@@ -77,14 +79,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** — `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 |
 | **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 |
 
@@ -107,11 +115,11 @@ visibility still follows the intended calling model. `@api private` means
 declaration; some internal methods remain Ruby-public because Phronomy components
 call them through explicit receivers.
 
-`Task` is the caller-facing completion abstraction. Framework components own
+`TaskResult` is the caller-facing completion abstraction. Framework components own
 settlement (`complete` / `fail` / `cancel!`); application code observes Tasks via
 `wait_result`, `on_complete`, `map`, and state readers. Operation-wide cancellation
 is requested through the `CancellationToken` accepted by the API that created the
-Task.
+TaskResult.
 
 Persistence Backend SPI methods, LLMAdapter methods, and other documented
 extension contracts are deliberate exceptions to the ordinary
@@ -147,7 +155,8 @@ private execution machinery, see [Runtime and concurrency](runtime-and-concurren
 
 Static `Orchestrator.subagent` Tools invoked inside a parent AgentExecution reserve
 child Agent/execution identities before dispatch and reuse retained outcomes.
-Direct `dispatch_parallel` / `fan_out` calls remain Runtime-only convenience APIs.
+Direct `dispatch_parallel` calls retain Agent-specific policy and use the common
+runtime Execution engine. The redundant `fan_out` / `fan_out_async` APIs are removed.
 `Orchestrator#resume(execution_id)` continues retained parent coordination.
 
 `TeamCoordinator` requires `team_definition id:, version:` and provides

data/docs/getting-started.md

@@ -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::Persistence.in_memory
 
 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
@@ -180,13 +180,13 @@ 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
 is also an error; the existing binding is immutable for that Runtime incarnation.
 
-`Phronomy::Task` is the common caller-facing completion handle for asynchronous
+`Phronomy::TaskResult` is the common caller-facing completion handle for asynchronous
 Phronomy work. Logical lifecycle progress is driven by EventLoop/FSMSession;
 synchronous work that must execute away from EventLoop is submitted to
-OffloadPool. Both paths expose completion as a `Task`.
+OffloadPool. Both paths expose completion as a `TaskResult`.
 
-`Task#wait_result` is for an external caller. Do not block EventLoop waiting for
-a Task that can only complete through that same EventLoop.
+`TaskResult#wait_result` is for an external caller. Do not block EventLoop waiting for
+a TaskResult that can only complete through that same EventLoop.
 
 Streaming uses the same Agent-incarnation listener:
 
@@ -208,7 +208,7 @@ EventLoop and therefore should return quickly.
 ## Human-in-the-loop approval
 
 A Tool requiring approval suspends the durable logical execution without
-settling the original execution Task. Approval notification is delivered
+settling the original execution TaskResult. Approval notification is delivered
 through the same Agent listener as `:approval_required`:
 
 ```ruby
@@ -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::Persistence.in_memory
 
 workflow = Phronomy::Workflow.define(
   ReviewContext,
@@ -349,7 +349,7 @@ workflow = Phronomy::Workflow.define(AnswerContext) do
 end
 ```
 
-Returning a `Phronomy::Task` from a Workflow entry/transition action is not an
+Returning a `Phronomy::TaskResult` from a Workflow entry/transition action is not an
 implicit await mechanism and is rejected.
 
 ## Agent as Tool

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/durable-semantic-coordination-v2.md

@@ -1,5 +1,11 @@
 # Durable semantic coordination V2 migration
 
+> 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 |
@@ -42,7 +48,7 @@ results without hydration/callbacks. `Persistence#handoff_result(source_id)`
 follows the exact transfer chain without constructing a graph or Agent owners. `Orchestrator#resume(id)` continues existing
 static subagent coordination. There is no global generic class registry.
 
-Observer Task wait timeouts and shutdown do not request cancellation. Team's
+Observer TaskResult wait timeouts and shutdown do not request cancellation. Team's
 `cancel(run_id)` persists a run-scoped request before forwarding its live token;
 resume settles exact children or returns the existing rehydration error. Handoff's
 `cancel(execution_id)` follows only that turn. A cancellation token passed to

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

@@ -0,0 +1,35 @@
+# HandoffRunner moves to MultiAgent
+
+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/shared-state-multi-agent.md

@@ -0,0 +1,44 @@
+# SharedState moves to MultiAgent
+
+This change applies to the architecture refactoring branch after core commit
+`aa9c3d53090bda4deb01b8cab16a43539b6b1deb`. Use the matching core and examples
+checkouts; the unchanged gem version number alone does not identify this API.
+
+| Previous Experimental API | API after this change |
+|---|---|
+| `Phronomy::Agent::SharedState` | `Phronomy::MultiAgent::SharedState` |
+| `Phronomy::Agent::SharedState::KnowledgeStore` | `Phronomy::MultiAgent::SharedState::KnowledgeStore` |
+
+The previous name is removed without an alias. Update superclass declarations
+and explicit constant references. For example:
+
+```ruby
+require "phronomy"
+
+class ResearchTeam < Phronomy::MultiAgent::SharedState
+  member Researcher
+  max_cycles 3
+end
+```
+
+Use the public application entry point `require "phronomy"`. The old internal
+file `phronomy/agent/shared_state.rb` is removed; arbitrary implementation-file
+requires are not a supported partial-loading API.
+
+The DSL, `invoke(input, config: {})` signature, sequential order, shared findings,
+termination rules and `{output:, cycles:, terminated_by:}` result remain the same.
+`config:` remains accepted but is not forwarded to member invocations. Timeout
+is checked between complete cycles and does not cancel an active Agent.
+
+Set `PHRONOMY_PATH` to the matching local core checkout before running
+`bundle install` or the examples verification. Example `22_shared_state` now
+uses the new superclass, and the examples API preflight rejects mismatched core.
+
+No saved-record or SQL schema migration is required. Do not rewrite the existing
+`Phronomy::Agent::SharedState::Instrumented/` generated definition ID: it is
+deliberately preserved together with instrumentation version 1. It is not an
+alias for the removed Ruby constant. The in-memory KnowledgeStore still lasts
+for one invocation only.
+
+See [ADR-053](../decisions/053-shared-state-coordination-ownership.md) for the
+ownership and compatibility decision.