phronomy 0.25.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/async-composition.md

@@ -0,0 +1,205 @@
+# Result composition and Execution
+
+`Phronomy::TaskResult` represents a pending or settled result. It does not start
+a thread. `Phronomy::Execution` starts the input JOBs and waits for the final
+TaskResult returned by each JOB. The application defines those completion
+conditions and what to do with the collected values.
+
+## Invocation, individual results and fan-in
+
+```ruby
+require "phronomy"
+
+def collect_answers_async(agents, question:, invocation_context: nil)
+  Phronomy::Execution.run_async(
+    agents, timeout: 30, invocation_context: invocation_context
+  ) do |agent, execution|
+    agent.invoke_async(question, invocation_context: execution.invocation_context)
+      .map { |response| response.fetch(:output).strip }
+  end
+end
+
+# Each outcome identifies the original input position, including failed JOBs.
+outcomes = collect_answers_async(agents, question: "Explain the tradeoff").wait_result
+outcomes.each do |outcome|
+  puts [outcome.index, outcome.status, outcome.value, outcome.error&.message].inspect
+end
+```
+
+`agents` contains separately generated or loaded Agent instances. Use each
+Agent's materialization listener for lifecycle/progress events. Result handling
+uses the TaskResult returned by the invocation.
+
+The input must be an Array. Its positions are shallowly copied before any JOB
+starts. Start blocks run in input order without waiting for previous returned
+results. They can run on the calling thread. Execution adds no per-JOB thread
+or worker: keep start and transformation blocks short and use
+`Blocking.call_async` for application work that can block. A start block itself
+can delay the return of `run_async` if the application performs synchronous work.
+
+Zero, one and many inputs all produce an Array of Outcome records. Empty input
+still validates parameters and rejects an already-expired deadline or cancelled
+token before completing. `Execution.run` starts the same execution once and
+waits for its Outcome Array. The synchronous entrance is rejected on EventLoop
+even for empty or already-completed inputs.
+
+## map and flat_map
+
+| Operation | Success callback | Derived result |
+| --- | --- | --- |
+| `result.map { ... }` | Returns any value | That value, even when the value itself is a TaskResult |
+| `result.flat_map { ... }` | Returns a TaskResult | Waits for and adopts that inner result's terminal value/state |
+| `result.on_complete { \|value, error\| ... }` | Independent completion notification | Returns the original result; the callback does not transform it |
+
+A callback can run immediately during registration or on the completing thread.
+There is no callback thread guarantee. `map`/`flat_map` block StandardError
+failures become failures of the derived result, preserving the original error.
+A wrong `flat_map` return becomes a TypeError failure. Missing blocks raise
+ArgumentError at registration. A source or inner **cancelled state** propagates
+as cancelled with the original error. A failed CancellationError, or one raised
+by an application transformation, stays failed.
+
+For example, extend each JOB through a second Agent before returning its result:
+
+```ruby
+evaluations = Phronomy::Execution.run_async(pairs, timeout: 30) do |pair, execution|
+  context = execution.invocation_context
+  pair.fetch(:author).invoke_async(question, invocation_context: context)
+    .flat_map do |answer|
+      pair.fetch(:reviewer).invoke_async(answer.fetch(:output), invocation_context: context)
+        .map { |review| review.fetch(:output) }
+    end
+end
+```
+
+If a JOB raises StandardError or returns something other than a TaskResult,
+that JOB becomes failed. Other JOBs continue. Once all final results settle,
+the whole execution succeeds with the Outcome Array even if it contains
+individual failures or cancellations.
+
+## Outcome records and whole-execution deadlines
+
+`TaskResult::Outcome` has read-only `index`, `status`, `value` and `error` fields.
+The returned Array and its records are frozen. Values and original exceptions
+are retained by reference, without deep copying or freezing application objects.
+
+| Whole execution | Whole TaskResult | Available records |
+| --- | --- | --- |
+| All JOBs settled | completed | Successful value is the Outcome Array |
+| `timeout:` won | failed, ExecutionTimeoutError | `error.outcomes` |
+| Explicit or inherited token/deadline cancellation won | cancelled, ExecutionCancellationError | `error.outcomes` |
+
+Record statuses are `:completed`, `:failed`, `:cancelled`, and, in an interrupted
+snapshot, `:unfinished`. Unstarted JOBs also have unfinished records. This is
+not another terminal state of TaskResult. A JOB's record refers to its final
+returned result, so completed transformed values are retained; an unfinished
+inner `flat_map` result makes that JOB unfinished.
+
+The execution serializes record updates and terminal claims. The first terminal
+claim wins. At timeout/cancellation it fixes the records before requesting child
+cancellation; later notifications cannot rewrite those records. It does not
+retroactively decide using physical worker completion timestamps.
+
+`timeout:` covers fan-out start through the final JOB results reaching fan-in.
+`nil` adds no deadline. Zero or negative values fail before starting JOBs. It
+accepts finite real Numeric values usable as elapsed seconds; other types raise
+TypeError, and non-finite/complex values raise ArgumentError. These checks occur
+before JOB starts or cancellation subscriptions. The existing Blocking numeric
+conversion rules are unchanged.
+
+`cancellation_token:` accepts nil or a CancellationToken (including subclasses).
+`invocation_context:` accepts nil or an existing InvocationContext (including
+subclasses). Other types raise TypeError at the Execution entrance.
+
+`TaskResult#wait_result(timeout:)` sets only that caller's wait limit. It does not
+cancel or alter the underlying result. Pending waits are forbidden on EventLoop.
+An individual Blocking timeout keeps its TimeoutError failure; an individual
+deadline token keeps the cancellation state. These are distinct from the whole
+execution's errors and snapshot.
+
+## Context, cancellation and ownership
+
+Pass `execution.invocation_context` explicitly to an Agent or to
+`Blocking.call_async(invocation_context: ..., cancellation_token: ...)` for work
+belonging to that execution. The result is bound before it returns to the app;
+its `map`/`flat_map` continuations inherit the scope. A continuation checks the
+scope before running. Explicitly passing the context again when starting an
+inner operation also covers cancellation after the continuation has begun.
+
+An optional existing context contributes its user, policy, budget and tracing
+information by reference. Execution derives a new context without modifying
+the supplied one. Existing context cancellation/deadline and the explicit
+Execution token/timeout all remain effective. Controls connect one way into a
+private token. Cancelling one execution or an individual operation does not
+cancel a parent's or another caller's shared token. Agent and Blocking admission
+combine the individual token with the context's controls.
+
+Scope cancellation stops unstarted scoped operations/transformations and requests
+cooperative cancellation of running operations. It does not use Thread#raise,
+roll back effects, or guarantee physical worker termination. Offload work and
+owned composition steps retain their physical-completion tracking after logical
+cancellation. `on_complete` notifications still run, and suppressed framework
+continuations settle as cancelled rather than remaining pending.
+
+Execution waits only for registered JOBs' returned final results. If a JOB
+starts X and Y but returns Y, the app is responsible for X. Normal completion
+does not discover, join, or sweep-cancel X. If the app explicitly supplied this
+scope to X, its API's cancellation and closed-scope start restrictions still
+apply. A normally closed context cannot be reused to start another operation.
+
+## Observing work started elsewhere
+
+```ruby
+# Source started under its original owner and controls.
+shared_result = existing_agent.invoke_async(question)
+
+run = Phronomy::Execution.run_async([shared_result], timeout: 5) do |source, execution|
+  execution.observe(source).map { |response| response.fetch(:output).upcase }
+end
+```
+
+`observe` returns a distinct scoped result. It does not restart, rebind or cancel
+the source, its existing continuations, or its physical work. A JOB may also
+return an external result directly if it only needs to wait for it.
+
+`TaskResult.all_settled(results)` is the public wait-only API. It accepts an Array
+of TaskResult instances/subclasses, snapshots the positions, and preserves order
+and duplicate positions. Invalid elements cause an immediate TypeError before
+any source is subscribed. It accepts an empty list and has no timeout/cancel
+parameters. It does not own or infer scopes from its sources. If subsequent
+transformations should be scoped, explicitly use
+`execution.observe(TaskResult.all_settled(results)).map { ... }`.
+
+## Whole-result processing and existing layers
+
+The whole TaskResult is the scope exit. An outer `map`/`flat_map` does not inherit
+or extend the completed inner scope, whether registered before or after fan-in.
+For example, vote counting belongs in an outer `map`. A slow save belongs in an
+outer `flat_map` returning `Blocking.call_async(timeout: 5) { ... }`. That new
+operation's five seconds start when it is invoked, independently of the first
+execution's deadline. There is no `compose` argument or separate fan-out entrance.
+
+Execution owns common runtime coordination. Orchestrator remains above the Agent
+layer: `dispatch_parallel[_async]` retains Agent construction, knowledge
+inheritance, bounded active children and `on_error` policy, and delegates its
+runtime coordination to Execution. AgentExecution remains the durable Agent
+record; ExecutionCoordinator keeps admission, persistence, approval, recovery
+and terminal barriers while reusing the common context/control binding.
+
+## Development-release migration
+
+- Replace `Phronomy::Task` with `Phronomy::TaskResult`. The old constant and file
+  are removed; there is no compatibility alias.
+- Replace `orchestrator.fan_out(agent: klass, inputs: inputs, ...)` with
+  `orchestrator.dispatch_parallel(*inputs.map { |input| {agent: klass, input: input} }, ...)`
+  when keeping Orchestrator's Agent construction/knowledge/concurrency policy.
+  Use Execution directly for application-defined JOB result composition.
+- Replace the asynchronous equivalent with `dispatch_parallel_async` or
+  `Execution.run_async` as appropriate. `fan_out` and `fan_out_async` are removed.
+- Keep per-incarnation listeners at Agent creation/load. This change introduces
+  no invocation listener blocks, Proc persistence, durable result transforms,
+  callback acknowledgements or new scheduler.
+
+See examples `32_async_composition` for complete basic and asynchronously
+evaluated majority-vote applications, and `23_bounded_parallel` for bounded
+Agent dispatch. Examples must depend on a core commit containing these APIs.

data/docs/decisions/010-cooperative-first-concurrency.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted — revised for a single Task completion contract and the OffloadPool
+Accepted — revised for a single TaskResult completion contract and the OffloadPool
 execution boundary.
 
 ## Context
@@ -19,7 +19,7 @@ executes is separate from the object used by callers to observe completion.
 ## Decision
 
 Framework lifecycle coordination uses one Runtime-owned EventLoop and explicit
-FSMSession state/events. **`Phronomy::Task` is the single caller-facing completion
+FSMSession state/events. **`Phronomy::TaskResult` is the single caller-facing completion
 handle**, not an execution backend.
 
 There are two framework execution mechanisms:
@@ -28,22 +28,22 @@ There are two framework execution mechanisms:
 - **OffloadPool** for synchronous work that must execute on bounded worker OS
   Threads away from EventLoop.
 
-Both mechanisms surface asynchronous completion as `Phronomy::Task`.
+Both mechanisms surface asynchronous completion as `Phronomy::TaskResult`.
 
 Phronomy defines two Tool execution modes:
 
 - `:cooperative` — short, EventLoop-safe work, or a specialized asynchronous
   implementation that starts another Phronomy lifecycle and immediately returns
-  a Task;
+  a TaskResult;
 - `:offloaded` — synchronous work that must not run on EventLoop. It executes in
-  the bounded OffloadPool and returns a Task.
+  the bounded OffloadPool and returns a TaskResult.
 
 Workload classification such as I/O-bound versus CPU-bound is application-owned.
 Phronomy does not provide separate `:blocking_io`, `:cpu_bound`, or
 `:external_process` Tool execution modes.
 
 Logical waits are never offloaded merely to obtain concurrency. Waiting for an
-Agent, Workflow, ToolInvocation, approval, timer, or another Task is represented
+Agent, Workflow, ToolInvocation, approval, timer, or another TaskResult is represented
 as FSMSession state plus a later EventLoop event.
 
 ## Runtime model
@@ -65,7 +65,7 @@ Runtime
 └─ EventLoop-driven timers
 
 EventLoop / FSMSession ─┐
-                       ├─> Task = completion handle
+                       ├─> TaskResult = completion handle
 OffloadPool ────────────┘
 ```
 
@@ -91,11 +91,11 @@ resource domains.
 An EventLoop action must not block while waiting for a free OffloadPool queue
 slot. Framework-owned EventLoop-origin submissions therefore use non-blocking
 admission (`on_full: :raise`) and propagate `BackpressureError` through the normal
-FSM/Task completion path.
+FSM/TaskResult completion path.
 
 ## Timeout and cancellation
 
-An OffloadPool submit-time timeout settles the caller-facing Task with
+An OffloadPool submit-time timeout settles the caller-facing TaskResult with
 `TimeoutError`. It does not asynchronously interrupt a running worker Thread. If
 execution has already started, the private Operation becomes abandoned, the
 worker may continue until the submitted synchronous call returns, and that
@@ -104,8 +104,8 @@ eventual worker result is discarded.
 The cancellation token passed to `OffloadPool#submit` follows the same model:
 
 - cancellation before worker execution prevents the submitted block from
-  starting and settles the Task as cancelled;
-- cancellation after worker execution starts settles the Task immediately, marks
+  starting and settles the TaskResult as cancelled;
+- cancellation after worker execution starts settles the TaskResult immediately, marks
   the private Operation abandoned, and allows the worker to continue;
 - cancellation does not use `Thread#raise`;
 - application code may observe the same CancellationToken and terminate its own
@@ -114,18 +114,18 @@ The cancellation token passed to `OffloadPool#submit` follows the same model:
 A submit token with a monotonic deadline is connected to the Runtime timer queue,
 so deadline expiry becomes explicit cancellation without a polling Thread.
 
-`Task#wait_result(timeout:)` is a synchronous bridge for non-EventLoop callers.
+`TaskResult#wait_result(timeout:)` is a synchronous bridge for non-EventLoop callers.
 Its timeout is waiter-local: it raises `TimeoutError` only to that caller and does
-not settle the Task, cancel the submitted operation, or mark an OffloadPool
+not settle the TaskResult, cancel the submitted operation, or mark an OffloadPool
 Operation abandoned.
 
-Framework components own Task settlement. Application code should request
+Framework components own TaskResult settlement. Application code should request
 operation-wide cancellation through the CancellationToken accepted by the API
-that created the Task rather than calling Task settlement methods directly. A
-Task cancellation must not implicitly cancel a shared CancellationToken in the
+that created the TaskResult rather than calling TaskResult settlement methods directly. A
+TaskResult cancellation must not implicitly cancel a shared CancellationToken in the
 reverse direction.
 
-Independent `Task#on_complete` notification callbacks are fault-isolated. Their
+Independent `TaskResult#on_complete` notification callbacks are fault-isolated. Their
 execution thread is not guaranteed, so callbacks must be thread-safe and should
 return quickly. Framework lifecycle code normally converts completion into an
 explicit EventLoop event.
@@ -136,7 +136,7 @@ explicit EventLoop event.
 caller-facing timeout or cancellation won after worker execution had already
 started. `offload_pool_abandoned_active` is current-state: it counts only those
 abandoned operations whose synchronous workers are still occupying OffloadPool
-capacity. Task does not expose abandonment as caller-facing completion state;
+capacity. TaskResult does not expose abandonment as caller-facing completion state;
 that distinction remains private OffloadPool execution/observability state.
 
 ## CPU-bound work
@@ -154,7 +154,7 @@ does not reintroduce a Tool-level workload class.
 A component that truly uses a native asynchronous driver and does not create a
 Phronomy-owned OS Thread does not need an OffloadPool worker. If such an
 extension point is formally introduced, it must still adapt completion into a
-`Phronomy::Task`; it must not expose provider-specific futures or private Runtime
+`Phronomy::TaskResult`; it must not expose provider-specific futures or private Runtime
 operation records as Phronomy's completion contract.
 
 The current VectorStore and Embeddings extension contracts are synchronous; their
@@ -168,14 +168,14 @@ OffloadPool worker
   → wait_result
 ```
 
-and equivalently for Workflow/ToolInvocation/Task lifecycles.
+and equivalently for Workflow/ToolInvocation/TaskResult lifecycles.
 
 The correct model is:
 
 ```text
 parent FSMSession
   → start child lifecycle
-  → return Task immediately
+  → return TaskResult immediately
   → child settles
   → post parent EventLoop event
 ```
@@ -183,8 +183,8 @@ parent FSMSession
 ## Consequences
 
 - There is one explicit framework continuation model: FSMSession + EventLoop.
-- There is one caller-facing completion abstraction: Task.
-- Task stays thread-free and represents settlement only.
+- There is one caller-facing completion abstraction: TaskResult.
+- TaskResult stays thread-free and represents settlement only.
 - OffloadPool owns bounded OS-thread execution and its private Operation state.
 - Tool execution classification remains `:cooperative` / `:offloaded`.
 - CPU/I/O classification and resource sizing are application responsibilities.

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