phronomy 0.26.0 → 0.27.0

data/docs/architecture.md

@@ -41,6 +41,215 @@ explicit compatibility decision.
   dependency minimization must not weaken accepted durability,
   ownership, security-boundary, or extension contracts.
 
+## Responsibility groups and dependency graphs
+
+Dependency views describe a directed graph of responsibility groups, not a
+tree or a single pipeline. Several distinct groups may share one horizontal
+band. A band's height expresses a proposed abstraction level; it does not imply
+that its groups are independent or that every valid dependency points down.
+
+Assess each dependency by the referenced contract and its owner. Shared value
+types, extension contracts, and collaboration within a component can justify
+dependencies between groups. A directory containing both shared definitions and
+concrete orchestration must be examined by responsibility before assigning it a
+single position. Cycles and upward arrows are review evidence, not defect counts.
+
+The FSM terminal marker illustrates this distinction. `FSMProtocol::FINISH`
+owns the internal `:__end__` marker used by the session and Workflow compilers.
+The public Workflow DSL continues to use `:__finish__`. The execution session
+and phase compiler do not depend on `WorkflowRunner` for this shared vocabulary;
+the Workflow builder still legitimately creates its runner.
+
+Context Policy and hook contracts provide another example. The shared values,
+Manifest representation, and Plan validation live in `agent/context_contract/`,
+separately from concrete policies and Agent execution. Zeitwerk collapses that
+directory to preserve the existing `Phronomy::Agent` constants. A Policy's
+dependency on those contracts does not make it depend on Agent execution. See
+[ADR-036](decisions/036-context-contract-ownership.md).
+
+### Common definitions
+
+`common/` owns general definitions shared across the framework that do not
+belong to a particular feature. They must not depend on concrete Agent,
+Workflow, Runtime, or other feature implementations. Being used in several
+places, or inheriting a common base class, does not by itself make a definition
+common; feature-owned contracts remain with their owners.
+
+This group contains `Phronomy::Error`, `Phronomy::ConfigurationError`,
+`Phronomy::CanonicalJSON`, and `Phronomy::Values::Immutable`. Zeitwerk collapses
+`common/`, preserving these canonical names without introducing a
+`Phronomy::Common` namespace. Other exceptions belong to their feature
+contracts. `configuration/` owns settings and scalar defaults. The concrete
+adapter and tracer defaults are selected in `runtime_composition/`, which binds
+fresh-instance factories consumed by `Configuration.new`. This keeps concrete
+feature selection outside settings while preserving application behavior.
+Application Runtime reset and configuration replacement are also coordinated in
+`runtime_composition/`, separately from configuration access and Engine mechanics.
+See [ADR-039](decisions/039-runtime-configuration-lifecycle-ownership.md) and
+[ADR-040](decisions/040-configuration-default-composition.md).
+See [ADR-037](decisions/037-common-definition-ownership.md) and
+[ADR-038](decisions/038-responsibility-based-source-layout.md).
+
+### Source placement and loading
+
+`lib/phronomy.rb` is the application loading entry point. Internal production
+files must not require it. Feature implementations and contracts live in their
+responsibility directories; the direct root contains only `version.rb` and the
+small namespace/loading files enumerated in ADR-038.
+The separately documented external backend-test entry
+`phronomy/testing/persistence_contract` retains its existing opt-in loading
+contract and is excluded from production automatic loading.
+
+Engine owns Event, Execution composition and its outcome exceptions, and the
+synchronous FSM callback exceptions. Recovery owns shared rehydration
+requirements. Workflow implementation lives under `workflow/execution/`;
+Agent namespace/event loading lives under `agent/api/`, separately from the shared
+Agent lifecycle exceptions in `agent/lifecycle_contract/`. LLM values and
+call-boundary exceptions live under `llm_contract/`.
+
+Agent consumes its private fresh-Persistence factory only when neither an
+explicit instance nor a configured instance is available. Concrete selection
+and binding live in `runtime_composition/agent_defaults.rb`. The one-shot
+`Agent.run_once` method is defined in `agent/composition/run_once.rb`, because it
+explicitly composes Agent and fresh ephemeral Persistence on every call.
+The application entry loads both composition files; Agent execution and
+namespace loading do not delegate upward to them. See
+[ADR-044](decisions/044-agent-default-and-one-shot-composition.md).
+
+Types excluded from authorization worker inputs declare the internal,
+methodless `Concurrency::WorkerInputRestricted` contract at their own
+definitions. ToolInvocation checks that execution-boundary contract rather
+than concrete Workflow types. The original restriction set and opaque
+application-value behavior are preserved; see
+[ADR-045](decisions/045-worker-input-restriction-ownership.md).
+
+Agent implementation files are grouped into lifecycle, execution, Tool execution,
+context assembly, journal, Handoff and recovery directories. These directories
+are collapsed, so existing Agent constant names remain unchanged. Journal encoding,
+saved context reads and live invocation restoration have separate internal owners;
+transaction and EventLoop state decisions remain with their callers. See
+[ADR-046](decisions/046-agent-responsibility-layout-and-shared-records.md).
+
+Recovery hands semantic continuation commands to the execution owner through
+its EventLoop delivery boundary. The owner checks current identity, revision
+and session state before applying them. `Agent::ExecutionSessionRunner` shares
+ordinary and recovered Agent/Tool session registration and reports completion
+back to the same coordinator; operation workers now own terminal persistence
+under its EventLoop result authority (ADR-051 below).
+See [ADR-047](decisions/047-recovered-execution-continuation-contract.md).
+
+InvocationRestorer decodes saved Tool snapshots, resolves the Tool Call and Tool,
+and matches approval evidence. The newly constructed ToolInvocation applies its
+own saved state through the internal `restore_state!` operation; Recovery no
+longer writes its instance variables. State application neither evaluates approval
+nor dispatches Tool execution. Existing recovery installation notifications and
+continuation rules are unchanged. See
+[ADR-052](decisions/052-tool-invocation-restoration-ownership.md).
+
+`Agent::DispatchPreparation` owns Provider/Tool dispatch prerequisites and their
+operation-specific readback. ExecutionCoordinator captures and submits inputs,
+then validates/applies results on EventLoop before dispatch. The worker's Provider
+entry separates record encoding, application ContextPolicy, prerequisite commit
+and post-commit materialization without changing transaction/rescue boundaries.
+Its input/result types are worker-owned; existing Coordinator constant paths are
+internal aliases, with changed canonical Ruby names. See
+[ADR-048](decisions/048-dispatch-preparation-worker-ownership.md).
+
+`Agent::InitialPreparation` owns initial durable admission, Context preparation,
+preparation failure persistence and replay from saved preparing inputs. Ordinary
+start and recovery share the admitted-preparation steps; Runtime admission,
+result validation, live-state apply and session delivery remain on EventLoop.
+The known failure base advances only after a successful commit response.
+`Agent::ExecutionFailure` shares the existing pure failure classification with
+terminal persistence; it does not own transactions or delivery. See
+[ADR-049](decisions/049-initial-preparation-worker-ownership.md).
+
+`Agent::ApprovalResumeCommit` persists approval decisions with operation-owned
+Tool recovery snapshots. Coordinator validates the suspended owner and approval
+request before copying canonical snapshot values into the immutable Command;
+there is no shared snapshot lookup. The worker validates the target, stages
+recovery facts and commits decision/Execution/Root together. EventLoop retains
+admission, stale-result checks, live-state application and session resumption.
+An uncertain commit still requires recovery; it is not retried or treated as a
+confirmed resume. Internal Coordinator type aliases remain, with changed
+canonical names and an added Command snapshot field. See
+[ADR-050](decisions/050-approval-resume-snapshot-and-commit-ownership.md).
+
+`Agent::ExecutionOutcomeCommitter` owns ordinary completion, failure, suspension
+and child waiting; `Agent::HandoffOutcomeCommitter` adds atomic Source transfer.
+The Handoff Coordinator now only selects its worker. Transaction boundaries,
+operation-specific readback and Handoff selection precedence remain unchanged.
+Coordinator retains quiescence, submission, stale-result validation, live-state
+application, admission and Task/listener delivery. Command/view/outcome types are
+worker-owned with internal Coordinator aliases and changed canonical Ruby names.
+See [ADR-051](decisions/051-execution-outcome-worker-ownership.md).
+
+The remaining execution owner expresses result handling as validation, committed
+state installation, and continuation or delivery. Private methods keep these
+steps in Coordinator; they introduce neither another owner nor shared per-operation
+fields. The operation-specific authority checks and outer rescue boundaries stay
+at the result entry points. Start/resume admission and submission flags stay in
+the same methods as their cleanup decisions.
+
+| Owner entry | Purpose-level steps |
+| --- | --- |
+| Initial preparation recovery result | Validate preparing owner; restart the prepared session or settle its saved failure; complete the load observer |
+| Approval resume result | Validate suspended revision; install committed state and waiter; observe the task; resume the FSM |
+| Terminal result | Validate revision/session; handle commit uncertainty; apply state and acknowledge the snapshot; deliver the selected outcome |
+
+Terminal delivery releases ownership before notifying completed/failed/Handoff
+observers, then settles Tasks. Suspension keeps ordinary Tasks pending. Ordinary
+commit uncertainty keeps recovery admission and pending waiters; coordination
+errors retain their separate release-and-fail behavior. Session registration
+failure during preparation recovery still terminalizes without a live session;
+trace/resume failure still uses the newly installed execution revision.
+This is an internal readability refinement of ADR-024/047/051, not a change to
+persistence, recovery guarantees or public interfaces.
+
+Selected nested Zeitwerk roots retain existing top-level Phronomy constants
+without changing the enclosing feature's existing nested constants. For
+example, `Phronomy::WorkflowContext` and `Phronomy::WorkflowRunner` coexist with
+`Phronomy::Workflow::Persistence`. Workflow remains a class and its source
+file lives beside its implementation. These moves do not introduce aliases or
+a new public API for requiring arbitrary internal paths.
+
+WorkflowRunner directly owns terminal save submission and F1 snapshot readback.
+The former WorkflowRecovery prepend and shadowed save implementation are removed;
+the active path is independent of an installation hook. Private methods separate
+submission, save/reconciliation and result delivery. FSMSession still interprets
+the terminal persistence event; that ownership is a separate next step. See
+[ADR-054](decisions/054-workflow-terminal-save-single-owner.md) and the
+[remaining refactoring plan](architecture/remaining-refactoring-plan.md).
+The Agent entry explicitly preserves Agent lifecycle extension installation.
+Configuration accessors now live beside Configuration, rather than inside the
+loader. Configuration constructs fresh components through internally bound
+factories; composition selects their concrete types. Static source-reference
+graphs do not follow these injected calls. LLMAdapter's async bridge still uses
+Runtime, and other dependency cycles remain.
+
+Agent and Team implement their identity registries in `agent/` and
+`multi_agent/`. Runtime strongly retains one of each when registered, using only
+its generic shutdown participant contract. Feature code reserves identities,
+handles feature exceptions, and detaches owners after completed cleanup.
+See [ADR-041](decisions/041-feature-owned-identity-registries.md).
+
+Agent and Workflow also own their distinct execution registries. EventLoop
+retains them through Engine's internal `ExecutionReceiver` contract, dispatches
+queued messages and combines generic session/delivery counts with their idle
+predicates. Normal mutation remains on the EventLoop thread; only final
+invalidation after join runs on the management thread. EventLoop has no Agent
+or Workflow dispatch branch. See
+[ADR-042](decisions/042-feature-owned-execution-state.md).
+
+`MultiAgent::SharedState` owns sequential peer coordination through a findings
+store created for each invocation. It equips member Agents with shared-store
+Tools, runs complete cycles, checks stopping conditions and aggregates findings.
+It is not an individual Agent's durable state or execution coordinator. Its
+Experimental public namespace moves from Agent to MultiAgent without an alias;
+generated semantic definition IDs retain their previous values. See
+[ADR-053](decisions/053-shared-state-coordination-ownership.md) and the
+[migration guide](migrations/shared-state-multi-agent.md).
+
 ## Current architecture
 
 | Area | Current document |

data/docs/decisions/014-unified-persistence-durable-state.md

@@ -278,3 +278,14 @@ ambiguous.
 
 Rejected. Cleanup from an invocation that failed to acquire admission could then
 release the real owner's reservation. Release is owner-aware by construction.
+
+## Storage composition refinement (2026-09-17)
+
+[ADR-032](032-storage-backend-composition.md) refines the public storage boundary:
+`Persistence` is the domain-facing composed service and `Storage::Backend` is
+the raw storage extension contract. Backend inheritance from `Persistence`, the
+old raw-repository constructor, and `build_transaction_view` are replaced.
+Storage record/error constants move to `Storage`. The single atomic transaction
+domain, durable-state/live-owner split, and failure guarantees in this decision
+remain in force. Earlier API spellings in this decision are historical for this
+amended scope; use the current Backend contract and migration guide.

data/docs/decisions/024-event-loop-single-writer-agent-runtime.md

@@ -1,6 +1,10 @@
 # ADR-024: EventLoop Single-Writer Agent Runtime State
 
-**Status**: Accepted
+**Status**: Amended
+**Implementation ownership amendment**: [042-feature-owned-execution-state](042-feature-owned-execution-state.md) moves feature execution state and decisions to Agent/Workflow receivers; the EventLoop thread remains the single writer. Its registration, delivery and drain rules refine the original descriptions below.
+
+**Worker input classification amendment**: [045-worker-input-restriction-ownership](045-worker-input-restriction-ownership.md) replaces the concrete rejection list with an execution-boundary marker declared by each owning type. The existing value/behavior restrictions and application-owned opaque-value contract remain unchanged.
+
 **Date**: 2026-08-24
 **Partially supersedes**: [ADR-014](014-unified-persistence-durable-state.md) for live Agent Runtime ownership and `AgentExecutionActivation`
 **Complements**: [ADR-010](010-cooperative-first-concurrency.md), [ADR-012](012-canonical-execution-log-and-context-policy.md), [ADR-018](018-durability-guarantees-and-failure-model.md), [ADR-022](022-agent-execution-parent-identity-and-runtime-routing-boundary.md), [ADR-023](023-fsm-session-incarnation-identity-and-routing.md)

data/docs/decisions/025-process-local-agent-ownership-and-runtime-admission.md

@@ -1,7 +1,10 @@
 # ADR-025: Process-Local Agent Ownership and Runtime Admission
 
-**Status**: Accepted
+**Status**: Amended
+**Implementation ownership amendment**: [042-feature-owned-execution-state](042-feature-owned-execution-state.md) moves feature execution state and decisions to Agent/Workflow receivers; the EventLoop thread remains the single writer. Its registration, delivery and drain rules refine the original descriptions below.
+
 **Date**: 2026-08-24
+**Amended by**: [041-feature-owned-identity-registries](041-feature-owned-identity-registries.md) for registry implementation ownership and its generic Runtime shutdown contract
 **Partially supersedes**: [ADR-014](014-unified-persistence-durable-state.md) for same-process Agent live-instance ownership and top-level execution admission
 **Complements**: [ADR-018](018-durability-guarantees-and-failure-model.md), [ADR-022](022-agent-execution-parent-identity-and-runtime-routing-boundary.md), [ADR-023](023-fsm-session-incarnation-identity-and-routing.md), [ADR-024](024-event-loop-single-writer-agent-runtime.md)
 
@@ -43,8 +46,8 @@ live ownership service.
 
 ### One `agent_id` has one mutable live Agent owner per Runtime
 
-A Runtime owns a purpose-specific Agent ownership registry keyed only by
-`agent_id`:
+Agent owns the purpose-specific registry implementation, keyed only by
+`agent_id`; Runtime strongly retains one registered instance for its lifetime:
 
 ```text
 agent_id
@@ -63,6 +66,13 @@ The registry is separate from EventLoop's `execution_id -> AgentExecutionState`
 directory. Agent lifetime and Execution lifetime are different semantic
 lifetimes and must not be represented by one registry.
 
+The original implementation placed this registry under Runtime. ADR-041 moves
+it to `Agent::OwnershipRegistry` and removes the feature-specific Runtime
+forwarding methods. Runtime uses only the generic shutdown participant contract
+to close, wait for, and finally detach registered owners. The invariant and
+Runtime-scoped lifetime are unchanged; EventLoop admission is not moved by that
+amendment.
+
 ### Public Agent construction/resolution semantics
 
 The public operations have distinct meanings:

data/docs/decisions/026-workflow-runtime-admission-and-durable-terminal-barrier.md

@@ -1,6 +1,10 @@
 # ADR-026: Workflow Runtime Admission and Durable Terminal Barrier
 
-**Status**: Accepted
+**Status**: Amended
+**Implementation ownership amendment**: [042-feature-owned-execution-state](042-feature-owned-execution-state.md) moves feature execution state and decisions to Agent/Workflow receivers; the EventLoop thread remains the single writer. Its registration, delivery and drain rules refine the original descriptions below.
+**Observer failure clarification**: [055-terminal-observer-failure-settlement](055-terminal-observer-failure-settlement.md) keeps terminal observer errors on the ordinary failure path without undoing an already confirmed save.
+**Terminal policy ownership amendment**: [056-workflow-terminal-policy-ownership](056-workflow-terminal-policy-ownership.md) moves Workflow event/outcome interpretation to WorkflowTerminalPolicy while preserving the shared session, durable barrier and uncertainty lifecycle.
+
 **Date**: 2026-08-24
 **Partially supersedes**: [ADR-014](014-unified-persistence-durable-state.md) for same-process Workflow admission ownership and terminal durable-barrier ordering
 **Refines**: [ADR-023](023-fsm-session-incarnation-identity-and-routing.md) by removing the transitional Workflow FSMSession-identity reservation bridge

data/docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md

@@ -4,6 +4,11 @@
 
 Accepted. V2 revision 2, 2026-09-06.
 
+The HandoffRunner namespace and ownership are amended by
+[034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md).
+The public Runner is now `Phronomy::MultiAgent::HandoffRunner`. Other Handoff
+types and the durable semantics below remain unchanged in this first step.
+
 User approval covers the V2 boundary and the five recovery-contract clarifications.
 Acceptance is design authority; it is not a claim of repository integration or test success.
 

data/docs/decisions/031-durable-multi-agent-coordination.md

@@ -4,6 +4,11 @@
 
 Accepted. V2 revision 2, 2026-09-06.
 
+The HandoffRunner namespace and ownership are amended by
+[034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md).
+The public Runner is now `Phronomy::MultiAgent::HandoffRunner`. Other Handoff
+types and the durable semantics below remain unchanged in this first step.
+
 User approval covers the V2 boundary and the five recovery-contract clarifications.
 Acceptance is design authority; it is not a claim of repository integration or test success.
 

data/docs/decisions/032-storage-backend-composition.md

@@ -0,0 +1,80 @@
+# 032: Compose domain persistence over a storage backend
+
+- Status: Accepted
+- Domain ownership refined by: [033-domain-persistence-ownership](033-domain-persistence-ownership.md)
+- Date: 2026-09-17
+- Refines: [014-unified-persistence-durable-state](014-unified-persistence-durable-state.md)
+
+The raw fixed-repository/error portions are amended by
+[ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable
+transaction/uncertainty decisions below remain in force.
+
+## Context
+
+The previous `Persistence` class combined raw storage contracts with domain
+repository construction, codecs, and result queries. Physical backends inherited
+that class, and SQL implementations called `build_transaction_view` to construct
+upper domain facades. This made the common storage boundary depend on the
+entities whose records it stored.
+
+## Decision
+
+1. `Storage::Backend` and `Storage::Repositories` define synchronous raw storage
+   and transaction-view protocols. `Storage::DurableRecord` and portable storage
+   errors belong to this common contract. These files do not depend on Agent,
+   MultiAgent, Runtime, or the domain-facing Persistence implementation.
+2. Concrete backends depend on that contract and their physical storage tools.
+   The in-memory implementation lives in `storage/backends/in_memory.rb` and
+   retains its single Monitor and single all-repository transaction snapshot.
+3. `Persistence.new(backend:)` composes the domain service over a selected backend.
+   The existing domain codecs and facades remain in `persistence/`. They validate
+   and convert records using the actual domain record definitions.
+4. The same facade builder wraps the root backend and the raw view yielded by
+   `backend.transaction`. Transaction conversion stays inside the backend block;
+   conversion failures therefore participate in its normal rollback semantics.
+5. `Persistence.in_memory` is the explicit convenience assembly. Backend selection
+   belongs to construction, not to the common storage contract.
+6. Replace the old Persistence subclass SPI, raw-repository constructor,
+   `build_transaction_view`, `Persistence::InMemory`, and old record/error owners.
+   No compatibility aliases or second implementation of that SPI are retained.
+   See the [migration guide](../migrations/storage-backend-composition.md).
+
+Both concrete backends and domain persistence depend on the common storage
+contract. These are sibling responsibility groups, not a requirement for one
+strict vertical ordering of the entire system. Runtime calls to a selected
+backend do not establish a source dependency on that backend's concrete class.
+
+## Preserved contracts
+
+All eight repositories remain one atomic transaction domain. Their IDs,
+revision/position checks, active execution constraints, record types, format
+versions, and payload schemas are unchanged. ContentStore retains its separate
+canonicalization API. The shared `AgentBusyError` remains the existing admission
+failure contract; its standalone definition does not load Agent implementation.
+
+Atomic durable-state transitions remain CONDITIONAL on a conforming backend for
+F0 operations; commit-outcome certainty under F1 remains NO as a general promise.
+F4 restart readability remains CONDITIONAL on retained confirmed durable data;
+InMemory does not provide disk retention. X0 external effects remain outside the
+storage transaction. This change adds no asynchronous SPI or execution ownership.
+
+## Consequences and validation
+
+Custom SQL backends migrate their superclass, record/error references, and raw
+transaction view construction. They keep all transaction repositories and the
+watermark bound to the same connection. Applications wrap a raw backend once.
+
+An isolated-load architecture test checks that storage can use opaque records and
+admission without loading domain or execution code. Public contract tests cover
+root/transaction view separation and removal of the replaced SPI. Existing
+repository conformance, commit/rollback/CAS, codec, recovery, and integration tests
+remain required. Codec rejection after a physical write must roll back the whole
+transaction, not leave a committed partial operation.
+
+Shared Immutable ownership has already moved to `Values::Immutable`; this change
+preserves that boundary. Domain model placement and unrelated module cycles
+remain separate subsequent changes. In particular, DurableCodec retains its
+TeamRoot / TeamExecution references to validate and reconstruct Team records.
+Those belong to domain persistence, not to the common storage contract.
+Moving a type or hiding a constant reference alone is not evidence that this
+storage boundary has been separated.

data/docs/decisions/033-domain-persistence-ownership.md

@@ -0,0 +1,79 @@
+# 033: Own persistence rules within each domain
+
+- Status: Amended
+- Date: 2026-09-18
+- Error boundary refined by: [043-storage-execution-constraint-notifications](043-storage-execution-constraint-notifications.md)
+- Refines: [032-storage-backend-composition](032-storage-backend-composition.md)
+
+The raw fixed-repository/error portions are amended by
+[ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable
+transaction/uncertainty decisions below remain in force.
+
+## Context
+
+ADR-032 separated raw storage from domain persistence, but the common-looking
+`persistence/` directory still collected Agent, Team, and Workflow schemas and
+repository facades. Moving that directory to an upper band in a dependency
+diagram described its contents; it did not establish suitable domain ownership.
+The public Persistence entry point also contained domain-specific result queries.
+
+## Decision
+
+1. `agent/persistence/` owns AgentRoot, Journal, AgentExecution, and Handoff
+   codecs/repositories and Agent/Handoff result queries.
+2. `multi_agent/persistence/` owns TeamRoot and TeamExecution codecs/repositories
+   and Team result queries. Team persistence can be used over a raw backend
+   without loading Agent implementation or the combined Persistence service.
+3. `workflow/persistence/` owns the Workflow record schema, normalization rules,
+   and state repository. Workflow symbol normalization remains specific to that
+   domain; other codecs do not adopt it implicitly.
+4. `Storage::RecordCodec` contains shared record-envelope and scalar validation.
+   Domain codecs extend it; it neither selects nor imports a domain codec.
+   These helpers and domain components are private implementation, not new SPI.
+5. `PersistenceComposition::Repositories` explicitly assembles the seven domain
+   repository wrappers and the existing ContentStore from one raw storage view.
+   The public `Phronomy::Persistence` service remains the compatible entry point.
+   It delegates queries and retains the Runtime observation-thread guard.
+   Each view creates and caches domain wrappers on first use, under one lock,
+   so Agent-only use does not load Team or Workflow implementations.
+6. Conversion remains inside `backend.transaction`. Root and transaction paths
+   use the same builder. Reusing the root view when the backend yields itself
+   retains the existing repository identity and fault-injection behavior.
+7. Delete the private combined `Persistence::DurableCodec` and
+   `Persistence::RepositoryFacades`; do not preserve a second owner through
+   compatibility aliases. Explicit historical migration keeps its public API
+   and calls the new domain codecs.
+
+InMemory, SQLite, and PostgreSQL are all concrete implementations of the common
+Backend contract. Domain repository wrappers are consumers of that contract;
+they do not introduce a second physical transaction boundary.
+
+## Preserved contracts and limits
+
+Public Persistence methods, Backend SPI, eight repository accessors, IDs,
+revisions/positions, active constraints, physical SQL schemas, record types,
+format versions, and payload schemas are unchanged. Existing SQL backends need
+no source migration for this ownership change. The public result-reader dispatch
+and observation guard remain in the public entry point.
+
+Atomic durable-state transitions and rollback remain CONDITIONAL on a conforming
+backend for F0. Commit-outcome certainty under F1 is not added. F4 restart
+readability depends on retained confirmed data; InMemory is not disk retention.
+X0 effects remain outside storage transactions.
+
+The raw `Storage::Repositories` still names eight Phronomy record repositories and
+an Agent watermark operation. This is an explicit intermediate state, not a claim
+that the framework contract is domain-neutral. Contract generalization and naming
+of the final common persistence framework are deferred to the staged plan below.
+
+## Validation
+
+Existing record-schema, backend conformance, optimistic conflict, recovery,
+Handoff, Team, Workflow, and public compatibility tests remain required. A
+separate-process boundary test uses Team persistence without Agent, Workflow,
+Runtime, or combined-Persistence loading. Another process uses the public Agent
+repositories without loading Team or Workflow implementations. A failure-injection test rejects the
+Team response after writes and verifies rollback across Agent, Team, and content.
+Dependency analysis must not introduce a new nontrivial file cycle.
+
+See [the staged implementation plan](../architecture/persistence-refactoring-plan.md).

data/docs/decisions/034-handoff-runner-coordination-ownership.md

@@ -0,0 +1,76 @@
+# ADR-034: Handoff Runner Coordination Ownership
+
+## Status
+
+Accepted for the H1 step on `refactor/architecture`, 2026-09-18.
+The subsequent Handoff contract and persistence separation is deferred.
+
+## Scope of supersession
+
+This amends the Runner placement/public namespace in
+[030-agent-handoff-domain-and-durable-responsibility](030-agent-handoff-domain-and-durable-responsibility.md)
+and the domain map in
+[031-durable-multi-agent-coordination](031-durable-multi-agent-coordination.md).
+All other durable Handoff semantics remain in force.
+
+## Context
+
+HandoffRunner validates a graph of concrete Agents, selects the active Agent,
+invokes or resumes exact executions, follows multiple transfers, and scopes
+cancellation/result lookup to a specified chain. Those responsibilities span
+Agents. They differ from an individual Agent's execution, Journal and Context.
+
+Calling Handoff from an Agent does not make that whole coordination lifetime an
+Agent implementation detail. Updating the Source and routing state in one
+transaction also does not require them to occupy one module.
+
+The Runner and TeamCoordinator share the Runtime-local AdmissionRegistry. Keeping
+the Runner inside Agent creates an Agent-to-MultiAgent concrete dependency.
+Moving only the Runner aligns ownership without generalizing the registry or
+changing the existing shutdown participant contract.
+
+## Decision
+
+1. Move the public Runner implementation from `agent/handoff_runner.rb` to
+   `multi_agent/handoff_runner.rb` and expose
+   `Phronomy::MultiAgent::HandoffRunner`.
+2. Remove `Phronomy::Agent::HandoffRunner` without a compatibility alias on the
+   refactoring branch. Migrate API documentation, RBS, snapshot and consumers
+   together. See the [migration guide](../migrations/handoff-runner-multi-agent.md).
+3. Retain `Agent::Handoff`, `HandoffPolicy`, Context/Request/State and Agent
+   terminal/persistence integration during H1. Qualify the Runner's dependencies
+   explicitly. This mixed placement is an intermediate state.
+4. Keep AdmissionRegistry in MultiAgent. The admission key, exception classes,
+   successful-call release and Runtime shutdown participation are unchanged.
+5. Preserve method parameters/results, record formats, main-Agent anchor,
+   deterministic Target IDs, transaction boundaries, exact recovery and scoped
+   cancellation. H1 introduces no new execution or shutdown manager.
+
+## Consequences and limits
+
+Agent no longer directly names a MultiAgent implementation in production source.
+The Runner's existing Tracing dependency now belongs to the MultiAgent directory.
+Module-edge totals and large strongly connected components need not decrease:
+this step changes responsibility placement, not the underlying algorithm.
+
+Agent still interprets Handoff/Team coordination metadata. This logical coupling
+is not removed merely because a directory edge disappears.
+
+Later work must separate Request construction, Coordinator selection, Context
+conversion, transaction participation and purge/recovery constraints before
+moving the remaining Handoff-specific types and persistence rules. That work must
+preserve one transaction for Source termination plus responsibility transfer and
+for Target termination plus routing stabilization. It must not promote transferred
+Context into permanent Target Journal/Knowledge or depend on post-commit callbacks
+for coordination correctness.
+
+## Verification obligations
+
+The new public constant must load with Zeitwerk and match its RBS/API snapshot;
+the old constant must not remain as an alias. Existing Handoff, multi-hop,
+cancellation/recovery, shutdown and SQLite reconstruction scenarios must pass.
+API guards must distinguish `MultiAgent::HandoffRunner` from the removed exact
+constant `MultiAgent::Handoff`.
+
+The implementation delivery records test results separately; this ADR does not
+assert that unexecuted live-LLM or database-server tests passed.

data/docs/decisions/035-tool-executor-capability-ownership.md

@@ -0,0 +1,68 @@
+# ADR-035: Default Tool Executor Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch as T1.
+
+This decision assigns the default Tool execution helper to the existing
+Capability implementation. The public Tool facade defined by ADR-015 remains
+the same Class object with the same canonical implementation name.
+
+## Context
+
+`Agent::Context::Capability::Base#call_async` delegates default asynchronous
+dispatch to `Agent::ToolExecutor`. The helper selects inline cooperative work
+or OffloadPool submission and returns a TaskResult. It has no responsibility
+for Agent state, approval, persistence, recovery, or multi-Agent coordination.
+
+Placing this helper directly under Agent makes the Capability directory depend
+on Agent execution while Agent execution also depends on Capability. The
+underlying helper is part of the Tool calling contract and its standard
+implementation, so its ownership should reflect that role.
+
+Moving only the helper to `tool/` would introduce another directory cycle:
+`tool/base.rb` currently aliases `Agent::Context::Capability::Base`. Moving the
+canonical Tool class and changing its runtime name would require a separate
+public compatibility decision.
+
+## Decision
+
+1. Move the helper to
+   `Phronomy::Agent::Context::Capability::ToolExecutor`, in
+   `agent/context/capability/tool_executor.rb`. Classify this helper as private
+   API and remove the old internal constant without a compatibility alias.
+2. Use the new helper from Capability Base and Agent ToolInvocation. Preserve
+   the existing dispatch implementation and error messages.
+3. Keep `Tool::Base` and `Agent::Context::Capability::Base` as the same Class
+   object. Preserve their canonical name, DSL state, method-owner checks, and
+   the public `call_async(args, cancellation_token:, config:)` protocol.
+4. Keep Runtime selection, authorization and logical result ownership in Agent
+   ToolInvocation. Its standard path passes Runtime and `on_full: :raise` to
+   the private helper; custom Tool implementations receive the public protocol.
+   Agent-as-Tool continues through its own asynchronous Agent lifecycle.
+5. Keep the existing TaskResult and OffloadPool mechanisms in Engine. This
+   step adds no execution manager or application registration requirement.
+
+## Consequences and limits
+
+The Capability directory now directly names its existing Engine dependencies
+instead of an Agent-owned wrapper. The code-level algorithm and file-level
+dependency graph are preserved when the moved file is matched to its source.
+Directory placement changes do not imply that all larger dependency cycles
+have been resolved.
+
+Applications should use the public Tool authoring and invocation contracts.
+Code or tests that directly reference the removed private Agent::ToolExecutor
+constant need to follow its new internal name. The public Tool API and durable
+formats require no migration, and the Context contract regrouping remains a
+separate change.
+
+## Verification obligations
+
+Verify cooperative execution, OffloadPool dispatch, cancellation propagation,
+Runtime injection, custom `call_async`, and Agent-as-Tool. Keep the existing
+offload-boundary observations aligned with the moved source path. The public
+API snapshot, RBS and Tool class identity must remain unchanged; Zeitwerk must
+load the new helper and leave the old internal constant absent.
+
+The implementation delivery records its actual test results separately.