phronomy 0.26.0 → 0.28.0

data/docs/architecture/workflow-terminal-ownership-design.md

@@ -0,0 +1,104 @@
+# Workflow terminal ownership: design and validation
+
+Implementation baseline: core `01cd2f57549f6d1e60825254f4520d0f123e651c`
+(Refactor 32 applied) and examples `2f8b467f1268dd21de4c02b1c90c8bdd211d1feb`,
+2026-09-23. W2a and W2b are applied and verified; W2b is core
+`fcd434c45ad98e5c93953cbce1ffef3c12246894` (Refactor 33). The adopted private contract is
+[ADR-056](../decisions/056-workflow-terminal-policy-ownership.md).
+
+## Role and consumers
+
+FSMSession drives one live state machine on EventLoop. WorkflowRunner assembles
+Workflow transitions, stream observation and any durable terminal save.
+InvocationActions and EngineSessionBuilder uses the same engine for input, LLM and Tool
+progression; ToolInvocationSessionBuilder uses it for authorization, approval
+and Tool execution. Therefore the session stays in Engine.
+
+The former leak was narrower: Engine recognized the Workflow persistence event
+and interpreted its save outcomes. WorkflowTerminalPolicy now owns that rule.
+
+## Ownership and concrete boundary
+
+| Owner | Responsibility |
+|---|---|
+| FSMSession | Identity/sink, transitions, live context, pending terminal kind/notification flag, event acceptance and final notification/event ordering. |
+| WorkflowTerminalPolicy | Start the injected save callback; recognize the Workflow result event; map its outcome to a generic terminal decision. |
+| Phronomy::TerminalDecision | Immutable `action` and `error` value shared by a domain policy and the session. No live session authority. |
+| WorkflowRunner | Construct a policy for durable execution; retain snapshot capture, one save, F1 readback and caller completion. |
+| WorkflowExecutionRegistry | Admission, owner tokens, session routing binding and recovery-required ownership. |
+| EventLoop | Event routing, management events, retirement, source completion and shutdown. |
+
+Runner builds a policy only when both repository and persist are enabled.
+Agent, Tool and ephemeral Workflow need no dummy policy or delayed completion.
+The policy retains only its persistence callback, with no lifecycle flags.
+
+The three private operations are `start(terminal_type:, context:, event_sink:)`,
+`handles?(event)` and `decision_for(event)`. Start does not return completion
+permission. The decision value maps Workflow success to `complete`, known
+failure to `fail`, and unresolved uncertainty to `retire`. Failure preserves the
+original exception or the existing missing-error fallback. Invalid outcomes
+remain errors. Engine no longer branches on Workflow's event or outcome values.
+
+FSMSession alone tracks `running`, `awaiting_terminal`, and its final lifecycle
+state. Matching early events are discarded before invoking decision_for;
+ordinary events cannot advance while awaiting; events after done are ignored.
+The retirement action reuses the existing recovery-required management route.
+
+## Preserved durable ordering
+
+1. Session reaches a logical wait/completion boundary and captures metadata.
+2. Session marks itself awaiting a decision before invoking the policy.
+3. Runner marks admission persisting_terminal and captures an immutable command.
+4. Offload saves once and reconciles an uncertain result when possible.
+5. The bound EventSink returns the result to that session on EventLoop.
+6. The policy interprets the result only while the session accepts it.
+7. A complete decision permits the deferred observer, then the terminal event.
+8. EventLoop retires the session; Runner releases admission before settling the caller.
+
+An observer exception still uses Refactor 32's ordinary error path, with the
+already confirmed snapshot retained. No observer retry or extra save is added.
+
+Unresolved uncertainty instead retires the session and retains recovery-required
+admission without falsely settling the caller. Normal shutdown clears that
+ownership and ends the dispatcher, while the caller remains pending; unexpected
+dispatcher failure retains its separate existing waiter-cleanup behavior. This
+change does not promise that normal shutdown resolves an unknown commit.
+
+## Alternatives and compatibility
+
+Moving the full session would introduce Workflow dependencies into Agent/Tool.
+Renaming event strings in Engine would leave semantic ownership unchanged.
+Subclass/prepend overrides would recreate the hidden execution path removed by
+W1. Saving after retirement or settling on a worker would break the barrier.
+The injected policy keeps each rule at its existing execution authority.
+
+The internal constructor changes from terminal_barrier to terminal_policy;
+there is no compatibility alias or new public plugin API. Without a policy,
+Engine does not reserve a Workflow-specific event name. Production Workflow
+emits the result event only when it has injected its durable policy.
+Public signatures, Workflow command/result identities, data records and Storage
+SPI stay unchanged. One policy class and one decision value type are added;
+this is responsibility separation, not a total-line-count reduction.
+
+## Acceptance evidence
+
+| Scenario | Test boundary |
+|---|---|
+| Immediate completion/halt and Agent/Tool | Existing Workflow/Agent/Tool suites and generic no-policy completion. |
+| Delayed save and halted stream | Real Runtime admission tests prove no early result/notification. |
+| Portable failures and F1 post/pre/conflict/unreadable | Existing save tests plus real Runtime pre-state and uncertainty tests. |
+| Unknown result and normal shutdown | Admission retained until shutdown, session unbound, caller remains pending. |
+| Early/ordinary/duplicate decisions | Non-Workflow policy/session contract and Workflow policy wiring tests. |
+| Late sink and new incarnation | Real Runtime rejects an old sink for the same logical Workflow ID. |
+| Terminal observer failure | Refactor 32's four public stream regressions. |
+| Submission rejection and delivery rejection | Existing error path releases admission; rejected delivery logs without retry. |
+| Invalid outcomes and missing error | Workflow policy through the real Runner/session assembly. |
+| Load, types, API, gem and source boundary | Full validation and private ownership regression assertions. |
+
+The pre-state, uncertainty/shutdown, stale-sink and rejected-delivery scenarios
+also pass on the Refactor 32 baseline; they characterize preserved behavior.
+New protocol tests establish the extracted ownership contract. Refactor 33
+application verification completed W2b. Storage S1/S2 followed and passed on
+Refactor 35; see the [closure review](refactoring-closure.md) for S3 and the
+current applied/candidate boundary. The earlier Refactor 32 baseline remains
+historical evidence for preserved behavior.

data/docs/architecture.md

@@ -23,6 +23,13 @@ reviewed explicitly rather than resolved by recency.
 
 ## Design principles
 
+The current r8 refinement of Agent parent/Tool child progress and concrete
+execution connections is described in [unit 8](architecture/r8-unit8.md), building
+on [unit 7](architecture/r8-unit7.md). C04 owns Agent progress and approval/recovery;
+C06 owns Tool operations; C13 supplies execution submission/completion. Concrete
+FSM construction stays in Agent runtime_binding. These scoped changes do not
+declare the full contract target or remaining dependency cycles complete.
+
 These are design heuristics for new and revised architecture. They do not
 override an Accepted ADR, an established public/extension contract, or an
 explicit compatibility decision.
@@ -41,10 +48,222 @@ 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_adapter/`, together with the SDK-neutral
+operation contract. See [r8 unit 6](architecture/r8-unit6.md).
+
+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` and `Agent::ExecutionChange` own Agent
+completion, failure, suspension, dispatch preparation and commit proof. A limited
+participant joins its own domain changes to the same scope. MultiAgent owns
+subagent reservations and Handoff routing; it passes extension state and transfer
+receipts, never Agent records or arbitrary update blocks. The EventLoop owner
+continues to apply confirmed results and deliver callbacks. See
+[r8 unit 4](architecture/r8-unit4.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 private AsyncClient now
+owns the Runtime dependency; its synchronous Base and RubyLLM implementation
+are independent of Engine. VectorStore/Embeddings migration and other cycles
+remain. See [Backend responsibilities](architecture/backend-groups.md).
+
+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 |
 |---|---|
+| Backend Contracts, Implementations, Async Clients and dependency diagrams | [Backend responsibilities](architecture/backend-groups.md) |
 | Agent state, identity, ownership, and Context authority | [Agent Context](architecture/agent-context.md) |
 | Per-LLM-call Context Policy and Manifest construction | [Context Management](architecture/context-management.md) |
 | Journal-backed Knowledge and retrieval integration | [Knowledge and RAG](architecture/knowledge-and-rag.md) |
@@ -87,3 +306,6 @@ Durable multi-agent coordination is described by [ADR-029](decisions/029-semanti
 TeamExecution is a purpose-specific CAS authority delegating coordinator/workers
 to ordinary Agents, with no Team FSMSession or second Workflow engine.
 Static subagent reservation lives in the existing parent AgentExecution metadata.
+
+Current C10/C11 common operation ownership and independent Embeddings/Documents
+placement are specified in [r8 unit 5](architecture/r8-unit5.md).

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/015-tool-public-facade-and-rbs-boundary.md

@@ -9,7 +9,7 @@ Accepted.
 Phronomy has accumulated two related API-maintenance problems:
 
 1. Application-defined Tools are implemented by subclassing the internal-taxonomy
-   name `Phronomy::Agent::Context::Capability::Base`, even though the product
+   name `Phronomy::Tool::Base`, even though the product
    concept exposed to users is simply a Tool.
 2. The gem ships almost no RBS signatures, so the distinction between
    application APIs, extension SPIs, and private implementation objects is not
@@ -42,7 +42,7 @@ Phronomy::Tool::Base
 The existing implementation class remains:
 
 ```ruby
-Phronomy::Agent::Context::Capability::Base
+Phronomy::Tool::Base
 ```
 
 `Phronomy::Tool::Base` is an exact constant alias to that same class object. It
@@ -58,7 +58,7 @@ This preserves:
   name.
 
 Consequently, `Phronomy::Tool::Base.name` intentionally remains
-`"Phronomy::Agent::Context::Capability::Base"`. If a future public contract
+`"Phronomy::Tool::Base"`. If a future public contract
 requires the runtime class name itself to become `Phronomy::Tool::Base`, that is
 a separate migration decision.
 

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/027-llm-adapter-provider-boundary.md

@@ -46,6 +46,8 @@ reconciliation must not silently promote its API stability.
 2. `Phronomy::LLMAdapter::Base#complete` and `#stream` are the public
    Provider-call extension boundary. Phronomy owns the framework-side
    asynchronous/offload wrappers around that synchronous adapter contract.
+   [ADR-059](059-backend-contracts-and-async-clients.md) locates those wrappers
+   in the private `LLMAdapter::AsyncClient`, separate from Base and RubyLLM.
 3. `Phronomy::LLMAdapter::RubyLLM` remains the default configured LLM adapter
    and RubyLLM remains Phronomy's default Provider integration.
 4. A custom LLMAdapter may replace Provider-call behavior, but the LLMAdapter

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

@@ -1,9 +1,16 @@
 # ADR-030: Agent Handoff Domain and Durable Responsibility
 
+> 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.
+
 ## Status
 
 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

@@ -1,9 +1,16 @@
 # ADR-031: Durable Multi-Agent Semantic Coordination
 
+> Agent/MultiAgent ownership is amended by [ADR-064](064-agent-execution-and-multi-agent-responsibility.md).
+
 ## Status
 
 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,85 @@
+# 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.
+
+Domain-facing exception ownership is further amended by
+[061-persistence-failure-contracts](061-persistence-failure-contracts.md).
+Raw backend exceptions remain owned by Storage; domain repository exits now
+translate their known categories to independent Persistence exceptions.
+
+## 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.